v4-new-features

Novos recursos do Phaser 4

Novos recursos e funcionalidades do Phaser 4: Filtros (substituindo FX/BitmapMask), RenderNodes (substituindo Pipelines), objetos de jogo CaptureFrame, Gradient e Noise, SpriteGPULayer, TilemapGPULayer, componente de iluminação, RenderSteps e novos modos de tonalidade.

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

Está migrando da v3? Consulte o Guia de Migração da v3 para a v4 para obter instruções passo a passo sobre alterações no código, APIs removidas e uma lista de verificação para a migração.

Visão geral: o que mudou na v4

O Phaser 4 é uma reformulação completa do mecanismo de renderização WebGL. O renderizador da v3 permitia que cada subsistema gerenciasse o estado do WebGL de forma independente, causando conflitos (por exemplo, certos efeitos visuais (FX) que prejudicavam as máscaras). A v4 centraliza o gerenciamento do estado do WebGL por meio de um gráfico de RenderNodes, no qual cada nó lida com exatamente uma tarefa de renderização.

Principais remoções

Principais adições

• Novos GameObjects: CaptureFrame, Gradient, Noise, NoiseCell2D/3D/4D, NoiseSimplex2D/3D, SpriteGPULayer, Stamp, TilemapGPULayer
• Novos componentes: Lighting, RenderSteps, RenderNodes
• Novos modos de matiz: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT
• Novos filtros: Blend, Blocky, CombineColorMatrix, GradientMap, ImageLight, Key, Mask, NormalTools, PanoramaBlur, ParallelFilters, Quantize, Sampler, Threshold
• Orientação GL: a v4 usa a orientação GL padrão (Y=0 na parte inferior para texturas)

Sistema de filtros (substituindo FX e BitmapMask)

Referência completa: filters-and-postfx.md

Os filtros unificam os sistemas FX e Mask da v3. Cada filtro recebe uma imagem de entrada e produz uma imagem de saída por meio de uma passagem de shader. Os filtros podem ser aplicados a qualquer objeto de jogo ou câmera — a v3 tinha restrições quanto aos objetos compatíveis com FX.

// Abordagem da v3 (FX):
sprite.preFX.addGlow(0xff00ff, 4);
sprite.postFX.addBlur(0, 2, 2, 1);// Abordagem da v4 (Filtros):
sprite.enableFilters();
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);
sprite.filters.external.addBlur(0, 2, 2, 1);// Abordagem v3 (BitmapMask):
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskImage);
sprite.setMask(mask);// Abordagem v4 (FilterMask):
sprite.enableFilters();
sprite.filters.internal.addMask(maskImage);

Interno x Externo: os filtros internos são executados antes da transformação da câmera (espaço local do objeto, mais econômico). Os filtros externos são executados depois (espaço da tela, resolução total).

RenderNodes (Substituindo os Pipelines)

Na v3, um Pipeline era um sistema de renderização que frequentemente lidava com várias responsabilidades. Na v4, cada RenderNode lida com uma única tarefa de renderização por meio de seu método run(). Alguns nós também possuem um método batch() para acumular o estado antes do desenho.

Arquitetura

O RenderNodeManager (no renderizador WebGL) é responsável por todos os nós de renderização. Os objetos de jogo referenciam os nós por meio de mapas baseados em funções.

// Funções do RenderNode em um objeto de jogo:
// - 'Submitter': executa outras funções de nó para cada elemento
// - 'Transformer': fornece coordenadas de vértices
// - 'Texturer': lida com texturas// Os GameObjects possuem mapas de nós de renderização padrão e personalizados:
gameObject.defaultRenderNodes  // nós integrados por função
gameObject.customRenderNodes   // substituições por função
gameObject.renderNodeData      // dados indexados pelo nome do nó

Configurando nós de renderização personalizados

// Substituir uma função de renderização específica:
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');// Passar dados para um nó de renderização:
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});// Remover um nó personalizado (volta ao padrão):
gameObject.setRenderNodeRole('Submitter', null);

Tipos de RenderNode integrados

Manipuladores de lote (acumulam e desenham vários objetos por chamada de desenho):

• BatchHandlerQuad — agrupamento padrão de quadriláteros (Image, Sprite, BitmapText, etc.)
• BatchHandlerQuadSingle — variante para um único quad
• BatchHandlerTileSprite — agrupamento de TileSprite
• BatchHandlerTriFlat — agrupamento de triângulos planos (Graphics, Shape)
• BatchHandlerPointLight — processamento em lote de luzes pontuais
• BatchHandlerStrip — processamento em lote de faixas de triângulos

Submitters (renderização coordenada por tipo de objeto):

• SubmitterQuad, SubmitterTile, SubmitterTileSprite
• SubmitterSpriteGPULayer, SubmitterTilemapGPULayer

