# phaser changelog

> Phaser is a fun, free and fast 2D game framework for making HTML5 games for desktop and mobile web browsers, supporting Canvas and WebGL rendering.

- Vendor: phaserjs
- Category: Frameworks & Libraries
- Official site: https://phaser.io/
- Tracked by: What's New (https://whatsnew.fyi/product/phaser)
- Harvested from: GitHub (phaserjs/phaser)
- Entries below: 10 (newest first)

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

## Releases

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

### v4.0.0-rc.7 — Phaser v4.0.0 Release Candidate 7

- Date: 2026-03-25
- Version: v4.0.0-rc.7
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.0.0-rc.7
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.0.0-rc.7
- Labels: Pre-release

- **added** — Actions.AddEffectBloom allows you to quickly set up a bloom effect, using several filters, on a target Camera or GameObject
- **added** — Actions.AddEffectShine allows you to quickly set up a shine effect, using a new Gradient and filters, on a target Camera or GameObject
- **added** — Actions.AddMaskShape allows you to quickly add shapes to a target Camera or GameObject as Masks with blurred edges and inversion support
- **added** — Actions.FitToRegion transforms an object to fit a region, such as the screen
- **changed** — Display.Color helper methods HSLToColor, HexStringToColor, IntegerToColor, ObjectToColor, RGBStringToColor, and ValueToColor now support modifying an existing Color object instead of creating a new one
- **added** — Display.Color.Interpolate.HSVWithHSV method to interpolate HSV values in HSV space
- **changed** — Display.Color.Interpolate.ColorWithColor has new parameters hsv and hsvSign to allow it to operate in HSV space
- **added** — Display.ColorBand describes a transition between two colors intended for use in gradients
- **added** — Display.ColorRamp describes a range of colors using ColorBands intended for use in gradients
- **added** — GameObject#isDestroyed flag helps you avoid errors when accessing an object that might have removed expected properties during destruction
- **added** — GameObjects.Gradient is a new game object which renders gradients with shapes LINEAR, BILINEAR, RADIAL, CONIC_SYMMETRIC, and CONIC_ASYMMETRIC
- **added** — GameObjects.Gradient supports repeat modes EXTEND, TRUNCATE, SAWTOOTH, and TRIANGULAR with optional Interleaved Gradient Noise based dithering
- **changed** — GameObjects.NineSlice has two new parameters tileX and tileY allowing non-corner regions to tile instead of stretch
- **added** — GameObjects.Noise renders noise patterns with control over value power curve, trigonometric or PCG algorithms, and grayscale, random color, or random normals output
- **added** — GameObjects.NoiseCell2D, NoiseCell3D, and NoiseCell4D provide cellular noise with sharp or smooth edges and support for rendering as texture or normal map
- **added** — GameObjects.NoiseSimplex2D and NoiseSimplex3D provide simplex noise with gradient flow, octaves of detail, turbulence, and texture or normal map rendering
- **changed** — Tint is overhauled: tint and setTint() now purely affect color settings, tintFill and setTintFill() are removed, and new tintMode property and setTintMode() method manage tint fill mode
- **added** — Phaser.TintModes enumerates valid tint modes: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, and HARD_LIGHT
- **added** — New filters added: CombineColorMatrix, GradientMap, Key, ImageLight, PanoramaBlur, NormalTools, and Quantize

##### New Features

- `Actions.AddEffectBloom` allows you to quickly set up a bloom effect, using several filters, on a target Camera or GameObject.
- `Actions.AddEffectShine` allows you to quickly set up a shine effect, using a new Gradient and filters, on a target Camera or GameObject.
- `Actions.AddMaskShape` allows you to quickly add shapes to a target Camera or GameObject as Masks. Blurred edges and inversion are supported.
- `Actions.FitToRegion` transforms an object to fit a region, such as the screen.
- `Display.Color`: several helper methods now support modifying an existing `Color` object instead of creating a new one.
  - `HSLToColor`
  - `HexStringToColor`
  - `IntegerToColor`
  - `ObjectToColor`
  - `RGBStringToColor`
  - `ValueToColor`
