« Changelog History


Phaser v3.50.0-beta.1 Release Notes

Release Date: 2020-08-06 // over 3 years ago

  • WebGL Multi-Texture Rendering

    🐎 The Texture Tint Pipeline has had its core flow rewritten to eliminate the need for constantly creating batch objects. Instead, it now supports the new multi-texture shader, vastly increasing rendering performance, especially on drawcall-bound systems.

    ⚡️ All of the internal functions, such as batchQuad and batchSprite have been updated to use the new method of texture setting. The method signatures all remain the same, unless indicated below.

    • Config.render.maxTextures is a new game config setting that allows you to control how many texture units will be used in WebGL.
    • 💻 WebGL.Utils.checkShaderMax is a new function, used internally by the renderer, to determine the maximum number of texture units the GPU + browser supports.
    • The property WebGLRenderer.currentActiveTextureUnit has been renamed to currentActiveTexture.
    • WebGLRenderer.startActiveTexture is a new read-only property contains the current starting active texture unit.
    • WebGLRenderer.maxTextures is a new read-only property that contains the maximum number of texture units WebGL can use.
    • WebGLRenderer.textureIndexes is a new read-only array that contains all of the available WebGL texture units.
    • WebGLRenderer.tempTextures is a new read-only array that contains temporary WebGL textures.
    • 🚚 The WebGLRenderer.currentTextures property has been removed, as it's no longer used.
    • TextureSource.glIndex is a new property that holds the currently assigned texture unit for the Texture Source.
    • TextureSource.glIndexCounter is a new property that holds the time the index was assigned to the Texture Source.
    • 🚚 WebGLRenderer.currentTextures has been removed, as it's no longer used internally.
    • 0️⃣ WebGLRenderer.setBlankTexture no longer has a force parameter, as it's set by default.
    • ⚡️ The Mesh Game Object WebGL Renderer function has been updated to support multi-texture units.
    • ⚡️ The Blitter Game Object WebGL Renderer function has been updated to support multi-texture units.
    • ⚡️ The Bitmap Text Game Object WebGL Renderer function has been updated to support multi-texture units.
    • ⚡️ The Dynamic Bitmap Text Game Object WebGL Renderer function has been updated to support multi-texture units.
    • ⚡️ The Particle Emitter Game Object WebGL Renderer function has been updated to support multi-texture units.
    • ⚡️ The Texture Tint vertex and fragment shaders have been updated to support the inTexId float attribute and dynamic generation.
    • The Texture Tint Pipeline has a new attribute, inTexId which is a gl.FLOAT.
    • TextureTintPipeline.bind is a new method that sets the uMainSampler uniform.
    • 🚚 The TextureTintPipeline.requireTextureBatch method has been removed, as it's no longer required.
    • 🚚 The TextureTintPipeline.pushBatch method has been removed, as it's no longer required.
    • 🚚 The TextureTintPipeline.maxQuads property has been removed, as it's no longer required.
    • 🚚 The TextureTintPipeline.batches property has been removed, as it's no longer required.
    • 👍 TextureTintPipeline.flush has been rewritten to support multi-textures.
    • TextureTintPipeline.flush no longer creates a sub-array if the batch is full, but instead uses bufferData for speed.
    • WebGLPipeline.currentUnit is a new property that holds the most recently assigned texture unit. Treat as read-only.
    • WebGLRenderer.setTextureSource is a new method, used by pipelines and Game Objects, that will assign a texture unit to the given Texture Source.
    • ⚡️ The WebGLRenderer.setTexture2D method has been updated to use the new texture unit assignment. It no longer takes the textureUnit or flush parameters and these have been removed from its method signature.
    • WebGLRenderer.setTextureZero is a new method that activates texture zero and binds the given texture to it. Useful for fbo backed game objects.
    • WebGLRenderer.clearTextureZero is a new method that clears the texture tha was bound to unit zero.
    • WebGLRenderer.textureZero is a new property that holds the currently bound unit zero texture.
    • WebGLRenderer.normalTexture is a new property that holds the currently bound normal map (texture unit one).
    • WebGLRenderer.setNormalMap is a new method that sets the current normal map texture.
    • WebGLRenderer.clearNormalMap is a new method that clears the current normal map texture.
    • WebGLRenderer.resetTextures is a new method that flushes the pipeline, resets all textures back to the temporary ones and resets the active texture counter.
    • WebGLPipeline.boot will now check all of the attributes and store the pointer location within the attribute entry.
    • WebGLPipeline.bind no longer looks-up and enables every attribute, every frame. Instead it uses the cached pointer location stored in the attribute entry, cutting down on redundant WebGL operations.
    • WebGLRenderer.isNewNormalMap is a new method that returns a boolean if the given parameters are not currently used.
    • WebGLPipeline.forceZero is a new property that informs Game Objects if the pipeline requires a zero bound texture unit.
    • WebGLPipeline.setAttribPointers is a new method that will set the vertex attribute pointers for the pipeline.
    • WebGLRenderer.unbindTextures is a new method that will activate and then null bind all WebGL textures.

    Forward Diffuse Light Pipeline API Changes

    🚚 This Light2D pipeline, which is responsible for rendering lights under WebGL, has been rewritten to work with the new Texture Tint Pipeline functions. Lots of redundant code has been removed and the following changes and improvements took place:

    • 🔀 The pipeline now works with Game Objects that do not have a normal map. They will be rendered using the new default normal map, which allows for a flat light effect to pass over them and merge with their diffuse map colors.
    • 🛠 Fixed a bug in the way lights were handled that caused Tilemaps to render one tile at a time, causing massive slow down. They're now batched properly, making a combination of lights and tilemaps possible again.
    • 👍 The Bitmap Text (Static and Dynamic) Game Objects now support rendering with normal maps.
    • 👍 The TileSprite Game Objects now support rendering with normal maps.
    • 👍 Mesh and Quad Game Objects now support rendering with normal maps.
    • 👍 The Graphics Game Objects now support rendering in Light2d. You can even use normal map textures for the texture fills.
    • 👍 Particle Emitter Game Object now supports rendering in Light2d.
    • 👍 All Shape Game Objects (Rectangle, IsoBox, Star, Polygon, etc) now support rendering in Light2d.
    • 💅 The Text Game Object now supports rendering in Light2d, no matter which font, stroke or style it is using.
    • 👍 Both Static and Dynamic Tilemap Layer Game Objects now support the Light2d pipeline, with or without normal maps.
    • The pipeline will no longer look-up and set all of the light uniforms unless the Light is dirty.
    • The pipeline will no longer reset all of the lights unless the quantity of lights has changed.
    • 0️⃣ The ForwardDiffuseLightPipeline.defaultNormalMap property has changed, it's now an object with a glTexture property that maps to the pipelines default normal map.
    • 0️⃣ The ForwardDiffuseLightPipeline.boot method has been changed to now generate a default normal map.
    • 🚚 The ForwardDiffuseLightPipeline.onBind method has been removed as it's no longer required.
    • 🚚 The ForwardDiffuseLightPipeline.setNormalMap method has been removed as it's no longer required.
    • ForwardDiffuseLightPipeline.bind is a new method that handles setting-up the shader uniforms.
    • The ForwardDiffuseLightPipeline.batchTexture method has been rewritten to use the Texture Tint Pipeline function instead.
    • The ForwardDiffuseLightPipeline.batchSprite method has been rewritten to use the Texture Tint Pipeline function instead.
    • ForwardDiffuseLightPipeline.lightCount is a new property that stores the previous number of lights rendered.
    • ForwardDiffuseLightPipeline.getNormalMap is a new method that will look-up and return a normal map for the given object.

    Lights

    • ⚡️ Light.dirty is a new property that controls if the light is dirty, or not, and needs its uniforms updating.
    • Light has been recoded so that all of its properties are now setters that activate its dirty flag.
    • LightsManager.destroy will now clear the lightPool array when destroyed, where-as previously it didn't.
    • LightsManager.cull now takes the viewport height from the renderer instead of the game config (thanks zenwaichi)

    WebGL ModelViewProjection API Changes

    The ModelViewProjection object contained a lot of functions that Phaser never used internally. These have now been
    🏗 moved to external functions, which can be easily excluded from Custom builds to save space.

    ⚡️ If you used any of them in your code, please update to the new function names below:

    • Phaser.Renderer.WebGL.MVP is a new namespace under which the Model View Projection functions now live.
    • projIdentity is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ProjectIdentity
    • projPersp is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ProjectPerspective
    • modelRotateX is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.RotateX
    • modelRotateY is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.RotateY
    • modelRotateZ is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.RotateZ
    • viewLoad is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ViewLoad
    • viewRotateX is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ViewRotateX
    • viewRotateY is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ViewRotateY
    • viewRotateZ is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ViewRotateZ
    • viewScale is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ViewScale
    • viewTranslate is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ViewTranslate
    • modelIdentity is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.Identity
    • modelScale is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.Scale
    • modelTranslate is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.Translate
    • viewIdentity is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ViewIdentity
    • viewLoad2D is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ViewLoad2D
    • projOrtho is now available as a stand-alone function Phaser.Renderer.WebGL.MVP.ProjectOrtho
    • Phaser.Renderer.WebGL.MVP.SetIdentity is a new function the others use, to save on space.

    ⚡️ BitmapText New Features, Updates and API Changes

    • BitmapText.setCharacterTint is a new method that allows you to set a tint color (either additive, or fill) on a specific range of characters within a static Bitmap Text. You can specify the start and length offsets and a per-corner tint color.
    • BitmapText.setWordTint is a new method that allows you to set a tint color (either additive, or fill) on all matching words within a static Bitmap Text. You can specify the word by string, or numeric offset, and the number of replacements to tint.
    • BitmapText.setDropShadow is a new method that allows you to apply a drop shadow effect to a Bitmap Text object. You can set the horizontal and vertical offset of the shadow, as well as the color and alpha levels. Call this method with no parameters to clear a shadow.
    • ⚡️ BitmapTextWebGLRenderer has been rewritten from scratch to make use of the new pre-cached WebGL uv texture and character location data generated by GetBitmapTextSize. This has reduced the number of calculations made in the function dramatically, as it no longer has work out glyph advancing or offsets during render, but only when the text content updates.
    • BitmapText.getCharacterAt is a new method that will return the character data from the BitmapText at the given x and y corodinates. The character data includes the code, position, dimensions and glyph information.
    • The BitmapTextSize object returned by BitmapText.getTextBounds has a new property called characters which is an array that contains the scaled position coordinates of each character in the BitmapText, which you could use for tasks such as determining which character in the BitmapText was clicked.
    • 📜 ParseXMLBitmapFont will now calculate the WebGL uv data for the glyphs during parsing. This avoids it having to be done during rendering, saving CPU cycles on an operation that never changes.
    • 📜 ParseXMLBitmapFont will now create a Frame object for each glyph. This means you could, for example, create a Sprite using the BitmapText texture and the glyph as the frame key, i.e.: this.add.sprite(x, y, fontName, 'A').
    • 📄 BitmapTextWord, BitmapTextCharacter and BitmapTextLines are three new type defs that are now part of the BitmapTextSize config object, as returned by getTextBounds. This improves the TypeScript defs and JS Docs for this object.
    • ⚡️ The signature of the ParseXMLBitmapFont function has changed. The frame parameter is no longer optional, and is now the second parameter in the list, instead of being the 4th. If you call this function directly, please update your code.
    • ⚡️ The BitmapText.getTextBounds method was being called every frame, even if the bounds didn't change, potentially costing a lot of CPU time depending on the text length and quantity of them. It now only updates the bounds if they change.
    • The GetBitmapTextSize function used Math.round on the values, if the round parameter was true, which didn't create integers. It now uses Math.ceil instead to give integer results.
    • ⚡️ The GetBitmapTextSize function has a new boolean parameter updateOrigin, which will adjust the origin of the parent BitmapText if set, based on the new bounds calculations.
    • BitmapText.preDestroy is a new method that will tidy-up all of the BitmapText data during object destruction.
    • BitmapText.dropShadowX is a new property that controls the horizontal offset of the drop shadow on the Bitmap Text.
    • BitmapText.dropShadowY is a new property that controls the vertical offset of the drop shadow on the Bitmap Text.
    • BitmapText.dropShadowColor is a new property that sets the color of the Bitmap Text drop shadow.
    • BitmapText.dropShadowAlpha is a new property that sets the alpha of the Bitmap Text drop shadow.
    • BatchChar is a new internal private function for batching a single character of a Bitmap Text to the pipeline.
    • If you give an invalid Bitmap Font key, the Bitmap Text object will now issue a console.warn.
    • Setting the color value in the DynamicBitmapText.setDisplayCallback would inverse the red and blue channels if the color was not properly encoded for WebGL. It is now encoded automatically, meaning you can pass normal hex values as the colors in the display callback. Fix #5225 (thanks @teebarjunk)
    • If you apply setSize to the Dynamic BitmapText the scissor is now calculated based on the parent transforms, not just the local ones, meaning you can crop Bitmap Text objects that exist within Containers. Fix #4653 (thanks @lgibson02)
    • 📜 ParseXMLBitmapFont has a new optional parameter texture. If defined, this Texture is populated with Frame data, one frame per glyph. This happens automatically when loading Bitmap Text data in Phaser.

    🆕 New Features

    • WebGLRenderer.setInt1iv will allow you to look-up and set a 1iv uniform on the given shader.
    • Geom.Intersects.GetLineToLine is a new function that will return a Vector3 containing the point of intersection between 2 line segments, with the z property holding the distance value.
    • Geom.Intersects.GetLineToPolygon is a new function that checks for the closest point of intersection between a line segment and an array of polygons.
    • Geom.Polygon.Translate is a new function that allows you to translate all the points of a polygon by the given values.
    • Phaser.Types.Math.Vector3Like is a new data type representing as Vector 3 like object.
    • Phaser.Types.Math.Vector4Like is a new data type representing as Vector 4 like object.
    • Transform.getLocalPoint is a new method, available on all Game Objects, that takes an x / y pair and translates them into the local space of the Game Object, factoring in parent transforms and display origins.
    • 🔌 The KeyboardPlugin will now track the key code and timestamp of the previous key pressed and compare it to the current event. If they match, it will skip the event. On some systems if you were to type quickly, you would sometimes get duplicate key events firing (the exact same event firing more than once). This is now prevented from happening.
    • Display.Color.GetColorFromValue is a new function that will take a hex color value and return it as an integer, for use in WebGL. This is now used internally by the Tint component and other classes.
    • 🚚 Utils.String.RemoveAt is a new function that will remove a character from the given index in a string and return the new string.
    • Frame.setUVs is a new method that allows you to directly set the canvas and UV data for a frame. Use this if you need to override the values set automatically during frame creation.

    ⚡️ Updates and API Changes

    • Config.batchSize has been increased from 2000 to 4096.
    • ✂ Removed the Deferred Diffuse fragment and vertex shaders from the project, as they're not used.
    • StaticTilemapLayer.upload will now set the vertex attributes and buffer the data, and handles internal checks more efficiently.
    • StaticTilemapLayer now includes the ModelViewProjection mixin, so it doesn't need to modify the pipeline during rendering.
    • WebGLRenderer.textureFlush is a new property that keeps track of the total texture flushes per frame.
    • The TextureTintStripPipeline now extends TextureTintPipeline and just changes the topolgy, vastly reducing the filesize.
    • TransformMatrix.getXRound is a new method that will return the X component, optionally passed via Math.round.
    • TransformMatrix.getYRound is a new method that will return the Y component, optionally passed via Math.round.
    • 🗄 The KeyboardPlugin no longer emits keydown_ events. These were replaced with keydown- events in v3.15. The previous event string was deprecated in v3.20.
    • 🗄 The KeyboardPlugin no longer emits keyup_ events. These were replaced with keyup- events in v3.15. The previous event string was deprecated in v3.20.
    • ⚡️ The ScaleManager.updateBounds method is now called every time the browser fires a 'resize' or 'orientationchange' event. This will update the offset of the canvas element Phaser is rendering to, which is responsible for keeping input positions correct. However, if you change the canvas position, or visibility, via any other method (i.e. via an Angular route) you should call the updateBounds method directly, yourself.

    🐛 Bug Fixes

    • RenderTexture.resize (which is called from setSize) wouldn't correctly set the TextureSource.glTexture property, leading to bindTexture: attempt to use a deleted object errors under WebGL.
    • The MatterAttractors plugin, which enables attractors between bodies, has been fixed. The original plugin only worked if the body with the attractor was first in the world bodies list. It can now attract any body, no matter where in the world list it is. Fix #5160 (thanks @strahius)
    • 🚚 The KeyboardManager and KeyboardPlugin were both still checking for the InputManager.useQueue property, which was removed several versions ago.
    • In Arcade Physics, Dynamic bodies would no longer hit walls when riding on horizontally moving platforms. The horizontal (and vertical) friction is now re-applied correctly in these edge-cases. Fix #5210 (thanks @Dercetech @samme)
    • Calling Rectangle.setSize() wouldn't change the underlying geometry of the Shape Game Object, causing any stroke to be incorrectly rendered after a size change.

    📚 Examples, Documentation and TypeScript

    📄 My thanks to the following for helping with the Phaser 3 Examples, Docs and TypeScript definitions, either by reporting errors, fixing them or helping author the docs:

    @samme @16patsle @scott20145