v4-new-features

What this skill does

# 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.

```js
// 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.

```js
// 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

```js
// 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

```js
// 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.

```js
// 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.

```js
// 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`,