- `Display.Color.Interpolate`: an extra interpolation mode is available.
  - `HSVWithHSV`: new method to interpolate HSV values, in HSV space.
  - `ColorWithColor` has new parameters to allow it to operate in HSV space.
    - `hsv` flag sets it to operate in HSV space.
    - `hsvSign` flag can force it to interpolate hue either ascending or descending. Default behavior picks the shortest angle.
- `Display.ColorBand` describes a transition between two colors. Intended for use in gradients.
- `Display.ColorRamp` describes a range of colors using ColorBands. Intended for use in gradients.
- `GameObject#isDestroyed` flag helps you avoid errors when accessing an object that might have removed expected properties during destruction.
- `GameObjects.Gradient` is a new game object which renders gradients.
  - Gradient shapes include:
    - `LINEAR`
    - `BILINEAR`
    - `RADIAL`
    - `CONIC_SYMMETRIC`
    - `CONIC_ASYMMETRIC`
  - Gradient repeat modes include:
    - `EXTEND`: flat colors extend from start and end.
    - `TRUNCATE`: transparency extends from start and end.
    - `SAWTOOTH`: gradient starts over every time it completes.
    - `TRIANGULAR`: gradient reverses direction every time it gets to the end or start.
  - Optional Interleaved Gradient Noise based dithering to eliminate banding.
- `GameObjects.NineSlice` has two new parameters: `tileX`, `tileY`, which allow non-corner regions of the NineSlice to tile instead of stretch. Some stretching is still applied to keep the tile count a whole number. Thanks to @skhoroshavin for this contribution!
- `GameObjects.Noise` renders noise patterns.
  - Control value power curve.
  - Select from trigonometric or PCG algorithms.
  - Output grayscale, random color, or random normals.
- Cellular noise objects: `GameObjects.NoiseCell2D`, `NoiseCell3D` and `NoiseCell4D` provide cellular/Worley/Voronoi noise.
  - Render cellular noise with sharp or smooth edges, or random flat colors.
  - Smoothly animate scroll through the XY plane or evolve the pattern through Z or ZW axes.
  - Add octaves of detail.
  - Supports rendering as a texture or normal map for use in other effects.
- Simplex noise objects: `GameObjects.NoiseSimplex2D` and `NoiseSimplex3D` provide simplex noise.
  - Render simplex noise, the successor to Perlin Noise.
  - Use gradient flow to smoothly loop noise animation.
  - Add octaves of detail.
  - Apply turbulence and output shaping for a variety of effects.
  - Supports rendering as a texture or normal map for use in other effects.
- `Tint` is overhauled.
  - `tint` and `setTint()` now purely affect the color settings.
    - Previously, both would silently deactivate fill mode.
  - `tintFill` and `setTintFill()` are removed.
  - New property `tintMode` and new method `setTintMode()` now set the tint fill mode.
  - `Phaser.TintModes` enumerates valid tint modes.
    - `MULTIPLY`
    - `FILL`
    - `ADD`
    - `SCREEN`
    - `OVERLAY`
    - `HARD_LIGHT`
  - FILL mode now treats partial alpha correctly.
  - BitmapText tinting now works correctly.
  - Conversion tip: `foo.setTintFill(color)` becomes `foo.setTint(color).setTintMode(Phaser.TintModes.FILL)`.
