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.

Phaser v3.88.1

Bug Fixes

• Fixed ReferenceError: GetFastValueOp is not defined in NumberTweenBuilder (thanks Flow)
• Reverted incorrect change made to SafeRange array util function.
• Fixed Array.Utils.GetFirst so it correctly handles a negative start index. Fixes Container.getByName returning null and various other similar methods. Fix #7040 (thanks @XWILKINX)

Phaser v3.88

New Features

• Transform.getWorldPoint is a new method that will return the World point as a Vector2 of a Game Object, factoring in parents if applicable (thanks @samme)
• Utils.Array.GetFirst can now search from the end of the array when setting startIndex to -1.
• DynamicTexture and by extension RenderTexture now have a new boolean property forceEven in their constructor, setSize and resize methods. This will force the given width and height values to be rounded up to the nearest even value. This significantly improves the rendering quality of the render texture in most circumstances, so the flag is true by default. This is a potentially breaking change, so if you know you need an odd sized texture, please set the value to false. Fix #6988 (thanks @rexrainbow)

Updates

• Tween.isNumberTween is a new boolean property that tells if the Tween is a NumberTween, or not.
• The TransformMatrix.setTransform method has been updated so that it uses the old way of passing in matrix values for Canvas 2D. This fixes the error "Failed to execute 'setTransform' on 'CanvasRenderingContext2D': 6 arguments required, but only 1 present." in old legacy browsers such as Chromium Embedded Framework. Fix #6965 (thanks @rafa-fie)
• Handlers for both mousedown and mouseup have been added for unlocking Web Audio. Both events occur before a click event, allowing for earlier audio unlocking on devices that use a mouse (thanks @pavle-goloskokovic)
• In both the Canvas and WebGL Renderer the background color, as set in the game config, is applied directly to the canvas immediately upon creation, rather than at the first render step. This may avoid some 'flashes' of color in certain circumstances (thanks @pavle-goloskokovic)
• The Texture Manager will now fail gracefully when a texture isn't created as a result of calling the addBase64 method. Rather than the error "TypeError: null is not an object (evaluating 'texture.source')" is will not return early (thanks @samme)
• Both TweenBuilder and NumberTweenBuilder have been updated to use GetFastValue for most properties instead of GetValue.
• The Transform.getWorldTransformMatrix method will now destroy the parent matrix at the end, if it was created within the method.
• The Arcade Physics Body.setGameObject and StaticBody.setGameObject methods have been updated to do the following: Return if no valid Game Object is passed. Disable and null the body of the existing Game Object if the Body has one. Set the body property, even if it doesn't exist (converts non-physics objects into physics objects). Calls setSize to update the body dimensions to make the new Game Object and finally sets enable based on the given parameter, which is now correctly referenced. The StaticBody version also has a new parameter, enable which matches that of the Dynamic Body and defaults to true (the original state). Fix #6969 (thanks @yongzheng7)
• The Arcade Physics ArcadeColliderType has been updated to include Physics.Arcade.StaticBody. Fix #6967 (thanks @yongzheng7)
• Phaser.Types.GameObjects.Text.TextStyle now includes letterSpacing: a positive or negative amount to add to the spacing between characters. Fix #7002 (thanks @Stever1388)
• Tilemaps.Parsers.Tiled.ParseTilesets, Tilemaps.Parsers.Tiled.BuildTilesetIndex and Tilemaps.ImageCollection.addImage have been updated to include width and height of each individual image. Fix #6990 (thanks @stickleprojects)
• Tilemaps.Components.RenderDebug and Tilemaps.Parsers.Tiled.BuildTilesetIndex have been updated to include width and height offsets in Image Collections.
• Added a warning to Tilemaps.Components.GetTilesWithinShape when attempting to use this method with non orthogonal tilemaps.
• Changed the Cameras.Scene2D.Camera.preRender method from protected to public. Fix #7020 (thanks @zoubingwu)

Bug Fixes