Transformadores (cálculo das posições dos vértices):

• TransformerImage, TransformerStamp, TransformerTile, TransformerTileSprite

Texturizadores (gerenciam a vinculação de texturas):

• TexturerImage, TexturerTileSprite

Filtros (pós-processamento — consulte filters-and-postfx.md):

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

Outros:

• Câmera, PreencherCâmera, PreencherRetângulo, PreencherTrajetória, PreencherTriângulo
• DrawLine, StrokePath, ShaderQuad
• ListCompositor, RebindContext, YieldContext
• DynamicTextureHandler

Estendendo: RenderNodes personalizados

// Registrar um construtor de nó personalizado:
renderer.renderNodes.addNodeConstructor('MyNode', MyNodeClass);// Ou adicionar uma instância de nó pré-criada:
renderer.renderNodes.addNode('MyNode', myNodeInstance);

Novos objetos de jogo

CaptureFrame

Captura o conteúdo atual do framebuffer para uma textura no ponto da lista de exibição em que se encontra. Não renderiza nada por si só. Apenas WebGL.

// Tudo acima disso na lista de exibição é capturado:
const image1 = this.add.image(400, 300, 'background');// Habilite o uso do framebuffer na câmera:
this.cameras.main.setForceComposite(true);// Crie o ponto de captura:
const capture = this.add.captureFrame('myCapturedTexture');// Use a textura capturada em outro objeto:
const overlay = this.add.image(400, 300, 'myCapturedTexture');
// Adicione filtros à sobreposição para distorcer a cena capturada

Detalhes importantes:

• Requer camera.setForceComposite(true) ou um contexto de framebuffer (Filtros, DynamicTexture, câmera com alfa parcial)
• Dentro de um Container com filtros, captura apenas o conteúdo desse Container
• Definir ` visible = false ` interrompe a captura
• Componentes: BlendMode, Depth, RenderNodes, Visible

Fonte: src/gameobjects/captureframe/CaptureFrame.js

Gradiente

Exibe gradientes de cor renderizados pela GPU. Estende Shader. Suporta modos linear, radial e outros modos de forma com ColorRamp configurável contendo objetos ColorBand.

// Gradiente linear simples:
const grad = this.add.gradient(undefined, 100, 100, 200, 200);// Gradiente radial complexo com várias faixas de cor:
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);// Animação:
halo.offset = 0,1 * (1 + Math.sin(time / 1000));

Detalhes importantes:

• Configuração: GradientQuadConfig com bandas, shapeMode, repeatMode, start, shape, dither
• Cores definidas via ColorRamp com objetos ColorBand (suporta HSV e vários modos de interpolação)
• Chame gradient.ramp.encode() após modificar os dados da rampa em tempo de execução

Fonte: src/gameobjects/gradient/Gradient.js

Objetos de jogo com ruído

Todos os tipos de ruído estendem Shader e são exclusivos do WebGL. Seis variantes disponíveis:

// Ruído branco básico:
const noise = this.add.noise({
    noiseOffset: [0, 0],
    noisePower: 1
}, 100, 100, 256, 256);// Ruído celular com personalização:
const cells = this.add.noiseCell2D({
    noiseOffset: [0, 0],
   noiseIterations: 3,
    noiseNormalMap: true    // saída como mapa normal para iluminação
}, 200, 200, 256, 256);// Ruído simplex para efeitos naturais:
const simplex = this.add.noiseSimplex2D({
    noiseFlow: 0,           // anime isso para evolução
   noiseIterations: 4,
    noiseWarpAmount: 0.5,   // turbulência
    noiseSeed: 42,
    noiseNormalMap: false
}, 300, 300, 256, 256);

Propriedades comuns a todos os tipos de ruído:

• noiseOffset — matriz [x, y] para deslocar o padrão
• noisePower — modula os níveis de saída (valores mais altos suprimem valores elevados)
• noiseNormalMap — mapa normal de saída (para integração com iluminação)
• noiseIterations — nível de detalhe (tipos celular/simplex)

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

Fonte: src/gameobjects/noise/

SpriteGPULayer

Renderiza um número muito grande de quadriláteros (até milhões) em uma única chamada de renderização, armazenando dados em um buffer estático da GPU. Até 100 vezes mais rápido do que sprites individuais. Apenas WebGL.

const layer = this.add.spriteGPULayer(texture, size); // size = número máximo de membros// Adicione membros (faça isso de uma só vez, não de forma incremental):
const member = { x: 100, y: 200, frame: 'tree', scaleX: 1, scaleY: 1, alpha: 1 };
layer.addMember(member);// Reutilize o objeto membro para maior eficiência com milhões de entradas:
member.x = 300;
member.y = 400;
member.frame = 'bush';
layer.addMember(member);// Ative a iluminação na camada:
layer.setLighting(true);