- `Combine

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

### v4.0.0-rc.6 — Phaser v4.0.0 Release Candidate 6

- Date: 2025-12-23
- Version: v4.0.0-rc.6
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.0.0-rc.6
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.0.0-rc.6
- Labels: Pre-release

- **added** — Add Texture#setWrap() method to provide easy access to texture wrap mode in WebGL
- **added** — Add Phaser.Textures.WrapMode.CLAMP_TO_EDGE which is always available
- **added** — Add optional sortByY parameter to the Tilemap createFromObjects method
- **changed** — Phaser.Textures.WrapMode.REPEAT will only be applied to textures with width and height equal to powers of 2
- **changed** — Phaser.Textures.WrapMode.MIRRORED_REPEAT requires powers of 2
- **changed** — Gamepad Button class now has optional isPressed boolean parameter to initialize the current pressed state
- **changed** — Container now updates the blend mode it passes to children more accurately, preventing blend modes from leaking between children's filters
- **changed** — Clarify that Tilemap.createLayer() with gpu flag enabled only works with orthographic layers, not hexagonal or isometric
- **fixed** — Blend filter parameter texture is now correctly documented as string
- **fixed** — ColorMatrix filter now correctly blends input alpha
- **fixed** — ColorMatrix.desaturate is no longer documented as saturation
- **fixed** — Filters now correctly handle non-central object origins when the object is flipped
- **fixed** — Glow filter acts consistently when knockout is active
- **fixed** — Grid shape now sets stroke correctly from optional initialization parameters at 1px wide
- **fixed** — Mask filter now correctly resizes and clears when the game resizes to an odd width or height
- **fixed** — ParallelFilters filter memory leak eliminated when both passes had active filters
- **fixed** — TilemapGPULayer now respects camera translation
- **fixed** — Fixed a crash in TweenBuilder when the targets array contains null or undefined elements
- **fixed** — Loader GetURL function now treats file:// URLs as absolute to prevent double-prefixed URLs when a baseURL is set
- **fixed** — Fixed a bug where multiple Timeline events with once set to true would silently break the timeline and prevent all future events from firing

##### New Features

- `Texture#setWrap()` provides easy access to texture wrap mode in WebGL, which would otherwise be very technical to alter on `WebGLTextureWrapper` objects. This is probably of most use to shader authors. Thanks @Legend-Master for raising an issue where power-of-two sprites had unexpected wrapping artifacts.
- `Phaser.Textures.WrapMode.CLAMP_TO_EDGE` is always available.
- `Phaser.Textures.WrapMode.REPEAT` will only be applied to textures with width and height equal to powers of 2.
- `Phaser.Textures.WrapMode.MIRRORED_REPEAT` likewise requires powers of 2.
- Added new optional `sortByY` parameter to the Tilemap `createFromObjects` method (thanks @saintflow47)

##### Clarifications

- Clarified that `Tilemap.createLayer()` with `gpu` flag enabled only works with orthographic layers, not hexagonal or isometric. Thanks @amirking59!

##### Updates

- Gamepad buttons initialize as not being pressed, which created a problem when reading Gamepads in one Scene, and then reading them in another Scene. If the player held the button down for even a fraction of a second in the first scene, the second scene would see a bogus Button down event. The `Button` class now has a new optional `isPressed` boolean parameter which the `Gamepad` class uses to resolve this, initializing the current pressed state of the Button (thanks @cryonautlex)

##### Fixes

- `Blend` filter parameter `texture` now correctly documented as `string`.
- `ColorMatrix` filter correctly blends input alpha.
- `ColorMatrix.desaturate` is no longer documented as `saturation`.
- `Container` now updates the blend mode it passes to children more accurately, preventing blend modes from leaking from one child into another child's filters. Thanks @leemanhopeter!
- `Filters` now correctly handles non-central object origins when the object is flipped. Thanks @ChrisCPI!
- `Glow` filter acts consistently when `knockout` is active.
- `Grid` shape now sets stroke correctly from optional initialization parameters, at 1px wide. (Use `Grid#setStrokeStyle()` to customize it further.) Thanks @Grimshad!
- `Mask` filter now correctly resizes and clears when the game resizes to an odd width or height, fixing a bug where masks might overdraw themselves over time. Thanks @leemanhopeter!
- `ParallelFilters` filter memory leak eliminated (this would occur when both passes had active filters).
- `TilemapGPULayer` now respects camera translation. Thanks @aroman!
- Fixed a crash in `TweenBuilder` when the targets array contains null or undefined elements (thanks @aomsir)
- The Loader `GetURL` function did not treat `file://` URLs as absolute. When a baseURL is set, it gets prepended to an already-absolute path, producing double-prefixed URLs (thanks @aomsir)
- Fixed a bug where multiple `Timeline` events with `once` set to `true` would silently break the timeline and prevent all future events from firing. Fix #7147 (thanks @TomorrowToday)

