V4 New Features

Phaser 4 New Features

New features and capabilities in Phaser 4: Filters (replacing FX/BitmapMask), RenderNodes (replacing Pipelines), CaptureFrame, Gradient, Noise game objects, SpriteGPULayer, TilemapGPULayer, Lighting component, RenderSteps, and new tint modes.

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

Migrating from v3? See the v3 to v4 Migration Guide for step-by-step code changes, removed APIs, and a migration checklist.

Overview: What Changed in v4

Phaser 4 is a complete overhaul of the WebGL rendering engine. The v3 renderer let each subsystem manage WebGL state independently, causing conflicts (e.g. certain FX breaking Masks). v4 centralizes WebGL state management through a RenderNode graph, where each node handles exactly one rendering task.

Key Removals

Key Additions

• New GameObjects: CaptureFrame, Gradient, Noise, NoiseCell2D/3D/4D, NoiseSimplex2D/3D, SpriteGPULayer, Stamp, TilemapGPULayer
• New Components: Lighting, RenderSteps, RenderNodes
• New Tint Modes: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT
• New Filters: Blend, Blocky, CombineColorMatrix, GradientMap, ImageLight, Key, Mask, NormalTools, PanoramaBlur, ParallelFilters, Quantize, Sampler, Threshold
• GL Orientation: v4 uses standard GL orientation (Y=0 at bottom for textures)

Filters System (Replacing FX and BitmapMask)

Full reference: filters-and-postfx.md

Filters unify the v3 FX and Mask systems. Every filter takes an input image and produces an output image via a shader pass. Filters can be applied to any game object or camera -- v3 had restrictions on which objects supported FX.

// v3 approach (FX):
sprite.preFX.addGlow(0xff00ff, 4);
sprite.postFX.addBlur(0, 2, 2, 1);

// v4 approach (Filters):
sprite.enableFilters();
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);
sprite.filters.external.addBlur(0, 2, 2, 1);

// v3 approach (BitmapMask):
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskImage);
sprite.setMask(mask);

// v4 approach (FilterMask):
sprite.enableFilters();
sprite.filters.internal.addMask(maskImage);

Internal vs External: Internal filters run before the camera transform (object-local space, cheaper). External filters run after (screen space, full-resolution).

RenderNodes (Replacing Pipelines)

In v3, a Pipeline was a rendering system that often handled multiple responsibilities. In v4, each RenderNode handles a single rendering task via its run() method. Some nodes also have a batch() method to accumulate state before drawing.

Architecture

The RenderNodeManager (on the WebGL renderer) owns all render nodes. Game objects reference nodes through role-based maps.

// RenderNode roles on a game object:
// - 'Submitter': runs other node roles for each element
// - 'Transformer': provides vertex coordinates
// - 'Texturer': handles textures

// GameObjects have default and custom render node maps:
gameObject.defaultRenderNodes  // built-in nodes per role
gameObject.customRenderNodes   // overrides per role
gameObject.renderNodeData      // data keyed by node name

Setting Custom RenderNodes

// Override a specific render role:
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');

// Pass data to a render node:
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});

// Remove a custom node (falls back to default):
gameObject.setRenderNodeRole('Submitter', null);

Built-in RenderNode Types

Batch Handlers (accumulate and draw multiple objects per draw call):

• BatchHandlerQuad -- standard quad batching (Image, Sprite, BitmapText, etc.)
• BatchHandlerQuadSingle -- single-quad variant
• BatchHandlerTileSprite -- TileSprite batching
• BatchHandlerTriFlat -- flat triangle batching (Graphics, Shape)
• BatchHandlerPointLight -- point light batching
• BatchHandlerStrip -- triangle strip batching

Submitters (coordinate rendering per object type):

• SubmitterQuad, SubmitterTile, SubmitterTileSprite
• SubmitterSpriteGPULayer, SubmitterTilemapGPULayer

Transformers (compute vertex positions):

• TransformerImage, TransformerStamp, TransformerTile, TransformerTileSprite

Texturers (manage texture binding):

• TexturerImage, TexturerTileSprite

Filters (post-processing -- see filters-and-postfx.md):

• BaseFilter, BaseFilterShader
• FilterBarrel, FilterBlend, FilterBlocky, FilterBlur (Low/Med/High variants)
• FilterBokeh, FilterColorMatrix, FilterCombineColorMatrix
• FilterDisplacement, FilterGlow, FilterGradientMap, FilterImageLight
• FilterKey, FilterMask, FilterNormalTools, FilterPanoramaBlur
• FilterParallelFilters, FilterPixelate, FilterQuantize
• FilterSampler, FilterShadow, FilterThreshold, FilterVignette, FilterWipe

Other:

• Camera, FillCamera, FillRect, FillPath, FillTri
• DrawLine, StrokePath, ShaderQuad
• ListCompositor, RebindContext, YieldContext
• DynamicTextureHandler

Extending: Custom RenderNodes

// Register a custom node constructor:
renderer.renderNodes.addNodeConstructor('MyNode', MyNodeClass);

// Or add a pre-built node instance:
renderer.renderNodes.addNode('MyNode', myNodeInstance);

New Game Objects

CaptureFrame

Captures the current framebuffer contents to a texture at the point in the display list where it sits. Does not render anything itself. WebGL only.

// Everything above this in the display list gets captured:
const image1 = this.add.image(400, 300, 'background');

// Enable framebuffer usage on the camera:
this.cameras.main.setForceComposite(true);

// Create the capture point:
const capture = this.add.captureFrame('myCapturedTexture');

// Use the captured texture on another object:
const overlay = this.add.image(400, 300, 'myCapturedTexture');
// Add filters to the overlay to distort the captured scene

Key details:

• Requires camera.setForceComposite(true) or a framebuffer context (Filters, DynamicTexture, camera with partial alpha)
• Inside a Container with filters, captures only that Container's contents
• Setting visible = false stops capturing
• Components: BlendMode, Depth, RenderNodes, Visible

Source: src/gameobjects/captureframe/CaptureFrame.js

Gradient

Displays GPU-rendered color gradients. Extends Shader. Supports linear, radial, and other shape modes with configurable ColorRamp containing ColorBand objects.

// Simple linear gradient:
const grad = this.add.gradient(undefined, 100, 100, 200, 200);

// Complex radial gradient with multiple color bands:
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);

// Animate:
halo.offset = 0.1 * (1 + Math.sin(time / 1000));

Key details:

• Config: GradientQuadConfig with bands, shapeMode, repeatMode, start, shape, dither
• Colors defined via ColorRamp with ColorBand objects (supports HSV, various interpolation modes)
• Call gradient.ramp.encode() after modifying ramp data at runtime

Source: src/gameobjects/gradient/Gradient.js