Phaser v4.0.0 Release Candidate 5

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.

Phaser v4.0.0 Release Candidate 4

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

Phaser v3.90.0

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

Phaser v4.0.0 Release Candidate 3

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

Phaser v4.0.0 Release Candidate 2

Updates since RC1:

New Features

• RenderConfig#renderNodes allows you to add render nodes at game boot.
• ShaderQuadConfig#initialUniforms lets you initialize a Shader with uniforms on creation.
• Shader#setUniform(name, value) lets you set shader program uniforms just once, instead of putting them all into the setupUniforms() method, where some uniforms might be set redundantly after init. This wraps Shader#renderNode.programManager.setUniform.

Changes

• TextureManager#addDynamicTexture now has forceEven parameter.

Fixes

• Fix parent transform on filtered objects (e.g. masks inside containers).
• Fix camera shake.
• Add typedefs for the { internal, external } structure of Camera#filters (and GameObject#filters).
• Fix FilterList#addMask docs.
• In Layer and Container objects, use that object's children for the displayList passed to RenderWebGLSteps.
• Fix positioning of Group members and offset objects in DynamicTexture#draw.
• Fix Shadow filter direction.

Phaser v4.0.0 Release Candidate 1

Updates since beta 8:

Changes

• Mask filter now uses current camera by default.
• GameObject#enableLighting now works even if the scene light manager is not enabled. The light manager must still be enabled for lights to render, but the game object flag can be set at any time.
• YieldContext and RebindContext render nodes now unbind all texture units. These nodes are used for external renderer compatibility. An external renderer could change texture bindings, leading to unexpected textures being used, so we force texture rebind.

New Features

• WebGLSnapshot (used in snapshot functions) supports unpremultiplication, which is on by default. This removes dark fringes on text and objects with alpha.
• Add chainable setter methods to Filter component: setFiltersAutoFocus, setFiltersFocusContext, setFiltersForceComposite, setRenderFilters.
• All enhancements from Phaser v3 development have been merged. This includes:
  • Transform#getWorldPoint
  • Layer#getDisplayList
  • DynamicTexture and RenderTexture changes:
    • forceEven parameter forces resolution to be divisible by 2.
    • clear(x, y, width, height) method now takes the listed optional parameters.
  • Rectangle now supports rounded corners.
  • Physics.Matter.Components.Transform#scale for setting scaleX and scaleY together.
  • WebGLRenderer reveals functions around context loss:
    • setExtensions
    • setContextHandlers
    • dispatchContextLost
    • dispatchContextRestored
  • Improvements to tile handling for non-orthogonal tiles.
  • Tween#isNumberTween
  • Many other fixes and tweaks.

Fixes

• Fix WebGLSnapshot orientation.
• Fix filters rendering outside intended camera scissor area.
• Fix reversion in BitmapText kerning.
• Fix CaptureFrame compatibility with Layer and Container.
• Fix Grid using old methods. It was supposed to use 'stroke' just like other Shape objects, not a unique 'outline'.
• Add @return tag to FilterList#addBlend (thanks @PhaserEditor2D!).
• Fix RenderSteps parameter propagation into Layer and Container. This resolves some missing render operations in complex situations.
• Fix DynamicTexture errors when rendering Masks.
• Fix camera transform matrix order issues, as seen when rendering through transformed cameras.
• Fix GL scissor sometimes failing to update. The actual issue was, we were storing the screen coordinates, but applying GL coordinates, which can be different in different-sized framebuffers. DrawingContext now takes screen coordinates, and sets GL coordinates in the WebGLGlobalWrapper.

Phaser v4.0.0 Beta 8

Changes

• Mask Filter now uses world transforms by preference when drawing the mask. This improves expected outcomes when mask objects are inside Containers.

Additions

• Extend RenderWebGLStep to take the currently rendering object list and index as parameters. This allows render methods to know their context in the display list, which can be useful for optimizing third-party renderers.
  • This takes the place of nextTypeMatch from Phaser v3, but is much more flexible.
• Add DynamicTexture#capture, for rendering game objects more accurately and with greater control than draw.
• Add CaptureFrame game object, which copies the current framebuffer to a texture when it renders. This is useful for applying post-processing prior to post.

Fixes

• Prevent RenderTexture from rendering while it's rendering, thus preventing infinite loops.
• Fix boundary errors on the Y axis in TilemapGPULayer shader, introduced after switching to GL standard texture orientation.
• Fix Filters#focusFilters setting camera resolution too late, leading to unexpected results on the first frame.
• Fix parent matrix application order, resolving unexpected behavior within Containers.
• Fix FillCamera node being misaligned/missing in cameras rendering to framebuffers.
• Fix errors when running a scene without the lighting plugin.
• Fixes to TypeScript documentation: thanks to SBCGames and mikuso for contributions!

