v4-new-features

Nuevas funciones de Phaser 4

Nuevas funciones y capacidades de Phaser 4: Filtros (que sustituyen a FX/BitmapMask), RenderNodes (que sustituyen a Pipelines), los objetos de juego CaptureFrame, Gradient y Noise, SpriteGPULayer, TilemapGPULayer, el componente Lighting, RenderSteps y nuevos modos de tinte.

Habilidades relacionadas:../v3-to-v4-migration/SKILL.md, ../filters-and-postfx/SKILL.md, ../game-object-components/SKILL.md, ../tilemaps/SKILL.md

¿Estás migrando desde la v3? Consulta la Guía de migración de la v3 a la v4 para conocer los cambios en el código paso a paso, las API eliminadas y una lista de comprobación para la migración.

Resumen: qué ha cambiado en la v4

Phaser 4 supone una revisión completa del motor de renderizado WebGL. El renderizador de la v3 permitía que cada subsistema gestionara el estado de WebGL de forma independiente, lo que provocaba conflictos (por ejemplo, ciertos efectos especiales que rompían las máscaras). La v4 centraliza la gestión del estado de WebGL a través de un grafo de RenderNodes, en el que cada nodo se encarga exactamente de una tarea de renderizado.

Eliminaciones clave

Novedades clave

• Nuevos GameObjects: CaptureFrame, Gradient, Noise, NoiseCell2D/3D/4D, NoiseSimplex2D/3D, SpriteGPULayer, Stamp, TilemapGPULayer
• Nuevos componentes: Lighting, RenderSteps, RenderNodes
• Nuevos modos de tinte: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT
• Nuevos filtros: Blend, Blocky, CombineColorMatrix, GradientMap, ImageLight, Key, Mask, NormalTools, PanoramaBlur, ParallelFilters, Quantize, Sampler, Threshold
• Orientación GL: la v4 utiliza la orientación GL estándar (Y=0 en la parte inferior para las texturas)

Sistema de filtros (sustituye a FX y BitmapMask)

Referencia completa: filters-and-postfx.md

Los filtros unifican los sistemas FX y Mask de la v3. Cada filtro toma una imagen de entrada y genera una imagen de salida mediante un paso de shader. Los filtros se pueden aplicar a cualquier objeto del juego o cámara; la v3 tenía restricciones sobre qué objetos admitían FX.

// Enfoque de la v3 (FX):
sprite.preFX.addGlow(0xff00ff, 4);
sprite.postFX.addBlur(0, 2, 2, 1);// Enfoque de la v4 (filtros):
sprite.enableFilters();
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);
sprite.filters.external.addBlur(0, 2, 2, 1);// Enfoque v3 (BitmapMask):
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskImage);
sprite.setMask(mask);// Método v4 (FilterMask):
sprite.enableFilters();
sprite.filters.internal.addMask(maskImage);

Internos frente a externos: los filtros internos se ejecutan antes de la transformación de la cámara (espacio local del objeto, más eficiente). Los filtros externos se ejecutan después (espacio de pantalla, resolución completa).

RenderNodes (sustitución de los pipelines)

En la v3, un Pipeline era un sistema de renderizado que a menudo se encargaba de múltiples responsabilidades. En la v4, cada RenderNode se encarga de una única tarea de renderizado a través de su método run(). Algunos nodos también disponen de un método batch() para acumular el estado antes de dibujar.

Arquitectura

El RenderNodeManager (en el renderizador WebGL) es el responsable de todos los nodos de renderizado. Los objetos del juego hacen referencia a los nodos a través de mapas basados en roles.

// Roles de RenderNode en un objeto del juego:
// - «Submitter»: ejecuta otros roles de nodo para cada elemento
// - «Transformer»: proporciona coordenadas de vértices
// - «Texturer»: gestiona las texturas// Los GameObjects tienen mapas de nodos de renderizado predeterminados y personalizados:
gameObject.defaultRenderNodes  // nodos integrados por rol
gameObject.customRenderNodes   // sustituciones por rol
gameObject.renderNodeData      // datos indexados por nombre de nodo

Configuración de nodos de renderizado personalizados