##### Examples, Documentation, Beta Testing and TypeScript

Thanks to the following for helping with the Phaser Examples, Beta Testing, Docs, and TypeScript definitions, either by reporting errors, fixing them, or helping author the docs:

@chavaenc
@Urantij
@justin-calleja
@DayKev
@samme
@ospira

### v4.0.0-rc.5 — Phaser v4.0.0 Release Candidate 5

- Date: 2025-08-22
- Version: v4.0.0-rc.5
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.0.0-rc.5
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.0.0-rc.5
- Labels: Pre-release

- **added** — Mask filter now supports scaleFactor parameter, allowing the creation of scaled-down framebuffers
- **added** — Camera has the new property isObjectInversion, used internally to support special transforms for filters
- **added** — Shader has the new method renderImmediate, which makes it straightforward to use renderToTexture when the object is not part of a display list
- **changed** — Drawing contexts, including filters, can now be larger than 4096 if the current device supports them
- **changed** — Balance rounded rectangle corners for smoothness on small corners while preventing excessive tesselation
- **fixed** — PhysicsGroup.add and StaticPhysicsGroup.add will now check to see if the incoming child already has a body of the wrong type, and if so, will destroy it so the new correct type can be assigned
- **fixed** — Blocky filter now has a minimum size of 1, which prevents the object from disappearing
- **fixed** — TilemapGPULayer now takes the first tileset if it receives an array of tilesets
- **fixed** — Filters now correctly transform the camera to focus objects with intricate transforms
- **fixed** — Filters now correctly handle parent transforms when focusing to the game camera
- **fixed** — DynamicTexture method startCapture now handles nested parent transforms correctly
- **fixed** — Children of filtered Container/Layer objects are correctly added to the current camera's renderList

##### New Features

- `Mask` filter now supports `scaleFactor` parameter, allowing the creation of scaled-down framebuffers. This can save memory in large games, but you must manage scaling logic yourself. Thanks to kimdanielarthur-cowlabs for developing the initial solution.
- `Camera` has the new property `isObjectInversion`, used internally to support special transforms for filters.
- `Shader` has the new method `renderImmediate`, which makes it straightforward to use `renderToTexture` when the object is not part of a display list, or otherwise needs updating outside the regular render loop.

##### Improvements

- Drawing contexts, including filters, can now be larger than 4096 if the current device supports them. Thanks to kimdanielarthur-cowlabs for suggesting this.
- Balance rounded rectangle corners for smoothness on small corners while preventing excessive tesselation.

##### Fixes

- `PhysicsGroup.add` and `StaticPhysicsGroup.add` will now check to see if the incoming child already has a body of the wrong type, and if so, will destroy it so the new correct type can be assigned.
- `Blocky` filter now has a minimum size of 1, which prevents the object from disappearing.
- `TilemapGPULayer` now takes the first tileset if it receives an array of tilesets (which is valid for Tilemaps but not for TilemapGPULayer). Thanks to ChrisCPI for the fix.
- Filters now correctly transform the camera to focus objects with intricate transforms.
- Filters now correctly handle parent transforms when focusing to the game camera.
- `DynamicTexture` method `startCapture` now handles nested parent transforms correctly. This is used in `Mask`, so masks within `Container` objects should behave correctly too.
- Children of filtered `Container`/`Layer` objects are correctly added to the current camera's `renderList`. This fixes an issue with input on overlapping interactive objects.

### v3.90.0 — Phaser v3.90.0

- Date: 2025-05-23
- Version: v3.90.0
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v3.90.0
- Permalink: https://whatsnew.fyi/product/phaser/releases/v3.90.0

