# phaser: what changed from 3 to 4

- Product: phaser (https://whatsnew.fyi/product/phaser)
- Vendor: phaserjs
- Range: changelog entries numbered after v3.90.0 up to and including v4.2.1, stable releases only
- Entries below: 4 releases (newest first)
- Resolved: 3 is v3.90.0 and 4 is v4.2.1, the newest stable release of each major we track
- Carrying security changes: 0 · CVEs mentioned: 0 · Mentioning breaking changes: 0 · Removing or deprecating something: 0
- Page: https://whatsnew.fyi/product/phaser/compare/3...4

What's New is an index, not a publisher: every entry below links to the vendor's own release notes, which are the authoritative source. Entries are labelled where they are hand-curated sample data, pre-releases, or drawn from a secondary source such as a developer blog.

Reuse: the summaries, labels and curation here are © What's New. Quote freely with attribution and a link back; wholesale republication of the corpus is not permitted — terms: https://whatsnew.fyi/terms. The vendors' own release notes remain their publishers'.

## What changed (48 changes, grouped by kind)

### Added

#### v4.2.0 (2026-06-19)

- New game config options render.alphaStrategy, render.stencil, and render.stencilAlphaStrategy for controlling alpha handling and stencil buffer creation
- CustomContext game object to modify DrawingContext at render time, enabling stencil testing, alpha handling strategies, and GL scissor modification
- Mesh2D game object to render textured triangles with batching support for regular sprites
- Mesh2D#buildOrderedIndices method to precompute optimized index lists for triangle-to-quad arrangements with configurable optimization strategies
- Mesh2D#useOrderedIndices and Mesh2D#setUseOrderedIndices to toggle between ordered and unordered index lists without rebuilding
- Mesh2D#renderAsTriangles and Mesh2D#setRenderAsTriangles to render mesh as individual triangles via BatchHandlerTri
- BatchHandlerTri render node to draw individual textured triangles as a batch, extending BatchHandlerQuad with a batchTriangles method
- TransformerVertex render node now splits per-vertex run into setupMatrix and transformVertex to cache transform matrices for mesh rendering
- Stencil game object as a persistent container whose contents modify the stencil buffer with operating modes including addLayer, subtractLayer, clear, and clearRegion
- StencilReference game object to re-render a target Stencil with different settings
- AlphaStrategy setting to use GLSL discard instead of alpha in shaders, with strategies including keep, dither, and threshold
- BatchHandler render node now supports config option for topology to allow extended nodes to opt into different triangulation modes
- DrawingContext now includes controls for alpha strategy, color writemask, and stencil parameters
- WebGLGlobalWrapper now handles stencil write mask
- TintModes.MULTIPLY_TWO tint mode using a secondary color for new tint effects
- Game objects with Tint component now support second tint per corner with tint2TopLeft properties and setTint2() method
- Mesh2D and Tile objects support constant tint via tint2
- Timestep#setFPSLimit method to change the frame rate at runtime with proper property updates
- Cone lights as directional light sources with coneEnabled, coneRotation, coneInnerAngle, and coneOuterAngle properties

#### v4.1.0 (2026-04-30)

- RenderConfig#mipmapRegeneration option allows certain framebuffer-based objects to use mipmaps if the game is configured to use mipmaps
- Layer is now a true GameObject
- Base filter Controller now has getPaddingCeil() method which returns the ceiling of the current padding

#### v4.0.0 (2026-04-10)

- Add Filter system with Blur, Glow, Shadow, Pixelate, ColorMatrix, Bloom, Vignette, Wipe, ImageLight, GradientMap, Quantize, and Blend filters
- Add SpriteGPULayer to render millions of sprites in a single draw call with GPU-driven animations on position, rotation, scale, alpha, tint, and frame
- Add TilemapGPULayer to render entire tilemap layers as a single quad with support for up to 4096 x 4096 tiles
- Add new game objects: Gradient, Noise (Cell 2D/3D/4D, Simplex 2D/3D), CaptureFrame, and Stamp

### Changed

#### v4.2.0 (2026-06-19)

- inTintEffect shader attribute changed from float to vec4 with encoding changed from float32 to four uint8s in ApplyTint shader addition
- WebGLStencilParametersFactory now takes an extra writeMask parameter

#### v4.1.0 (2026-04-30)

- Filter controllers should use getPaddingCeil() instead of getPadding() for custom render nodes

#### v4.0.0 (2026-04-10)

- Replace v3 pipeline system with a new node-based renderer where each render node handles a single task with fully managed WebGL state and built-in context restoration
- Unify FX and Masks from v3 into a single powerful Filter system applicable to any game object or camera
- Overhaul tint system with six tint modes: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT, separating color and mode as distinct concerns
- Improve lighting system to be activated with sprite.setLighting(true) with self-shadows and explicit light height support across most game objects
- Implement cleaner config-based Shader API with #pragma GLSL directive support
- Enhance TileSprite to support atlas frames and tile rotation

### Fixed

#### v4.2.1 (2026-07-09)

- Stencil option stencilInvert now works correctly
- Framebuffers now correctly clear stencil on use by enabling write mask by default
- Remove inline access of Phaser namespace from CombineColorMatrix, ImageLight, and Texture to prevent breaking in ESM build
- Fix ScaleManager not resizing to parent container
- Correct AnimationManager get() return type in documentation
- Tweens with a startDelay set now have their state updated from START_DELAY to ACTIVE

#### v4.1.0 (2026-04-30)

- Fix reversions in rounded rectangle handling
- Remove duplicate function definition and exposed internal code docs from RectangleCanvasRenderer
- Fix duplicate texture name resulting from RenderTexture#saveTexture
- Fix framebuffers in filters and DynamicTextures using mipmaps incorrectly
- Fix lack of default export in ESM build
- Fix lack of Class and LOG_VERSION export in ESM build
- Fix Utils.Array.GetRandom often returning null if only startIndex was specified

## Release notes

### v4.2.1 — Phaser v4.2.1

- Date: 2026-07-09
- Version: v4.2.1
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.2.1
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.2.1

- **fixed** — Stencil option stencilInvert now works correctly
- **fixed** — Framebuffers now correctly clear stencil on use by enabling write mask by default
- **fixed** — Remove inline access of Phaser namespace from CombineColorMatrix, ImageLight, and Texture to prevent breaking in ESM build
- **fixed** — Fix ScaleManager not resizing to parent container
- **fixed** — Correct AnimationManager get() return type in documentation
- **fixed** — Tweens with a startDelay set now have their state updated from START_DELAY to ACTIVE

##### Version 4.2.1 - Giedi - 9th July 2026

##### Fixes

- `Stencil` option `stencilInvert` works correctly (an alpha bug prevented it from having the intended effect)
- Framebuffers now correctly clear stencil on use
  - The global stencil settings defaulted to deactivating the stencil write mask, so it couldn't actually run the `clear` process correctly. Write mask is now enabled by default, but is never triggered because default stencil operations keep existing values.
- Remove inline access of Phaser namespace from `CombineColorMatrix`, `ImageLight`, and `Texture`. These would break in the ESM build. Thanks @scobo!
- Fix ScaleManager not resizing to parent container. Fix #7213 (thanks @VijayVPatil13)
- Docs: correct AnimationManager get() return type (thanks @samme)
- Tweens with a startDelay set weren't having their state updated from START_DELAY to ACTIVE. This left them stuck in their initial state, even once the startDelay had elapsed. Fix #7093 (thanks @Bambosh)

### v4.2.0 — Phaser v4.2.0

- Date: 2026-06-19
- Version: v4.2.0
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.2.0
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.2.0

- **added** — New game config options render.alphaStrategy, render.stencil, and render.stencilAlphaStrategy for controlling alpha handling and stencil buffer creation
- **added** — CustomContext game object to modify DrawingContext at render time, enabling stencil testing, alpha handling strategies, and GL scissor modification
- **added** — Mesh2D game object to render textured triangles with batching support for regular sprites
- **added** — Mesh2D#buildOrderedIndices method to precompute optimized index lists for triangle-to-quad arrangements with configurable optimization strategies
- **added** — Mesh2D#useOrderedIndices and Mesh2D#setUseOrderedIndices to toggle between ordered and unordered index lists without rebuilding
- **added** — Mesh2D#renderAsTriangles and Mesh2D#setRenderAsTriangles to render mesh as individual triangles via BatchHandlerTri
- **added** — BatchHandlerTri render node to draw individual textured triangles as a batch, extending BatchHandlerQuad with a batchTriangles method
- **added** — TransformerVertex render node now splits per-vertex run into setupMatrix and transformVertex to cache transform matrices for mesh rendering
- **added** — Stencil game object as a persistent container whose contents modify the stencil buffer with operating modes including addLayer, subtractLayer, clear, and clearRegion
- **added** — StencilReference game object to re-render a target Stencil with different settings
- **added** — AlphaStrategy setting to use GLSL discard instead of alpha in shaders, with strategies including keep, dither, and threshold
- **added** — BatchHandler render node now supports config option for topology to allow extended nodes to opt into different triangulation modes
- **added** — DrawingContext now includes controls for alpha strategy, color writemask, and stencil parameters
- **added** — WebGLGlobalWrapper now handles stencil write mask
- **added** — TintModes.MULTIPLY_TWO tint mode using a secondary color for new tint effects
- **added** — Game objects with Tint component now support second tint per corner with tint2TopLeft properties and setTint2() method
- **added** — Mesh2D and Tile objects support constant tint via tint2
- **added** — Timestep#setFPSLimit method to change the frame rate at runtime with proper property updates
- **added** — Cone lights as directional light sources with coneEnabled, coneRotation, coneInnerAngle, and coneOuterAngle properties
- **changed** — inTintEffect shader attribute changed from float to vec4 with encoding changed from float32 to four uint8s in ApplyTint shader addition
- **changed** — WebGLStencilParametersFactory now takes an extra writeMask parameter

##### Version 4.2.0 - Giedi - 19th June 2026

###### New Features

- New game config options:
    - `render.alphaStrategy`: hint to shaders to handle alpha in different ways.
    - `render.stencil`: disable stencil buffer creation in a game, saving memory.
    - `render.stencilAlphaStrategy`: set the default alpha strategy used within `Stencil` objects, where regular alpha does nothing.
- `CustomContext` game object is a container which can modify the `DrawingContext` at render time. This is an advanced rendering technique which reaches into the deep settings of the renderer. Potential uses include:
    - Toggling stencil testing
    - Selectively activating alpha handling strategies
    - Freehand GL scissor modification
- `Mesh2D` game object renders textured triangles. It batches with regular sprites.
    - `Mesh2D#buildOrderedIndices` precomputes an optimized index list (`Mesh2D#indicesOrdered`) which arranges triangles into quad-forming pairs, synthesizing degenerate triangles where a triangle has no edge-sharing partner. You choose the optimization strategy (`0` fast, `1` medium, `2` high), paying the cost once when the topology is stable. Use `Mesh2D#useOrderedIndices` (and `Mesh2D#setUseOrderedIndices`) to toggle between the ordered and unordered lists without rebuilding.
    - `Mesh2D#renderAsTriangles` (and `Mesh2D#setRenderAsTriangles`) renders the mesh as individual triangles via the new `BatchHandlerTri` render node, which is suitable for dynamic topology that cannot be optimized into quads.
- `BatchHandlerTri` render node draws individual textured triangles (`gl.TRIANGLES`) as a batch. It extends `BatchHandlerQuad`, reusing its shader, vertex layout, and texture handling, and adds a `batchTriangles` method which accepts vertex and index arrays directly.
- `TransformerVertex` render node now splits its per-vertex `run` into `setupMatrix` (build the transform matrix once per GameObject) and `transformVertex` (project a single vertex with the cached matrix). Mesh rendering uses this to avoid rebuilding the transform matrix for every vertex. `run` is unchanged for existing callers.
- `Stencil` game object is a container whose contents modify the stencil buffer. This is a fast way to persistently mask the game canvas. There are many ways to combine stencils. The default approach is to add layers to the stencil mask.
    - Unlike stencil masks in Phaser 3, Stencil objects are universal, persistent, and support anything as a stencil source, so long as it draws pixels. Use sprites and filter outputs as stencil sources!
    - Operating modes include `addLayer`, `subtractLayer`, `clear`, and `clearRegion`. Add and subtract can be inverted.
- `StencilReference` game object re-renders a target `Stencil` with different settings. This is useful for removing or reusing stencil geometry.
- `AlphaStrategy` setting used in the render system allows you to use GLSL `discard` instead of alpha in many shaders. This is inefficient, but is useful for some effects and situations.
    - Game config can set a default alpha strategy.
    - Stencil and CustomContext allow you to set an alpha strategy.
    - Most Phaser shaders handle alpha strategy. Custom shaders must implement it themselves, but you can use compositing (`filtersForceComposite`) to run graphics through a compatible shader.
    - Strategies include:
        - `keep`: use alpha as normal.
        - `dither`: use a dithering algorithm to select pixels to discard.
        - `threshold`: discard all pixels below a certain alpha.
- `BatchHandler` render node now has a config option for `topology`, allowing extended nodes to opt into different triangulation modes.
- `BatchHandlerTri` render node renders textured triangles. It is used by `Mesh2D` in triangle rendering mode. This can be more efficient than attempting to compile triangles into quads, which is the default strategy.
- `DrawingContext` adds more controls:
    - Alpha strategy
    - Color

_[Truncated at 4000 characters — full notes: https://github.com/phaserjs/phaser/releases/tag/v4.2.0]_

### v4.1.0 — Phaser v4.1.0

- Date: 2026-04-30
- Version: v4.1.0
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.1.0
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.1.0

- **added** — RenderConfig#mipmapRegeneration option allows certain framebuffer-based objects to use mipmaps if the game is configured to use mipmaps
- **added** — Layer is now a true GameObject
- **added** — Base filter Controller now has getPaddingCeil() method which returns the ceiling of the current padding
- **changed** — Filter controllers should use getPaddingCeil() instead of getPadding() for custom render nodes
- **fixed** — Fix reversions in rounded rectangle handling
- **fixed** — Remove duplicate function definition and exposed internal code docs from RectangleCanvasRenderer
- **fixed** — Fix duplicate texture name resulting from RenderTexture#saveTexture
- **fixed** — Fix framebuffers in filters and DynamicTextures using mipmaps incorrectly
- **fixed** — Fix lack of default export in ESM build
- **fixed** — Fix lack of Class and LOG_VERSION export in ESM build
- **fixed** — Fix Utils.Array.GetRandom often returning null if only startIndex was specified

##### Version 4.1.0 - Salusa - 30th April 2026

###### New Features

- `RenderConfig#mipmapRegeneration` option allows certain framebuffer-based objects to use mipmaps if the game is configured to use mipmaps. This has a cost because mipmaps must be recreated after every change. Currently it only applies to DynamicTextures; Filters cannot render mipmaps. Thanks @Flow!
- `Layer` is now a true `GameObject`. This fixes numerous small inconsistencies, and some big issues such as Filters not working. Thanks @rexrainbow for reporting the initial issue!
- The base filter `Controller` now has `getPaddingCeil()`, which returns the ceiling of the current padding. This is mostly used internally to avoid quality loss from fractional padding. If your code calls `getPadding()` on a filter controller (typically in a custom render node), you should replace it with `getPaddingCeil()`.

###### Fixes

- Fix reversions in rounded rectangle handling. Thanks @laineus!
- Remove duplicate function definition and exposed internal code docs from `RectangleCanvasRenderer`.
- Fix duplicate texture name resulting from `RenderTexture#saveTexture`. Thanks @UnaiNeuronUp!
- Fix framebuffers (in filters and DynamicTextures) using mipmaps incorrectly. Now filters do not render with mipmaps. Thanks @Flow!
- Fix lack of default export in ESM build. Thanks @kibertoad!
- Fix lack of Class and LOG_VERSION export in ESM build. Thanks to many users including @Flow and @rex for helping investigate this!
- Fix `Utils.Array.GetRandom` often returning `null` if only `startIndex` was specified. Now it always returns an array element if part of the array is within range, as documented.

### v4.0.0 — Phaser v4.0.0

- Date: 2026-04-10
- Version: v4.0.0
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.0.0
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.0.0

- **changed** — Replace v3 pipeline system with a new node-based renderer where each render node handles a single task with fully managed WebGL state and built-in context restoration
- **changed** — Unify FX and Masks from v3 into a single powerful Filter system applicable to any game object or camera
- **added** — Add Filter system with Blur, Glow, Shadow, Pixelate, ColorMatrix, Bloom, Vignette, Wipe, ImageLight, GradientMap, Quantize, and Blend filters
- **added** — Add SpriteGPULayer to render millions of sprites in a single draw call with GPU-driven animations on position, rotation, scale, alpha, tint, and frame
- **added** — Add TilemapGPULayer to render entire tilemap layers as a single quad with support for up to 4096 x 4096 tiles
- **changed** — Overhaul tint system with six tint modes: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT, separating color and mode as distinct concerns
- **added** — Add new game objects: Gradient, Noise (Cell 2D/3D/4D, Simplex 2D/3D), CaptureFrame, and Stamp
- **changed** — Improve lighting system to be activated with sprite.setLighting(true) with self-shadows and explicit light height support across most game objects
- **changed** — Implement cleaner config-based Shader API with #pragma GLSL directive support
- **changed** — Enhance TileSprite to support atlas frames and tile rotation

After years of development, Phaser 4 is here. This is the biggest release in Phaser's history - a ground-up rebuild of the WebGL renderer with a completely new architecture, while keeping the API you know and love.

##### Highlights

- **New Render Node Architecture** - The v3 pipeline system has been replaced with a clean, node-based renderer. Each render node handles a single task, WebGL state is fully managed, and context restoration is built in. Faster, more reliable, and much easier to extend.
- **Unified Filter System** - FX and Masks from v3 are now a single, powerful Filter system. Apply filters to any game object or camera with no restrictions. Ships with Blur, Glow, Shadow, Pixelate, ColorMatrix, Bloom, Vignette, Wipe, ImageLight, GradientMap, Quantize, Blend, and many more.
- **SpriteGPULayer** - Render a million sprites in a single draw call, up to 100x faster than standard rendering. GPU-driven animations on position, rotation, scale, alpha, tint, and frame.
- **TilemapGPULayer** - Render an entire tilemap layer as a single quad. Per-pixel shader cost means up to 4096 x 4096 tiles with no performance penalty. Perfect texture filtering with no seams.
- **Overhauled Tint System** - Six tint modes: `MULTIPLY`, `FILL`, `ADD`, `SCREEN`, `OVERLAY`, `HARD_LIGHT`. Color and mode are now separate concerns.
- **New Game Objects** - Gradient, Noise (Cell 2D/3D/4D, Simplex 2D/3D), CaptureFrame, and Stamp.
- **Improved Lighting** - As simple as `sprite.setLighting(true)`. Self-shadows, explicit light height, works across most game objects.
- **Shader and TileSprite Improvements** - Cleaner config-based Shader API, `#pragma` GLSL directives, TileSprite now supports atlas frames and tile rotation.
- **AI Agent Skills** - 28 comprehensive skill files included in the repository covering every major Phaser subsystem, plus a dedicated v3 to v4 migration skill. Point your AI coding agent at the `skills/` folder for deep Phaser 4 knowledge.

##### Install

```bash
npm install phaser
```

##### Links

- 📖 [Full Changelog](https://github.com/phaserjs/phaser/blob/master/changelog/v4/4.0/CHANGELOG-v4.0.0.md)
- 🔄 [Migration Guide (v3 to v4)](https://github.com/phaserjs/phaser/blob/master/changelog/v4/4.0/MIGRATION-GUIDE.md)
- 📚 [API Documentation](https://docs.phaser.io/)](https://docs.phaser.io)
- 🎮 [Examples](https://phaser.io/examples)
- 💬 [Discord](https://discord.gg/phaser)

##### Thank You

Phaser wouldn't have been possible without the fantastic support of the community. Thank you to everyone who supports our work, who shares our belief in the future of HTML5 gaming, and Phaser's role in that.

Happy coding everyone!

Rich and the whole team at Phaser Studio