// Anular una función de renderizado específica:
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');// Pasar datos a un nodo de renderizado:
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});// Eliminar un nodo personalizado (se vuelve al valor por defecto):
gameObject.setRenderNodeRole('Submitter', null);

Tipos de nodos de renderizado integrados

Manejadores de lotes (acumulan y dibujan varios objetos por llamada de dibujo):

• BatchHandlerQuad: procesamiento por lotes de cuádruples estándar (Image, Sprite, BitmapText, etc.)
• BatchHandlerQuadSingle: variante de un solo cuadrilátero
• BatchHandlerTileSprite: agrupamiento de TileSprite
• BatchHandlerTriFlat: procesamiento por lotes de triángulos planos (Graphics, Shape)
• BatchHandlerPointLight: procesamiento por lotes de luces puntuales
• BatchHandlerStrip: procesamiento por lotes de tiras de triángulos

Enviadores (renderizado coordinado por tipo de objeto):

• SubmitterQuad, SubmitterTile, SubmitterTileSprite
• SubmitterSpriteGPULayer, SubmitterTilemapGPULayer

Transformadores (cálculo de posiciones de vértices):

• TransformerImage, TransformerStamp, TransformerTile, TransformerTileSprite

Texturizadores (gestionan la asignación de texturas):

• TexturerImage, TexturerTileSprite

Filtros (posprocesado —véase filters-and-postfx.md—):

• BaseFilter, BaseFilterShader
• FilterBarrel, FilterBlend, FilterBlocky, FilterBlur (variantes Baja/Media/Alta)
• FilterBokeh, FilterColorMatrix, FilterCombineColorMatrix
• FilterDisplacement, FilterGlow, FilterGradientMap, FilterImageLight
• FilterKey, FilterMask, FilterNormalTools, FilterPanoramaBlur
• FilterParallelFilters, FilterPixelate, FilterQuantize
• FilterSampler, FilterShadow, FilterThreshold, FilterVignette, FilterWipe

Otros:

• Cámara, RellenarCámara, RellenarRectángulo, RellenarTrayectoria, RellenarTriángulo
• DibujarLínea, TrazarTrayecto, ShaderCuadrado
• ListCompositor, RebindContext, YieldContext
• Gestor de texturas dinámicas

Extensión: Nodos de renderizado personalizados

// Registrar un constructor de nodo personalizado:
renderer.renderNodes.addNodeConstructor('MyNode', MyNodeClass);// O añadir una instancia de nodo preconstruida:
renderer.renderNodes.addNode('MyNode', myNodeInstance);

Nuevos objetos de juego

CaptureFrame

Captura el contenido actual del búfer de fotogramas en una textura en el punto de la lista de visualización en el que se encuentra. No renderiza nada por sí mismo. Solo WebGL.

// Se captura todo lo que está por encima de esto en la lista de visualización:
const image1 = this.add.image(400, 300, 'background');// Habilita el uso del búfer de fotogramas en la cámara:
this.cameras.main.setForceComposite(true);// Crea el punto de captura:
const capture = this.add.captureFrame('myCapturedTexture');// Utiliza la textura capturada en otro objeto:
const overlay = this.add.image(400, 300, 'myCapturedTexture');
// Añade filtros a la superposición para distorsionar la escena capturada

Detalles clave:

• Requiere camera.setForceComposite(true) o un contexto de framebuffer (filtros, DynamicTexture, cámara con alfa parcial)
• Dentro de un contenedor con filtros, solo se captura el contenido de ese contenedor
• Establecer visible = false detiene la captura
• Componentes: BlendMode, Depth, RenderNodes, Visible

Fuente: src/gameobjects/captureframe/CaptureFrame.js

Gradiente

Muestra degradados de color renderizados por la GPU. Hereda de Shader. Admite modos lineales, radiales y de otras formas con una rampa de color configurable que contiene objetos ColorBand.

