Texture Pinning (API)

Los activos de textura de Roblox se cargan de forma diferida. La primera vez que un id de activo aparece en pantalla, Roblox obtiene los bytes, decodifica la imagen, la sube a la GPU y luego la renderiza. Ese viaje de ida y vuelta puede provocar un tirón de un solo fotograma en la primera emisión de un efecto con una textura nueva.

Un problema más sutil sigue a continuación. Incluso después de que Roblox decodifique los bytes, puede posteriormente desalojarlos bajo presión de memoria si ninguna instancia visible sigue referenciando el id del activo. Así que una textura ya decodificada puede volver a producir tirones en su segunda aparición, horas más tarde, tras un período de uso intensivo.

El sistema de anclaje de texturas del plugin gestiona ambas situaciones: una precarga anticipada, más una referencia persistente que evita el desalojo. El truco consiste en una referencia de interfaz oculta y casi invisible a cada id de activo anclado — el renderizador sigue contándola como un consumidor activo del activo, por lo que los bytes permanecen residentes.

Particle:Preload(root, force)

Recorre cada elemento transformado más cada ParticleEmitter y Trail bajo root, recopila sus ids de activos de textura y ancla cada uno. Retorna inmediatamente; la decodificación se inicia en un task.spawn en segundo plano (para que una precarga larga no bloquee tu script).

local root = workspace.SwordEffects
Part_Icles:Preload(root, true)
-- now any emit under SwordEffects is texture-warm

El parámetro force controla qué elementos bajo root son elegibles:

• force = false (predeterminado) — solo se anclan los elementos que tienen el atributo PreloadTexture establecido en true. Funciona junto con el interruptor por emisor PreloadTexture: cada efecto se registra voluntariamente en el momento de la autoría, y luego una sola llamada :Preload a nivel de árbol calienta exactamente el conjunto registrado.
• force = true — cada elemento transformado / PE / Trail bajo root se ancla, independientemente del atributo. Úsalo cuando quieras un calentamiento masivo sin establecer indicadores por elemento.

Si no se ha establecido PreloadTexture en ningún lugar bajo root y no pasas force = true, nada se ancla y la llamada es un no-op silencioso.

Particle:Deload(root, force)

Inverso de :Preload. Recorre la misma jerarquía y libera la reclamación de este root sobre cada activo anclado bajo él. El parámetro force se comporta de manera idéntica al de :Preload — false respeta PreloadTexture, true barre cada elemento transformado / PE / Trail.

Part_Icles:Deload(root, true)

Los anclajes se cuentan por referencia por id de activo. Si dos raíces anclaron la misma textura, descargar una raíz mantiene la textura anclada mediante la reclamación de la otra raíz. El anclaje solo se libera (y la textura vuelve a ser desalojable) cuando el último propietario hace deload.

Úsalo tras una transición de nivel, o cuando un conjunto de efectos no vaya a aparecer más en esta sesión. En dispositivos con memoria limitada, esto te permite recuperar el presupuesto para el siguiente conjunto.

Combinado con el atributo PreloadTexture

El atributo PreloadTexture por emisor (interruptor en la sección Advanced de Part / Beam / ImageLabel / Model) es el indicador de participación voluntaria. La API de script impulsa el barrido de anclaje. Los Models obtuvieron el interruptor PreloadTexture a partir de la v33; las versiones anteriores solo lo exponían en Part / Beam / ImageLabel.

Un patrón típico:

-- Game start: warm everything tagged for this session.
Part_Icles:Preload(ReplicatedStorage.Effects)

-- Player joins arena 1: warm arena-specific effects.
Part_Icles:Preload(ReplicatedStorage.Arenas.Castle.Effects)

-- Player leaves arena 1, enters arena 2: release arena 1, warm arena 2.
Part_Icles:Deload(ReplicatedStorage.Arenas.Castle.Effects)
Part_Icles:Preload(ReplicatedStorage.Arenas.Forest.Effects)

Todas estas llamadas usan force = false por defecto, por lo que cada una calienta exactamente los elementos que el artista registró voluntariamente mediante PreloadTexture.

El anclaje es por id de activo, no por instancia — anclar el mismo id de textura en dos carpetas comparte el calentamiento. La decodificación ocurre una sola vez.

Las duraciones de los anclajes se rastrean por propietario. En Studio, el plugin observa los padres comunes (Workspace, ServerStorage, ReplicatedStorage, StarterPack, ReplicatedFirst) y libera automáticamente la reclamación de un anclaje cuando su instancia propietaria se elimina — de modo que las eliminaciones en tiempo de autoría no dejan referencias de textura huérfanas. El runtime publicado que vive en tu juego publicado no conecta esa liberación automática; en un juego publicado, llama a :Deload(root) explícitamente cuando un conjunto de emisores se retira, o llama a :Deactivate para borrar todos los anclajes de una vez.

Qué sigue

Con la API documentada, el último capítulo — Ejemplos — recorre cuatro patrones comunes: chispa de espadazo, clon de bola de fuego desde el almacenamiento, emisión solo en pantalla para el rendimiento, y :AbsoluteEmit recursivo para jerarquías anidadas.