- **added** — Add `GameObjects.Rectangle.setRounded` method to set rounded corners on Rectangle Shape Game Objects
- **added** — Add `GameObjects.Rectangle.isRounded` read-only boolean to determine if Rectangle Shape Game Object has rounded corners
- **added** — Add `GameObjects.Rectangle.radius` read-only number for the size of rounded corners
- **added** — Add `Phaser.Math.Angle.GetClockwiseDistance()` to get the shortest nonnegative angular distance between two angles
- **added** — Add `Phaser.Math.Angle.GetCounterClockwiseDistance()` to get the shortest nonpositive angular distance between two angles
- **added** — Add `Phaser.Math.Angle.GetShortestDistance()` to get the shortest signed angular distance between two angles
- **added** — Add `Phaser.GameObjects.BitmapText#setDisplaySize` method to set the original scaled size of BitmapText
- **added** — Add fallback for Web Audio on Firefox for AudioListener positional properties
- **changed** — Update `EXPAND` Scale Mode to clamp canvas size and prevent it from growing too large on landscape ultra-wide displays
- **changed** — Throw an Error if trying to create a DOM Game Object without correctly configured Game Config
- **fixed** — Remove erroneous `console.log` from the Text Game Object
- **fixed** — Clear particle emitter color RGB arrays before repopulating
- **fixed** — Fix `Phaser.Animations.AnimationFrame` to correctly use frame duration when set
- **fixed** — Fix particle emitter custom `moveTo` functions to properly move particles
- **fixed** — Change ImageCollections default Tileset values from `null` to `undefined`
- **fixed** — Fix chained tweens to `persist` correctly after calling `Phaser.Tweens.BaseTween#stop`
- **fixed** — Add default `canvas.dir = 'ltr'` and `context.direction = 'ltr'` to new left-to-right Text Game Objects
- **fixed** — Fix `Grid` Game Objects to render `lineWidth` correctly in WebGL mode
- **fixed** — Add `collisionMask` and `collisionCategory` checks to `Phaser.Physics.Arcade.World#separate` for individual physics game objects
- **fixed** — Fix Arcade Physics bug causing immovable circle objects to move when pushed by polygons

#### Version 3.90 - Tsugumi - 23rd May 2025

##### New Features

* `GameObjects.Rectangle.setRounded` is a new method that will allow the Rectangle Shape Game Object to have rounded corners. Pass the radius to set for the corners, or pass a value of zero to disable rounded corners.
* `GameObjects.Rectangle.isRounded` is a new read-only boolean that can be used to determine if the Rectangle Shape Game Object has rounded corners, or not.
* `GameObjects.Rectangle.radius` is a new read-only number that is the size of the rounded corners. Do not set directly, instead use the method `setRounded`.
* Added `Phaser.Math.Angle.GetClockwiseDistance()` to get the shortest nonnegative angular distance between two angles. PR #7092 (thanks @samme)
* Added `Phaser.Math.Angle.GetCounterClockwiseDistance()` gets the shortest nonpositive angular distance between two angles. PR #7092 (thanks @samme)
* Added `Phaser.Math.Angle.GetShortestDistance()` gets the shortest signed angular distance between two angles. (This is like `Phaser.Math.Angle.ShortestBetween()` but in radians.) PR #7092 (thanks @samme)
* Added `Phaser.GameObjects.BitmapText#setDisplaySize` method to `BitmapText` to get the original scaled size of 1. PR #6623 (thanks @samme)
* Added fallback for Web Audio on Firefox. Firefox doesn't implement `positionX`, `positionY` and `positionZ` properties on the AudioListener instances at the moment. This prevents the follow feature from WebAudioSound to operate on Firefox. PR #7083 (thanks @raaaahman)

##### Updates

* The `EXPAND` Scale Mode has been updated to now clamp the size of the canvas that is created, preventing it from growing too large on landscape ultra-wide displays. Fix #7027 (thanks @leha-games @rexrainbow)
* An Error will now be thrown if you try to create a DOM Game Object but haven't correctly configured the Game Config (thanks @samme)

##### Bug Fixes