// Degradado lineal sencillo:
const grad = this.add.gradient(undefined, 100, 100, 200, 200);// Degradado radial complejo con varias bandas de color:
const halo = this.add.gradient({
   bands: [
        { start: 0.5, end: 0.6, colorStart: [0.5, 0.5, 1, 0], colorEnd: 0xffffff, colorSpace: 1, interpolation: 4 },
        { start: 0,6, end: 1, colorStart: 0xffffff, colorEnd: [1, 0, 5, 0 ,5, 0], colorSpace: 1, interpolation: 3 }
    ],
    dither: true,
    repeatMode: 1,
    shapeMode: 2,       // radial
    start: { x: 0.5, y: 0.5 },
    shape: { x: 0.5, y: 0.0 }
}, 400, 300, 800, 800);// Animación:
halo.offset = 0,1 * (1 + Math.sin(tiempo / 1000));

Detalles clave:

• Configuración: GradientQuadConfig con bandas, shapeMode, repeatMode, inicio, forma y dither
• Colores definidos mediante ColorRamp con objetos ColorBand (admite HSV y varios modos de interpolación)
• Llama a gradient.ramp.encode() tras modificar los datos de la rampa en tiempo de ejecución

Fuente: src/gameobjects/gradient/Gradient.js

Objetos de juego con ruido

Todos los tipos de ruido heredan de Shader y son exclusivos de WebGL. Hay seis variantes disponibles:

// Ruido blanco básico:
const noise = this.add.noise({
    noiseOffset: [0, 0],
    noisePower: 1
}, 100, 100, 256, 256);// Ruido celular con personalización:
const cells = this.add.noiseCell2D({
    noiseOffset: [0, 0],
   noiseIterations: 3,
    noiseNormalMap: true    // salida como mapa normal para la iluminación
}, 200, 200, 256, 256);// Ruido simplex para efectos naturales:
const simplex = this.add.noiseSimplex2D({
    noiseFlow: 0,           // animar esto para la evolución
   iteracionesDeRuido: 4,
    cantidadDeDeformaciónDelRuido: 0,5,   // turbulencia
    semillaDeRuido: 42,
    mapaNormalDeRuido: false
}, 300, 300, 256, 256);

Propiedades comunes a todos los tipos de ruido:

• noiseOffset -- matriz [x, y] para desplazar el patrón
• noisePower -- modula los niveles de salida (un valor más alto suprime los valores elevados)
• noiseNormalMap: mapa normal de salida (para la integración de la iluminación)
• noiseIterations -- nivel de detalle (tipos celular/simplex)

Equivalentes matemáticos: Phaser.Math.Hash(), Phaser.Math.HashCell(), Phaser.Math.HashSimplex()

Fuente: src/gameobjects/noise/

SpriteGPULayer

Renderiza un gran número de cuádros (hasta millones) en una sola llamada de dibujo almacenando los datos en un búfer estático de la GPU. Hasta 100 veces más rápido que los sprites individuales. Solo para WebGL.

const layer = this.add.spriteGPULayer(texture, size); // size = número máximo de miembros// Añadir miembros (hazlo todo de una vez, no de forma incremental):
const miembro = { x: 100, y: 200, frame: 'tree', scaleX: 1, scaleY: 1, alpha: 1 };
layer.addMember(member);// Reutiliza el objeto miembro para mayor eficiencia con millones de entradas:
member.x = 300;
member.y = 400;
member.frame = 'bush';
layer.addMember(member);// Activa la iluminación en la capa:
layer.setLighting(true);

Detalles clave:

• Solo una textura (sin multi-atlas), una sola imagen por capa
• Los miembros admiten animaciones tipo «tween» (fundido, rebote, onda, cambio de color) definidas en el momento de su creación
• Actualizar el contenido del búfer es costoso: rellénalo una vez y déjalo sin cambios
• Se recomiendan texturas con dimensiones que sean potencias de dos para el pixel art, a fin de evitar que se vean las uniones
• «Elimina» elementos visualmente estableciendo scaleX/scaleY/alpha en 0 (evita la reconstrucción del búfer)
• Componentes: Alpha, BlendMode, Depth, ElapseTimer, Lighting, Mask, RenderNodes, TextureCrop, Visible

Fuente: src/gameobjects/spritegpulayer/SpriteGPULayer.js

Nuevos componentes

Referencia completa de componentes: game-object-components.md

Componente de iluminación