Phaser v4.0.0 Beta 7

Major Changes

• Camera System Rewrite

The camera system rewrite changes the way camera matrices are calculated.

The Phaser 3 camera combined position, rotation, and zoom into Camera#matrix. Camera scroll was appended later.

The new camera system uses two matrices. Camera#matrix is now a combination of rotation, zoom, and scroll. A new Camera#matrixExternal property includes camera position. This allows us to cleanly divide the view from the position.

This change doesn't affect how you set camera properties to change the view. It mostly affects internal systems. However, if you use camera matrices directly, be aware that they have changed.

• Camera#matrix now includes scroll, and excludes position.
• Camera#matrixExternal is a new matrix, which includes the position.
• Camera#matrixCombined is the multiplication of matrix and matrixExternal. This is sometimes relevant.
• The GetCalcMatrix(src, camera, parentMatrix, ignoreCameraPosition) method now takes ignoreCameraPosition, causing its return value to use the identity matrix instead of the camera's position.
• GetCalcMatrixResults now includes a matrixExternal property, and factors scroll into the camera and calc matrices.
• To get a copy of a matrix with scroll factor applied, use TransformMatrix#copyWithScrollFactorFrom(matrix, scrollX, scrollY, scrollFactorX, scrollFactorY). This generally replaces cases where phrases such as spriteMatrix.e -= camera.scrollX * src.scrollFactorX were used.

The new system fixes many issues with nested transforms, filters, and other uses of transforms.

Minor Additions

• Add documentation explaining how to modify a SpriteGPULayer efficiently.
• Add SpriteGPULayer#insertMembers method.
• Add SpriteGPULayer#insertMembersData method.
• Add SpriteGPULayer#getDataByteSize method.
• Add non-looping animations to SpriteGPULayer (set animation to loop: false) to support one-time particle effects and dynamic sources.
• Add creation time to SpriteGPULayer members.
• Add documentation for writing a Extern#render function.
• TilemapLayer and TilemapGPULayer now support a parent matrix during rendering.
• Shape now sets filtersFocusContext = true by default, to prevent clipping stroke off at the edges.

Fixes and Tweaks

• Fix missing reference to Renderer events in BatchHandler (thanks @mikuso)
• Fix SpriteGPULayer segment handling (segments changed from 32 to 24 to avoid problems with 32-bit number processing)
• Allow negative acceleration in SpriteGPULayer member animations using Gravity.
• Rearrange SpriteGPULayer data encoding.
• Fix SpriteGPULayer failing to generate frame animations from config objects.
• Allow TextureSource#setFlipY to affect all textures (except compressed textures, which have fixed orientation).
• WebGLProgramWrapper now correctly recognizes uniforms with a value of undefined and can recognize if they have not changed and do not need updates.
• Set roundPixels game option to false by default. It's very easy to get messy results with this option, but it remains available for use cases where it is necessary.
• Throw an error if DOMElement has no container.
• Fix TileSprite applying smoothPixelArt game option incorrectly.

Phaser v4.0.0 Beta 6

Additions

• Add Filter support to Layer.
• Allow RenderTexture to automatically re-render.
  • DynamicTexture#preserve() allows you to keep the command buffer for reuse after rendering.
  • DynamicTexture#callback() allows you to run callbacks during command buffer execution.
  • RenderTexture.setTextureMode() allows you to set the RenderTexture to automatically re-render during the render loop.

Fixes and Eliminations

• Fix roundPixels handling in many places, mostly by removing it from irrelevant situations.
  • Remove TransformMatrix#setQuad parameter roundPixels, as it is no longer used.
• Filters are correctly destroyed along with their owners, unless ignoreDestroy is enabled. This supports multi-owner Filter controllers.
• WebGLRenderer destroys itself properly.
• Remove unnecessary transform related to camera scroll.
• Remove references to Mesh.
• Fix UV coordinates in Shader.
• Shader#setTextures() now replaces the texture array, rather than adding to it.
• Fix SpriteGPULayer#getMember(), which previously multiplied the index by 4.
• Fix flipX/flipY in Filter#focusFilters.
• Fix BatchHandlerQuad#run() parameter tintFill, which was set as a Number but should be used as a Boolean.
• Eliminate rounding in Camera#preRender().

Phaser v3.88.2

Bug Fixes

• Reverted an incorrect change made to the Scale Manager that prevented the autoCenter: Phaser.Scale.CENTER_BOTH from working.