* An erroneous `console.log` was left in the Text Game Object. This has now been removed.
* Particle emitter color RGB arrays are cleared before repopulating. Fix #7069 (thanks @Golen87 @samme)
* `Phaser.Animations.AnimationFrame` correctly uses frame duration when it is set. Fix #7070 (thanks @sylvainpolletvillard)
* Particle emitter custom `moveTo` functions can now move particles. Fix #7063 (thanks @samme)
* Changed ImageCollections default Tileset values from `null` to `undefined`. Fix #7053 (thanks @Snoturky)
* Chained tweens now `persist` correctly even after calling `Phaser.Tweens.BaseTween#stop`. Fix #7048 (thanks @FranciscoCaetano88)
* New left-to-right `Text` Game Objects now includes the default `canvas.dir = 'ltr` and `context.direction = 'ltr';`. Fixes a bug in Chrome 134 & Edge 134 where calling `destroy()` on a right-to-left `Text` Game Object prevents the next created left-to-right `Text` Game Object from rendering. Fix #7077 (thanks @Demeno)
* `Grid` Game Objects renders `lineWidth` correctly in WebGL mode. Fix #7029 (thanks @AlvaroNeuronup)
* Added `collisionMask` and `collisionCategory` checks to `Phaser.Physics.Arcade.World#separate` to allow individual physics game objects within a physics group to have it's own unique collision categories. Fix #7034 (thanks @frederikocmr)
* Fixed Arcade Physics bug causing immovable circle objects to move when pushed by polygons. Fix #7054 (thanks @hunkydoryrepair)
* Fixed `createFromTiles` to handle multiple tilesets when using sprite sheets. Fix #7122 (thanks @vikerman)
* Fixed audio files not loading from Base64 data URIs (thanks @bagyoni)

##### Examples, Documentation, Beta Testing and TypeScript

Thanks to the following for helping with the Phaser Examples, Beta Testing, Docs, and TypeScript definitions, either by reporting errors, fixing them, or helping author the docs:

@justin-calleja
@ixonstater
@DayKev

### v4.0.0-rc.4 — Phaser v4.0.0 Release Candidate 4

- Date: 2025-05-23
- Version: v4.0.0-rc.4
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.0.0-rc.4
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.0.0-rc.4
- Labels: Pre-release

- **added** — Add BatchHandlerQuadSingle render node for optimized single quad rendering in filter processes
- **changed** — BatchHandler render nodes now create their own WebGL data buffers with optimized sizes for batch performance
- **removed** — Remove WebGLRenderer#genericVertexBuffer and #genericVertexData to free 16MB of RAM and VRAM
- **removed** — Remove BatchHandlerConfig#createOwnVertexBuffer type property
- **removed** — Remove texture cropping support from TileSprite
- **fixed** — Fix lighting on rotated or filtered objects
- **fixed** — Add missing 'this' value for Group.forEach and StaticGroup.forEach
- **fixed** — Fix createFromTiles to handle multiple tilesets when using sprite sheets
- **fixed** — Fix audio files not loading from Base64 data URIs

This update improves performance related to data buffer size, primarily affecting filters, including masks. A game that was bottlenecked by filters on mobile devices may experience speedups of 16x or more. A desktop system, or a scene with no filters, may be broadly unaffected, save for memory savings.

##### New Features

- `BatchHandlerQuadSingle` render node added.
  - This is just a copy of `BatchHandlerQuad` with space for 1 quad.
  - The rendering system uses this node internally for transferring images in some steps of the filter process.

##### Changes

- `BatchHandler` render nodes now create their own WebGL data buffers.
  - This uses around 5MB of RAM and VRAM in a basic game.
  - Dedicated buffers are an optimum size for batch performance. 

##### Removals

- `WebGLRenderer#genericVertexBuffer` and `#genericVertexData` removed.
  - This frees 16MB of RAM and VRAM.
- `BatchHandlerConfig#createOwnVertexBuffer` type property removed.
- `TileSprite` no longer supports texture cropping.

##### Fixes

- Lighting fixed on rotated or filtered objects.
- Added missing 'this' value for Group.forEach and StaticGroup.forEach (thanks @TadejZupancic)
- Fix `createFromTiles` to handle multiple tilesets when using sprite sheets. Fix #7122 (thanks @vikerman)
- Fix audio files not loading from Base64 data URIs (thanks @bagyoni)

