/v4-new-features

name: v4-new-features
description: "Use this skill when learning about new features, game objects, components, and rendering capabilities added in Phaser 4. Covers Filters, RenderNodes, CaptureFrame, Gradient, Noise, SpriteGPULayer, TilemapGPULayer, Lighting component, RenderSteps, and new tint modes. Triggers on: new in v4, Phaser 4 features, RenderNode, SpriteGPULayer, CaptureFrame, Gradient game object, Noise game object, new tint modes. For migrating v3 code to v4, see the v3-to-v4-migration skill instead."

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](../v3-to-v4-migration/SKILL.md) 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

| v3 Feature | v4 Replacement | |---|---| | `Pipeline` | `RenderNode` (per-task rendering nodes) | | FX (`preFX` / `postFX`) | Filters (`filters.internal` / `filters.external`) | | `BitmapMask` | `FilterMask` (via filters system) | | `GeometryMask` (WebGL) | `FilterMask` (Canvas still uses GeometryMask) | | Derived FX: Bloom, Circle, Gradient, Shine | Actions (`AddEffectBloom`, `AddEffectShine`, `AddMaskShape`) or GameObjects | | `Mesh` and `Plane` | Removed (proper 3D planned for future) | | `Point` | Use `Vector2` instead |

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`, `FilterPixelat