Sustituye el enfoque de la v3 de asignar un canal de iluminación. Solo para WebGL.

// Enfoque de la v3:
sprite.setPipeline('Light2D');// Enfoque de la v4:
sprite.setLighting(true);// Autosombras (simula las sombras de superficie a partir del brillo de la textura):
sprite.setSelfShadow(true, 0.5,1/3);
// Argumentos: enabled, penumbra (cuanto menor, más nítida), diffuseFlatThreshold (0-1)// Utiliza el valor predeterminado para todo el juego en cuanto a auto-sombra:
sprite.setSelfShadow(null);  // lee el valor de config.render.selfShadow

Compatible con: BitmapText, Blitter, Graphics, Shape, Image, Sprite, Particles, SpriteGPULayer, Stamp, Text, TileSprite, Video, TilemapLayer, TilemapGPULayer.

Nota sobre el procesamiento por lotes: la iluminación cambia el sombreador, lo que rompe los lotes. Agrupa los objetos iluminados entre sí y los no iluminados entre sí para obtener el mejor rendimiento.

Fuente: src/gameobjects/components/Lighting.js

Componente RenderSteps

Permite inyectar lógica personalizada en el proceso de renderizado de un objeto de juego. Solo para WebGL. El sistema de filtros utiliza RenderSteps internamente.

// Añadir un paso de renderizado personalizado:
gameObject.addRenderStep(function (renderer, gameObject, drawingContext, parentMatrix, renderStep, displayList, displayListIndex) {
    // Lógica de renderizado personalizada aquí
    // Llamar al siguiente paso cuando esté listo:
   var nextFn = gameObject._renderSteps[renderStep + 1];
    if (nextFn) {
        nextFn(renderer, gameObject, drawingContext, parentMatrix, renderStep + 1, displayList, displayListIndex);
    }
});

Detalles clave:

• Los pasos se almacenan en el array _renderSteps y se ejecutan mediante renderWebGLStep()
• El primer paso se ejecuta primero y se encarga de llamar a los pasos siguientes
• Así es como los filtros difieren y controlan el flujo de renderWebGL

Fuente: src/gameobjects/components/RenderSteps.js

Componente RenderNodes

Proporciona los mapas `defaultRenderNodes`, `customRenderNodes` y `renderNodeData ` en los objetos del juego. Consulta la sección «RenderNodes» anterior para conocer su uso.

Fuente: src/gameobjects/components/RenderNodes.js

TilemapGPULayer

Referencia completa sobre mapas de mosaicos: tilemaps.md

Renderizado de mapas de mosaicos de alto rendimiento basado en la GPU. Renderiza toda la capa como un único cuadrilátero mediante un shader especializado. Solo para WebGL.

// Crear mediante Tilemap con el indicador «gpu»:
const map = this.make.tilemap({ key: 'level1' });
const tileset = map.addTilesetImage('tiles', 'tilesImage');
const gpuLayer = map.createLayer('Ground', tileset, 0, 0, true);  // último argumento: gpu = true

Capacidades:

• Un único conjunto de mosaicos con una única imagen de textura
• Máximo de 4096x4096 fichas, hasta 2^23 ID de fichas únicos
• Admite rotación de mosaicos y animación
• Solo mapas de mosaicos ortográficos (no isométricos ni hexagonales)
• Filtrado perfecto de texturas en modo LINEAL (sin costuras entre mosaicos)
• El coste es por píxel, no por mosaico: no hay pérdida de rendimiento aunque haya muchos mosaicos visibles

Restricciones:

• No se pueden utilizar varios conjuntos de mosaicos
• La edición requiere una llamada manual a generateLayerDataTexture() para actualizar
• Solo ortográfico

Datos internos: Los datos de los mosaicos se almacenan en una textura (4 bytes por mosaico: 2 bits de inversión, 1 bit de animación, 1 sin usar e índice de mosaico de 28 bits). Los datos de animación se almacenan en una textura independiente.

Fuente: src/tilemaps/TilemapGPULayer.js

Para conocer las opciones de configuración detalladas, las tablas de referencia de la API y los mapas de archivos fuente, consulta la guía de referencia.