• TweenData.update will now check if the Tween is a Number Tween and apply the final start/end value to the result on completion, instead of the eased value as calculated by the change made in v3.87.
• BaseTweenData.duration can now never be zero or less than zero, which would trigger NaN errors. It's now clamped to a minimum of 0.01ms. Fix #6955 (thanks @kainage)
• Fixed the properties in the FontFileConfig (thanks @samme)
• Matter.World.update could hang and crash the browser if a large delta value was given to it, such as returning to a long-dormant tab. The Matter Runner config values are now properly passed through, preventing this from happening. Fix #6977 (thanks @ubershmekel @samme)
• Phaser.Physics.Matter.Components.Transform#scale correctly scales the physics body with the GameObject. Fix #7001 (thanks @Stever1388)
• Phaser.Textures.Frame.setCropUVs updated crop calculation to include the spriteSourceSize. Fix #6996 (thanks @CrispMind)
• Phaser.Tilemaps.Parsers.Tiled.ParseJSONTiled updated hexagonal tilemaps to correctly calculate the widthInPixels and heightInPixels based on the hexagonal overlapping tiles. Fix #6992 (thanks @ptantiku)
• Phaser.Display.Color.Interpolate.RGBWithRGB now correctly returns a Phaser.Types.Display.ColorObject that includes r, g, b, a and color values. Fix #6979 (thanks @XWILKINX)
• Fixed incorrect Arcade Physics circle separation logic for circle to circle, and circle to rectangle collisions. The logic was incorrectly moving only one body, even if both could be moved. Fix #6963 (thanks @samme)
• Phaser.Plugins.PluginManager automatically boots plugins when the game config render type is set to Phaser.HEADLESS. Fix #6893 (thanks @hubertgrzeskowiak)
• Tweens created with persist set to true and given a completeDelay value are no longer destroyed and can be replayed. Fix #7008 (thanks @Stever1388)
• The Tweens.TweenChain onStart event is now dispatched properly. Fix #7007 (thanks @Stever1388)
• GameObjects.Particles.Zones.DeathZone now uses world position coordinates instead of local position coordinates following the particle emitter position. Fix #7006 (thanks @Stever1388)
• Merged pull request #7009 from @samme that prevents hanging timer events with repeats and negative delays. Fix #7004 (thanks @Stever1388)
• When adding a new Tween, passing an event listener callback outside the Phaser.Types.Tweens.TweenBuilderConfig object is now correctly executed without errors. Fix #7003 (thanks @Stever1388)
• A GameObjects.Text created with wordwrap and with letterSpacing applied now takes into account the provided letterSpacing value to correctly wrap lines. Fix #7002 (thanks @Stever1388)
• Creating new GameObjects.DOMElement sets the GameObject's displayWidth and displayHeight using its scaleX and scaleY values instead of the DOM elements getBoundingClientRect() values. Fix #6871 (thanks @HawkenKing)
• Setting scale mode to Phaser.Scale.FIT and autoCenter to Phaser.Scale.CENTER_BOTH correctly centres canvas on iOS devices. Fix #6862 (thanks @HawkenKing)
• On hex maps, creating a blank layer with the Tilemaps.Tilemap.createBlankLayer method now correctly sets the hexSideLength as loaded from the hex tilemap. Fix #6074 (thanks @wwoods)
• The Input.InputPlugin.processDragUpEvent now correctly returns x and y coordinates in world space.
• Animations.AnimationState.play method now prioritises the frameRate property when it is set in the PlayAnimationConfig object over animation data loaded from an external file.
• Fixed an issue where sounds / music would stop playing in iOS 17.5.1+ or iOS18+ after losing/gaining focus in Safari. The Web Audio Sound Manager will now listen for the 'visible' event and suspend and resume the context as a result. Fix #6829 (thanks @JanAmbrozic @condeagustin)
• The Layer Game Object method setToTop would throw an exception: getDisplayList is not a function. This method has now been added to the Game Object. Fix #7014 (thanks @leha-games @rexrainbow)
• Fixed an issue where the Particle EmitterOp defaultEmit() always returned undefined, causing particle problems if you gave only an onUpdate callback. Also if you configured an EmitterOp with onEmit or onUpdate, the op's current value would be incorrect (an object) until the first emit. Fix #7016 (thanks @urueda @samme)

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:

@samme
@justin-calleja

Phaser v4.0.0 Beta 5

As well as bug fixes, beta 5 includes two major components:

• SpriteGPULayer game object. This advanced renderer is designed to handle millions of background objects.
• Texture coordinates now match WebGL standards. This should bring greater compatibility with other technologies. Note that compressed textures must be re-compressed to work with this system: ensure that the Y axis starts at the bottom and increases upwards.

Fixes and Improvements

• Limit roundPixels to only operate when objects are axis-aligned and unscaled. This prevents flicker on transforming objects.
• Fix TextureSource.resolution being ignored in WebGL.
  • This fixes an issue where increasing text resolution increased text size.
• Fix DynamicTexture using a camera without the required methods.
• Remove WebGLAttribLocationWrapper as it is unused.
• Remove WebGLRenderer.textureIndexes as glTextureUnits.unitIndices now fills this role.
• Remove dead code and unused/unconnected properties from WebGLRenderer.
• Switch texture orientation to match WebGL standards.
• Add SpriteGPULayer game object.

Phaser v4.0.0 Beta 4

Fixes and Improvements

• Fix Arcade Physics group collisions, nearest and furthest, and static group refresh. Thanks samme!
• Fail gracefully when a texture isn't created in addBase64()
• Improve RenderSteps initialization, removing a private method substitution
• Fix Layer's use of RenderSteps
• Fix reversion that removed camera zoom on separate axes
• Fix filter padding precision
• Fix filter padding offset with internal filters
• Improve TransformMatrix.setQuad documentation
• Fix shader not switching when TilemapLayer and TileSprite are in the same scene

Phaser v4.0.0 Beta 3

Thanks to the community feedback in the Phaser Discord we decided to rework the way RenderFilters work:

Previously, the RenderFilters object wrapped game objects to apply Filters. This worked well in several ways, but because it replaced the existing game object, it made object references less reliable.

The decision was made to change Filters to a component on game objects. This is similar to the old FX system, but it is now built into the base GameObject, so it can be used everywhere. Filters are not FX (they're better).

For those who have been using Phaser 4 beta 1 or 2, this will change the way you use filters. The core principles are the same, however: filters are still divided into internal and external lists.

The new way to use filters is thus:

// Set up filter systems.
gameObject.enableFilters();

// Create filter controllers.
const blur = gameObject.filters.internal.addBlur();

When you run enableFilters(), Phaser creates an internal camera to handle the object's filters, and adds a RenderStep function.

By default, when there are no active filters to render, the RenderStep skips straight to renderWebGL. If you want the object to render to a framebuffer without rendering a filter, you can set gameObject.filtersForceComposite = true. This can be useful when you want to composite alpha, e.g. when you have several objects in a Container or Layer and you don't want to see them through each other, you can leave their alpha at 1, set filtersForceComposite, and reduce the alpha of gameObject.filterCamera.

Filters run focusFilters every time they render by default. This differs from RenderFilters.focus, which didn't run every time. This method ensures that the filterCamera is always locked onto the object. Some objects don't have enough properties to accurately lock on to, so the system will guess, and fall back to the screen resolution. You can run gameObject.focusFiltersOverride to manually set the camera target.

In general, this runs much like FX did - but with more control and better compatibility.

For more details about this release, please see the Dev Logs in Issue 211 of our Phaser World newsletter (due out on Friday 27th December)