Detalhes importantes:

• Apenas uma textura (sem multi-atlas), uma imagem por camada
• Os membros suportam animações do tipo tween (fade, bounce, wave, mudança de cor) definidas na criação
• Atualizar o conteúdo do buffer é dispendioso — preencha uma vez e deixe inalterado
• Recomenda-se o uso de texturas com dimensões que sejam potências de dois para pixel art, a fim de evitar costuras
• “Remova” membros visualmente definindo scaleX/scaleY/alpha como 0 (evita a reconstrução do buffer)
• Componentes: Alpha, BlendMode, Depth, ElapseTimer, Lighting, Mask, RenderNodes, TextureCrop, Visible

Fonte: src/gameobjects/spritegpulayer/SpriteGPULayer.js

Novos componentes

Referência completa dos componentes: game-object-components.md

Componente de iluminação

Substitui a abordagem da v3 de atribuir um pipeline de iluminação. Apenas para WebGL.

// Abordagem v3:
sprite.setPipeline('Light2D');// Abordagem v4:
sprite.setLighting(true);// Auto-sombreamento (simula sombras de superfície a partir do brilho da textura):
sprite.setSelfShadow(true, 0.5,1/3);
// Argumentos: enabled, penumbra (valor mais baixo = mais nítido), diffuseFlatThreshold (0-1)// Usa o padrão do jogo para auto-sombra:
sprite.setSelfShadow(null);  // lê a partir de config.render.selfShadow

Compatível com: BitmapText, Blitter, Graphics, Shape, Image, Sprite, Particles, SpriteGPULayer, Stamp, Text, TileSprite, Video, TilemapLayer, TilemapGPULayer.

Observação sobre agrupamento: a iluminação altera o shader, o que interrompe os agrupamentos. Agrupe objetos iluminados e objetos não iluminados separadamente para obter melhor desempenho.

Fonte: src/gameobjects/components/Lighting.js

Componente RenderSteps

Permite injetar lógica personalizada no processo de renderização de um objeto de jogo. Apenas WebGL. O sistema de Filtros utiliza o RenderSteps internamente.

// Adicione uma etapa de renderização personalizada:
gameObject.addRenderStep(function (renderer, gameObject, drawingContext, parentMatrix, renderStep, displayList, displayListIndex) {
    // Lógica de renderização personalizada aqui
    // Chame a próxima etapa quando estiver pronto:
   var nextFn = gameObject._renderSteps[renderStep + 1];
    if (nextFn) {
        nextFn(renderer, gameObject, drawingContext, parentMatrix, renderStep + 1, displayList, displayListIndex);
    }
});

Detalhes importantes:

• As etapas são armazenadas na matriz _renderSteps e executadas por meio de renderWebGLStep()
• A primeira etapa é executada primeiro e é responsável por chamar as etapas subsequentes
• É assim que os filtros diferem e controlam o fluxo do renderWebGL

Fonte: src/gameobjects/components/RenderSteps.js

Componente RenderNodes

Fornece os mapas defaultRenderNodes, customRenderNodes e renderNodeData nos objetos do jogo. Consulte a seção RenderNodes acima para saber como usá-los.

Fonte: src/gameobjects/components/RenderNodes.js

TilemapGPULayer

Referência completa sobre tilemap: tilemaps.md

Renderização de mapa de blocos baseada em GPU de alto desempenho. Renderiza toda a camada como um único quadrilátero por meio de um shader especializado. Apenas WebGL.

// Crie por meio do Tilemap com o sinalizador 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

Recursos:

• Conjunto de blocos único com uma única imagem de textura
• Máximo de 4096x4096 blocos, até 2^23 IDs de blocos únicos
• Suporte à inversão de blocos e animação
• Apenas mapas de blocos ortogonais (sem isométricos/hexagonais)
• Filtragem perfeita de texturas no modo LINEAR (sem emendas entre blocos)
• O custo é por pixel, não por bloco — sem perda de desempenho mesmo com muitos blocos visíveis

Restrições:

• Não é possível usar vários conjuntos de blocos
• A edição requer uma chamada manual de ` generateLayerDataTexture() ` para atualizar
• Apenas ortográfica

Dados internos: Os dados dos blocos são armazenados em uma textura (4 bytes por bloco: 2 bits de inversão, 1 bit de animação, 1 bit não utilizado e índice de bloco de 28 bits). Os dados de animação ficam em uma textura separada.

Fonte: src/tilemaps/TilemapGPULayer.js

Para opções detalhadas de configuração, tabelas de referência da API e mapas de arquivos-fonte, consulte o guia de referência.