What changed in phaser from 3 to 4

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)

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 writemask
  • Stencil parameters
• WebGLGlobalWrapper now handles stencil write mask.
• WebGLStencilParametersFactory now takes an extra writeMask parameter.
• TintModes.MULTIPLY_TWO is a new tint mode which uses a secondary color. This can create powerful new tint effects, such as fire or inversion.
  • To support this, the encoding of tint mode in shaders with the ApplyTint addition has been changed. The inTintEffect shader attribute has changed from a float to a vec4, and its encoding has changed from a float32 to four uint8s. This should only affect deep uses of the render system.
  • Game objects with the Tint component now support a second tint per corner (tint2TopLeft etc), and have a new method setTint2(). Additionally, the Mesh2D and Tile objects support constant tint via tint2. (TilemapGPULayer does not support tinting on tiles.)
• Timestep#setFPSLimit method changes the frame rate at runtime. This method updates derived properties, making it safer than manually adjusting Timestep#fpsLimit.

New Feature: Cone Lights

Cone lights are standard Phaser dynamic lights restricted to a directional cone. They are useful for flashlights, lantern beams, vision cones, headlights, searchlights, and other focal light sources.

Cone lights run through the existing WebGL lighting shader. They do not require a mask, a second Camera, or rendering the map twice. Any Game Object that already works with Phaser lighting can be lit by a cone light.

Full details can be found in the Phaser 4 Cone Lights.md file in the docs folder in this repo.

• Light.coneEnabled is a new boolean property that controls if the light is restricted to a cone.
• Light.coneRotation is a new number property that sets the cone direction in radians.
• Light.coneInnerAngle is a new number property that sets the inner cone angle in radians.
• Light.coneOuterAngle is a new number property that sets the outer cone angle in radians.
• Light.setCone is a new method that sets a Light to be a Cone light.
• Light.setConeRotation is a new method that sets the cone light rotation.
• Light.setConeAngles is a new method that sets the cone light inner and outer angles.
• Light.disableCone is a new method that disables a cone light.
• LightsManager.addConeLight is a new method that creates a cone-limited light.
• The DefineLights GLSL shader gains two new uniforms: vec2 direction and vec3 cone.

Thanks to @FSDevelop for adding this feature.

Changes

• GameObjects.Components.Filters now adds its RenderStep just before the core render method. This allows other steps to run beforehand.
• WebGLStencilParametersFactory now defaults to:
  • enabled: true (stencil test is on by default; testing showed little performance impact)
  • func: gl.EQUAL (stencil test now passes if the stencil buffer is EQUAL to 0)

Fixes

• Layer no longer has a duplicate RenderStep which does nothing.
• SpriteGPULayer no longer tries to access global namespace for Phaser functionality, which can cause a crash in modules.
• SpriteGPULayer no longer has a Mask component, as it's a Canvas feature but the object is WebGL only.
• DrawingContext no longer attempts to unbind textures based on the game canvas, which cannot exist and just wastes time.
• A Blitter will now call destroy on its Bob Game Objects as part of its own destroy process. Fix #7292 (thanks @samme)
• Fixed a bug where the Line width and height values were not being updated after a call to setTo(). Fix #7270 (thanks @samme)
• Phaser.Math.Pow2 now exports GetPowerOfTwo, IsSizePowerOfTwo and IsValuePowerOfTwo. Fix #7309 (thanks @Visualizeit )

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.

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

npm install phaser

Links

• 📖 Full Changelog
• 🔄 Migration Guide (v3 to v4)
• 📚 API Documentation](https://docs.phaser.io)
• 🎮 Examples
• 💬 Discord

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