##### Documentation / TypeScript Enhancements

Thanks to the following people:

@captain-something
@DayKev
@ixonstater

### v4.0.0-rc.3 — Phaser v4.0.0 Release Candidate 3

- Date: 2025-05-16
- Version: v4.0.0-rc.3
- Original notes: https://github.com/phaserjs/phaser/releases/tag/v4.0.0-rc.3
- Permalink: https://whatsnew.fyi/product/phaser/releases/v4.0.0-rc.3
- Labels: Pre-release

- **added** — Add GameObject#vertexRoundMode to control vertex pixel rounding on a per-object basis with options: "off", "safe", "safeAuto", "full", and "fullAuto"
- **added** — Add GameObject#willRoundVertices(camera, onlyTranslated) method to determine whether vertices should be rounded
- **added** — Add Blocky filter that picks a single color from the image to preserve pixel art palettes with configurable pixel width, height, and offset
- **changed** — Make WebGL2 canvases compatible with the WebGL renderer
- **changed** — Optimize multi-texture shader branching pattern for better performance on a wider range of devices
- **changed** — Optimize multi-texture shader to request only the number of textures needed, improving performance on mobile devices
- **changed** — Remove vertex rounding from multi-texture shader to prevent batch breaking and performance degradation
- **fixed** — Fix WebGLSnapshot and snapshot functions to return the correct pixel instead of the one above it
- **fixed** — Fix ArcadePhysics#closest() and #furthest() to be properly defined
- **fixed** — Add guards to GamepadPlugin.stopListeners and GamepadPlugin.disconnectAll to prevent invocation on undefined gamepads
- **fixed** — Fix Arcade Physics OverlapCirc() and OverlapRect() to properly error when useTree is false

This release candidate introduces better pixel art controls, and fixes performance issues related to pixel art options.

Updates since RC2:

##### New Features

- `GameObject#vertexRoundMode` added to control vertex pixel rounding on a per-object basis.
  - Options include:
    - `"off"`: Never round vertex positions.
    - `"safe"`: Round vertex positions if the object is "safe": it is rendering with a transform matrix which only affects the position, not other properties such as scale or rotation.
    - `"safeAuto"` (default): Like "safe", but only if rendering through a camera where `roundPixels` is enabled.
    - `"full"`: Always round vertex positions. This can cause sprites to wobble if their vertices are not safely aligned with the pixel resolution, e.g. during rotations. This is good for a touch of PlayStation 1 style jank.
    - `"fullAuto"`: Like "full", but only if rendering through a camera where `roundPixels` is enabled.
  - `GameObject#willRoundVertices(camera, onlyTranslated)` returns whether vertices should be rounded. In the unlikely event that you need to control vertex rounding even more precisely, you are intended to override this method.
- `Blocky` filter added. This is similar to Pixelate, but it picks just a single color from the image, preserving the palette of pixel art. You can also configure the pixel width and height, and offset. This is a good option for pixelating a retro game at high resolution, setting up for additional filters such as CRT emulation.

##### Changes

- WebGL2 canvases are now compatible with the WebGL renderer.
- Optimize multi-texture shader.
  - Shader branching pattern changed to hopefully be more optimal on a wider range of devices.
  - Shader will not request the maximum number of textures if it doesn't need them, improving performance on many mobile devices.
  - Shader no longer performs vertex rounding. This will prevent many situations where a batch was broken up, degrading performance.

##### Fixes

- `WebGLSnapshot` and snapshot functions based on it now return the correct pixel, instead of the one above it (or nothing if they're at the top of the image).
- `ArcadePhysics#closest()` and `#furthest()` are properly defined (thanks @samme).
- `GamepadPlugin.stopListeners` and `GamepadPlugin.disconnectAll` now have guards around them so they won't try to invoke functions on potentially undefined gamepads (thanks @cryonautlex)
- Arcade Physics OverlapCirc() and OverlapRect() error when useTree is false. Fix #7112 (thanks @samme)

##### Documentation / TypeScript Enhancements

Thanks to the following people:

@ospira 
@samme
@OuttaBounds
@raaaahman