Skip to content
Pre-release
Pre-release

@photonstorm photonstorm released this Sep 8, 2020 · 290 commits to master since this release

WebGL Pipeline Updates

If you use a custom WebGL Pipeline in your game, you must update your code in order to use Phaser 3.50.

Due to the huge amount of work that has taken place in this area, all of the pipelines have been renamed. If you extend any of these pipelines or use them in your game code (referenced by name), then please update accordingly. The name changes are:

  • TextureTintPipeline is now called the MultiPipeline.
  • TextureTintStripPipeline is now called the RopePipeline.
  • ForwardDiffuseLightPipeline is now called the LightPipeline.

To match the new pipeline names, the shader source code has also been renamed.

  • ForwardDiffuse.frag is now called Light.frag.
  • TextureTint.frag is now called Multi.frag.
  • TextureTint.vert is now called Multi.vert.

Other pipeline changes are as follows:

  • Types.Renderer.WebGL.WebGLPipelineConfig is a new TypeDef that helps you easily configure your own Custom Pipeline when using TypeScript and also provides better JSDocs.
  • Types.Renderer.WebGL.WebGLPipelineAttributesConfig is a new TypeDef that helps you easily configure the attributes for your own Custom Pipelines when using TypeScript and also provides better JSDocs.
  • All pipelines will now work out the renderer property automatically, so it's no longer required in the config.
  • All pipelines will now work out the gl property automatically, so it's no longer required in the config.
  • All pipelines will now extract the name property from the config, allowing you to set it externally.
  • All pipelines will now extract the vertexCapacity property from the config, allowing you to set it externally.
  • All pipelines will now extract the vertexSize property from the config, allowing you to set it externally.
  • All pipelines will now extract the vertexData property from the config, allowing you to set it externally.
  • All pipelines will now extract the attributes property from the config, allowing you to set it externally.
  • All pipelines will now extract the topology property from the config, allowing you to set it externally.

Single Pipeline

There is also a new pipeline called SinglePipeline, created to emulate the old TextureTintPipeline. This special pipeline uses just a single texture and makes things a lot easier if you wish to create a custom pipeline, but not have to recode your shaders to work with multiple textures. Instead, just extend SinglePipeline, where-as before you extended the TextureTintPipeline and you won't have to change any of your shader code. However, if you can, you should update it to make it perform faster, but that choice is left up to you.

WebGL Multi-Texture Rendering

The Multi Pipeline (previously 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 draw-call 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.
  • 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 that 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.
  • Renderer.WebGL.Utils.parseFragmentShaderMaxTextures is a new function that will take fragment shader source and search it for %count% and %forloop% declarations, replacing them with the required GLSL for multi-texture support, returning the modified source.

Light Pipeline Changes

The Light Pipeline (previously called the Forward Diffuse Light Pipeline), which is responsible for rendering lights under WebGL, has been rewritten to work with the new Multi Pipeline features. 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.
  • The ForwardDiffuseLightPipeline.defaultNormalMap property has changed, it's now an object with a glTexture property that maps to the pipelines default normal map.
  • 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 per-corner tint colors.
  • 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 coordinates. 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.

Update List Changes

The way in which Game Objects add themselves to the Scene Update List has changed. Instead of being added by the Factory methods, they will now add and remove themselves based on the new ADDED_TO_SCENE and REMOVED_FROM_SCENE events. This means, you can now add Sprites directly to a Container, or Group, and they'll animate properly without first having to be part of the Display List. The full set of changes and new features relating to this follow:

  • GameObjects.Events.ADDED_TO_SCENE is a new event, emitted by a Game Object, when it is added to a Scene, or a Container that is part of the Scene.
  • GameObjects.Events.REMOVED_FROM_SCENE is a new event, emitted by a Game Object, when it is removed from a Scene, or a Container that is part of the Scene.
  • Scenes.Events.ADDED_TO_SCENE is a new event, emitted by a Scene, when a new Game Object is added to the display list in the Scene, or a Container that is on the display list.
  • Scenes.Events.REMOVED_FROM_SCENE is a new event, emitted by a Scene, when it a Game Object is removed from the display list in the Scene, or a Container that is on the display list.
  • GameObject.addedToScene is a new method that custom Game Objects can use to perform additional set-up when a Game Object is added to a Scene. For example, Sprite uses this to add itself to the Update List.
  • GameObject.removedFromScene is a new method that custom Game Objects can use to perform additional tear-down when a Game Object is removed from a Scene. For example, Sprite uses this to remove themselves from the Update List.
  • Game Objects no longer automatically remove themselves from the Update List during preDestroy. This should be handled directly in the removedFromScene method now.
  • The Container will now test to see if any Game Object added to it is already on the display list, or not, and emit its ADDED and REMOVED events accordingly. Fix #5267 #3876 (thanks @halgorithm @mbpictures)
  • DisplayList.events is a new property that references the Scene's Event Emitter. This is now used internally.
  • DisplayList.addChildCallback is a new method that overrides the List callback and fires the new ADDED events.
  • DisplayList.removeChildCallback is a new method that overrides the List callback and fires the new REMOVED events.
  • GameObjectCreator.events is a new property that references the Scene's Event Emitter. This is now used internally.
  • GameObjectFactory.events is a new property that references the Scene's Event Emitter. This is now used internally.
  • ProcessQueue.checkQueue is a new boolean property that will make sure only unique objects are added to the Process Queue.
  • The Update List now uses the new checkQueue property to ensure no duplicate objects are on the active list.
  • DOMElementFactory, ExternFactory, ParticleManagerFactor, RopeFactory and SpriteFactory all no longer add the objects to the Update List, this is now handled by the ADDED events instead.
  • Sprite, Rope, ParticleEmitterManager, Extern and DOMElement now all override the addedToScene and removedFromScene callbacks to handle further set-up tasks.

Spine Plugin Updates

  • The Spine Runtimes have been updated to 3.8.95, which are the most recent non-beta versions. Please note, you will need to re-export your animations if you're working in a version of Spine lower than 3.8.20.
  • SpineContainer is a new Game Object available via this.add.spineContainer to which you can add Spine Game Objects only. It uses a special rendering function to retain batching, even across multiple container or Spine Game Object instances, resulting in dramatically improved performance over using regular Containers.
  • A Spine Game Object with setVisible(false) will no longer still cause internal gl commands and is now properly skipped, retaining any current batch in the process. Fix #5174 (thanks @Kitsee)
  • The Spine Game Object WebGL Renderer will no longer clear the type if invisible and will only end the batch if the next type doesn't match.
  • The Spine Game Object WebGL Renderer will no longer rebind the pipeline if it was the final object on the display list, saving lots of gl commands.
  • The Webpack build scripts have all been updated for Webpack 4.44.x. Fix #5243 (thanks @RollinSafary)
  • There is a new npm script npm run plugin.spine.runtimes which will build all of the Spine runtimes, for ingestion by the plugin. Note: You will need to check-out the Esoteric Spine Runtimes repo into plugins/spine/ in order for this to work.
  • Spine Game Objects can now be rendered to Render Textures. Fix #5184 (thanks @Kitsee)
  • Using > 128 Spine objects in a Container would cause a WebGL: INVALID_OPERATION: vertexAttribPointer: no ARRAY_BUFFER is bound and offset is non-zero error if you added any subsequent Spine objects to the Scene. There is now no limit. Fix #5246 (thanks @d7561985)
  • The Spine Plugin will now work in HEADLESS mode without crashing. Fix #4988 (thanks @raimon-segura)
  • Spine Game Objects now use -1 as their default blend mode, which means 'skip setting it'.
  • The Spine TypeScript defs have been updated for the latest version of the plugin and to add SpineContainers.
  • The SpineGameObject.setAnimation method will now use the trackIndex parameter if ignoreIfPlaying is set and run the check against this track index. Fix #4842 (thanks @vinerz)
  • The SpineFile will no longer throw a warning if adding a texture into the Texture Manager that already exists. This allows you to have multiple Spine JSON use the same texture file, however, it also means you now get no warning if you accidentally load a texture that exists, so be careful with your keys! Fix #4947 (thanks @Nomy1)
  • The Spine Plugin destroy method will now no longer remove the Game Objects from the Game Object Factory, or dispose of the Scene Renderer. This means when a Scene is destroyed, it will keep the Game Objects in the factory for other Scene's to use. Fix #5279 (thanks @Racoonacoon)
  • SpinePlugin.gameDestroy is a new method that is called if the Game instance emits a destroy event. It removes the Spine Game Objects from the factory and disposes of the Spine scene renderer.

Animation API New Features and Updates

If you use Animations in your game, please read the following important API changes in 3.50:

The Animation API has had a significant overhaul to improve playback handling. Instead of just playing an animation based on its global key, you can now supply a new PlayAnimationConfig object instead, which allows you to override any of the default animation settings, such as duration, delay and yoyo (see below for the full list). This means you no longer have to create lots of duplicate animations just to change properties such as duration, and can now set them dynamically at run-time as well.

  • The Animation class no longer extends EventEmitter, as it no longer emits any events directly. This means you cannot now listen for events directly from an Animation instance. All of the events are now dispatched by the Game Objects instead.
  • All of the SPRITE_ANIMATION_KEY events have been removed. Instead, please use the new events which all carry the frameKey parameter, which can be used to handle frame specific events.
  • ANIMATION_UPDATE_EVENT is a new event that is emitted from a Sprite when an animation updates, i.e. its frame changes.
  • ANIMATION_STOP_EVENT is a new event that is emitted from a Sprite when its current animation is stopped. This can happen if any of the stop methods are called, or a new animation is played prior to this one reaching completion. Fix #4894 (thanks @scott20145)
  • The Game Object Component.Animation component has been renamed to AnimationState and has moved namespace. It's now in Phaser.Animations instead of GameObjects.Components to help differentiate it from the Animation class when browsing the documentation.
  • The play, playReverse, playAfterDelay, playAfterRepeat and chain Sprite and Animation Component methods can now all take a Phaser.Types.Animations.PlayAnimationConfig configuration object, as well as a string, as the key parameter. This allows you to override any default animation setting with those defined in the config, giving you far greater control over animations on a Game Object level, without needing to globally duplicate them.
  • AnimationState.create is a new method that allows you to create animations directly on a Sprite. These are not global and never enter the Animation Manager, instead risiding within the Sprite itself. This allows you to use the same keys across both local and global animations and set-up Sprite specific local animations.
  • All playback methods: play, playReverse, playAfterDelay and playAfterRepeat will now check to see if the given animation key exists locally on the Sprite first. If it does, it's used, otherwise it then checks the global Animation Manager for the key instead.
  • AnimationState.skipMissedFrames is now used when playing an animation, allowing you to create animations that run at frame rates far exceeding the refresh rate, or that will update to the correct frame should the game lag. Feature #4232 (thanks @colorcube)
  • AnimationManager.addMix is a new method that allows you to create mixes between two animations. Mixing allows you to specify a unique delay between a pairing of animations. When playing Animation A on a Game Object, if you then play Animation B, and a mix exists, it will wait for the specified delay to be over before playing Animation B. This allows you to customise smoothing between different types of animation, such as blending between an idle and a walk state, or a running and a firing state.
  • AnimationManager.getMix is a new method that will return the mix duration between the two given animations.
  • AnimationManager.removeMix is a new method that will remove the mixture between either two animations, or all mixtures for the given animation.
  • AnimationState.remove is a new method that will remove a locally stored Animation instance from a Sprite.
  • AnimationState.get is a new method that will return a locally stored Animation instance from the Sprite.
  • AnimationState.exists is a new method that will check if a locally stored Animation exists on the Sprite.
  • The internal AnimationState.remove method has been renamed to globalRemove.
  • AnimationState.textureManager is a new property that references the global Texture Manager.
  • AnimationState.anims is a new property that contains locally created Animations in a Custom Map.
  • AnimationState.play and Sprite.play no longer accept a startFrame parameter. Please set it via the PlayAnimationConfig instead.
  • AnimationState.playReverse and Sprite.playReverse no longer accept a startFrame parameter. Please set it via the PlayAnimationConfig instead.
  • The AnimationState.delayedPlay method has been renamed to playAfterDelay. The parameter order has also changed, so the key now comes first instead of the duration.
  • The AnimationState.stopOnRepeat method has been renamed to stopAfterRepeat
  • The AnimationState.getCurrentKey method has been renamed to getName.
  • AnimationState.getFrameName is a new method that will return the key of the current Animation Frame, if an animation has been loaded.
  • AnimationState.playAfterDelay and Sprite.playAfterDelay are new methods that will play the given animation after the delay in ms expires.
  • AnimationState.playAfterRepeat and Sprite.playAfterRepeat are new methods that will play the given animation after the current animation finishes repeating. You can also specify the number of repeats allowed left to run.
  • The AnimationState.chain method is now available on the Sprite class.
  • The AnimationState.stopAfterDelay method is now available on the Sprite class.
  • The AnimationState.stopAfterRepeat method is now available on the Sprite class.
  • The AnimationState.stopOnFrame method is now available on the Sprite class.
  • AnimationManager.createFromAseprite is a new method that allows you to use animations created in the Aseprite editor directly in Phaser. Please see the comprehensive documentation for this method for full details on how to do this.
  • AnimationState now handles all of the loading of the animation. It no longer has to make calls out to the Animation Manager or Animation instance itself and will load the animation data directly, replacing as required from the optional PlayAnimationConfig. This improves performance and massively reduces CPU calls in animation heavy games.
  • The PlayAnimationConfig.frameRate property lets you optionally override the animation frame rate.
  • The PlayAnimationConfig.duration property lets you optionally override the animation duration.
  • The PlayAnimationConfig.delay property lets you optionally override the animation delay.
  • The PlayAnimationConfig.repeat property lets you optionally override the animation repeat counter.
  • The PlayAnimationConfig.repeatDelay property lets you optionally override the animation repeat delay value.
  • The PlayAnimationConfig.yoyo property lets you optionally override the animation yoyo boolean.
  • The PlayAnimationConfig.showOnStart property lets you optionally override the animation show on start value.
  • The PlayAnimationConfig.hideOnComplete property lets you optionally override the animation hide on complete value.
  • The PlayAnimationConfig.startFrame property lets you optionally set the animation frame to start on.
  • The PlayAnimationConfig.timeScale property lets you optionally set the animation time scale factor.
  • AnimationState.delayCounter is a new property that allows you to control the delay before an animation will start playing. Only once this delay has expired, will the animation START events fire. Fix #4426 (thanks @bdaenen)
  • AnimationState.hasStarted is a new boolean property that allows you to tell if the current animation has started playing, or is still waiting for a delay to expire.
  • AnimationState.showOnStart is a new boolean property that controls if the Game Object should have setVisible(true) called on it when the animation starts.
  • AnimationState.hideOnComplete is a new boolean property that controls if the Game Object should have setVisible(false) called on it when the animation completes.
  • The AnimationState.chain method docs said it would remove all pending animations if called with no parameters. However, it didn't - and now does!
  • The AnimationState.setDelay method has been removed. It never actually worked and you can now perform the same thing by calling either playAfterDelay or setting the delay property in the play config.
  • The AnimationState.getDelay method has been removed. You can now read the delay property directly.
  • The AnimationState.setRepeat method has been removed. You can achieve the same thing by setting the repeat property in the play config, or adjusting the public repeatCounter property if the animation has started.
  • AnimationState.handleStart is a new internal private method that handles the animation start process.
  • AnimationState.handleRepeat is a new internal private method that handles the animation repeat process.
  • AnimationState.handleStop is a new internal private method that handles the animation stop process.
  • AnimationState.handleComplete is a new internal private method that handles the animation complete process.
  • AnimationState.emitEvents is a new internal private method that emits animation events, cutting down on duplicate code.
  • The AnimationState.restart method has a new optional boolean parameter resetRepeats which controls if you want to reset the repeat counter during the restart, or not.
  • Animation.getTotalFrames is a new method that will return the total number of frames in the animation. You can access it via this.anims.currentAnim.getTotalFrames from a Sprite.
  • Animation.calculateDuration is a new method that calculates the duration, frameRate and msPerFrame for a given animation target.
  • The BuildGameObjectAnimation function now uses the PlayAnimationConfig object to set the values.
  • Sprite.playReverse is a new method that allows you to play the given animation in reverse on the Sprite.
  • Sprite.playAfterDelay is a new method that allows you to play the given animation on the Sprite after a delay.
  • Sprite.stop is a new method that allows you to stop the current animation on the Sprite.
  • AnimationManager.load has been removed as it's no longer required.
  • AnimationManager.staggerPlay has been fixed so you can now pass in negative stagger values.
  • AnimationManager.staggerPlay has a new optional boolean parameter staggerFirst, which allows you to either include or exclude the first child in the stagger calculations.
  • The Animation.completeAnimation method has been removed as it's no longer required.
  • The Animation.load method has been removed as it's no longer required.
  • The Animation.setFrame method has been removed as it's no longer required.
  • The Animation.getFirstTick method has no longer needs the includeDelay parameter, as it's handled by AnimationState now.
  • The Animation.getFrames method has a new optional boolean parameter sortFrames which will run a numeric sort on the frame names after constructing them, if a string-based frame is given.
  • Types.Animations.Animation has a new boolean property sortFrames, which lets Phaser numerically sort the generated frames.
  • AnimationState.timeScale is a new public property that replaces the old private _timeScale property.
  • AnimationState.delay is a new public property that replaces the old private _delay property.
  • AnimationState.repeat is a new public property that replaces the old private _repeat property.
  • AnimationState.repeatDelay is a new public property that replaces the old private _repeatDelay property.
  • AnimationState.yoyo is a new public property that replaces the old private _yoyo property.
  • AnimationState.inReverse is a new public property that replaces the old private _reverse property.
  • AnimationState.startAnimation is a new public method that replaces the old private _startAnimation method.
  • The AnimationState.getProgress method has been fixed so it will return correctly if the animation is playing in reverse.
  • The AnimationState.globalRemove method will now always be called when an animation is removed from the global Animation Manager, not just once.
  • The AnimationState.getRepeat method has now been removed. You can get the value from the repeat property.
  • The AnimationState.setRepeatDelay method has now been removed. You can set the value using the repeatDelay config property, or changing it at run-time.
  • AnimationState.complete is a new method that handles the completion in animation playback.
  • The AnimationState.setTimeScale method has now been removed. You can set the value using the timeScale config property, or changing it at run-time.
  • The AnimationState.getTimeScale method has now been removed. You can read the value using the timeScale property.
  • The AnimationState.getTotalFrames method has been fixed and won't error if called when no animation is loaded.
  • The AnimationState.setYoyo method has now been removed. You can set the value using the yoyo config property, or changing it at run-time.
  • The AnimationState.getYoyo method has now been removed. You can read the value using the yoyo property.
  • The AnimationState.stopAfterRepeat method now has an optional parameter repeatCount, so you can tell the animation to stop after a specified number of repeats, not just 1.
  • When playing an animation in reverse, if it reached the first frame and had to repeat, it would then jump to the frame before the final frame and carry on, skipping out the final frame.
  • The AnimationState.updateFrame method has now been removed. Everything is handled by setCurrentFrame instead, which removes one extra step out of the update process.
  • GenerateFrameNames will now console.warn if the generated frame isn't present in the texture, which should help with debugging animation creation massively.
  • GenerateFrameNumbers will now console.warn if the generated frame isn't present in the texture, which should help with debugging animation creation massively.
  • GenerateFrameNumbers would include the __BASE frame by mistake in its calculations. This didn't end up in the final animation, but did cause a cache miss when building the animation.
  • GenerateFrameNumbers can now accept the start and end parameters in reverse order, meaning you can now do { start: 10, end: 1 } to create the animation in reverse.
  • GenerateFrameNames can now accept the start and end parameters in reverse order, meaning you can now do { start: 10, end: 1 } to create the animation in reverse.

New Features

  • 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.Intersects.GetLineToPoints is a new function that checks for the closest point of intersection between a line segment and an array of points, where each pair of points form a line segment.
  • Geom.Intersects.GetRaysFromPointToPolygon is a new function that emits rays out from the given point and detects for intersection against all given polygons, returning the points of intersection in the results array.
  • Geom.Polygon.Translate is a new function that allows you to translate all the points of a polygon by the given values.
  • Geom.Polygon.Simplify is a new function that takes a polygon and simplifies the points by running them through a combination of Douglas-Peucker and Radial Distance algorithms, potentially dramatically reducing the number of points while retaining its shape.
  • WebGLRenderer.setInt1iv will allow you to look-up and set a 1iv uniform on the given shader.
  • 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.
  • TweenManager.getTweensOf has a new parameter includePending. If set, it will also check the pending tweens for the given targets and return those in the results as well. Fix #5260 (thanks @pcharest2000)
  • WebGLPipeline.hasBooted is a new boolean property that tracks if the pipeline has been booted or not, which is now far more important in 3.5 than in previous versions. This is checked in the WebGLRenderer.addPipeline method, and if not set, the pipeline is booted. Fix #5251 #5255 (thanks @telinc1 @rexrainbow)
  • The WebGL Renderer will now add the pipelines during the boot method, instead of init.
  • You can now use this.renderer from within a Scene, as it's now a Scene-level property and part of the Injection Map.
  • Clock.addEvent can now take an existing TimerEvent object, as well as a config object. If a TimerEvent is given it will be removed from the Clock, reset and then added. This allows you to pool TimerEvents rather than constantly create and delete them. Fix #4115 (thanks @jcyuan)
  • Clock.removeEvent is a new method that allows you to remove a TimerEvent, or an array of them, from all internal lists of the current Clock.
  • Group.getMatching is a new method that will return any members of the Group that match the given criteria, such as getMatching('visible', true) (thanks @atursams)
  • ArcadePhysics.disableUpdate is a new method that will prevent the Arcade Physics World update method from being called when the Scene updates. By disabling it, you're free to call the update method yourself, passing in your own delta and time values.
  • ArcadePhysics.enableUpdate is a new method that will make the Arcade Physics World update in time with the Scene update. This is the default, so only call this if you have specifically disabled it previously.
  • ArcadeWorldConfig.customUpdate is a new boolean property you can set in the Arcade Physics config object, either in the Scene or in the Game Config. If true the World update will never be called, allowing you to call it yourself from your own component. Close #5190 (thanks @cfortuner)
  • Utils.Array.SortByDigits is a new function that takes the given array of strings and runs a numeric sort on it, ignoring any non-digits.
  • GroupCreateConfig, which is used when calling Group.createMultiple or Group.createFromConfig, can now accept the following new properties: setOrigin: { x, y, stepX, stepY } which are applied to the items created by the Group.

Updates and API Changes

  • Earcut, used for polygon triangulation, has been updated from 2.1.4 to 2.2.2.
  • Earcut has now been exposed and is available via Geom.Polygon.Earcut and is fully documented.
  • 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.
  • The constant Phaser.Renderer.WebGL.BYTE value has been removed as it wasn't used internally.
  • The constant Phaser.Renderer.WebGL.SHORT value has been removed as it wasn't used internally.
  • The constant Phaser.Renderer.WebGL.UNSIGNED_BYTE value has been removed as it wasn't used internally.
  • The constant Phaser.Renderer.WebGL.UNSIGNED_SHORT value has been removed as it wasn't used internally.
  • The constant Phaser.Renderer.WebGL.FLOAT value has been removed as it wasn't used internally.
  • global.Phaser = Phaser has been removed, as it's no longer required by the UMD loader, which should make importing in Angular 10 easier. Fix #5212 (thanks @blackyale)
  • Pointer.downTime now stores the event timestamp of when the first button on the input device was pressed down, not just when button 1 was pressed down.
  • Pointer.upTime now stores the event timestamp of when the final depressed button on the input device was released, not just when button 1 was released.
  • The Pointer.getDuration method now uses the new Pointer downTime and upTime values, meaning it will accurately report the duration of when any button is being held down, not just the primary one. Fix #5112 (thanks @veleek)
  • The BaseShader default vertex shader now includes the outTexCoord vec2 varying, mapped to be the same as that found in the pipeline shaders. Fix #5120 (@pavel-shirobok)
  • When using the GameObjectCreator for Containers you can now specify the children property in the configuration object.
  • WebGLRenderer.finalType is a new boolean property that signifies if the current Game Object being rendered is the final one in the list.
  • The WebGLRenderer.updateCanvasTexture method will now set gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL to true, which should stop issues where you update a Text Game Object, having added a Render Texture or Spine Game Object to the Scene after it, which switches the PMA setting. Fix #5064 #5155 (thanks @hugoruscitti @immangrove-supertree)
  • Textures.Parsers.JSONHash will now perform a hasOwnProperty check when iterating the frames, skipping anything that isn't a direct property. This should allow you to use generated atlas data that comes from JSON.parse. Fix #4768 (thanks @RollinSafary)
  • The Camera3D Plugin has been rebuilt for Phaser 3.50 and the webpack config updated. This plugin is now considered deprecated and will not be updated beyond this release.
  • Tween.seek will no longer issue a console warning for 'Tween.seek duration too long', it's now up to you to check on the performance of tween seeking.
  • WebGLRenderer.previousPipeline is a new property that is set during a call to clearPipeline and used during calls to rebindPipeline, allowing the renderer to rebind any previous pipeline, not just the Multi Pipeline.
  • The WebGLRenderer.rebindPipeline method has been changed slightly. Previously, you had to specify the pipelineInstance, but this is now optional. If you don't, it will use the new previousPipeline property instead. If not set, or none given, it will now return without throwing gl errors as well.
  • If inputWindowEvents is set in the Game Config, then the MouseManager will now listen for the events on window.top instead of just window, which should help in situations where the pointer is released outside of an embedded iframe. Fix #4824 (thanks @rexrainbow)
  • Types.GameObjects.Text.GetTextSizeObject is a new type def for the GetTextSize function results.
  • The Arcade.Body.resetFlags method has a new optional boolean parameter clear. If set, it clears the wasTouching flags on the Body. This happens automatically when Body.reset is called. Previous to this, the flags were not reset until the next physics step (thanks @samme)
  • Utils.Array.StableSort has been recoded. It's now based on Two-Screens stable sort 0.1.8 and has been updated to fit into Phaser better and no longer create any window bound objects. The inplace function has been removed, just call StableSort(array) directly now. All classes that used StableSort.inplace have been updated to call it directly.
  • If a Scene is paused, or sent to sleep, it will automatically call Keyboard.resetKeys. This means that if you hold a key down, then sleep or pause a Scene, then release the key and resume or wake the Scene, it will no longer think it is still being held down (thanks @samme)
  • Actions.setOrigin will now call updateDisplayOrigin on the items array, otherwise the effects can't be seen when rendering.
  • You can now set the ArcadeWorld.fixedStep property via the ArcadeWorldConfig object (thanks @samme)
  • Utils.Array.NumerArray can now accept the start and end parameters in reverse order, i.e. 10, 1 will generate a number array running from 10 to 1. Internally it has also been optimized to skip string based returns.

Namespace Updates

  • The Phaser.Curves.MoveTo function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.DOM.GetInnerHeight function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.GameObjects.Bob class has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.GameObjects.LightsManager class has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.GameObjects.LightsPlugin class has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.GameObjects.Particles.EmitterOp class has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.GameObjects.GetTextSize function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.GameObjects.MeasureText function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.GameObjects.TextStyle function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Input.CreatePixelPerfectHandler function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Physics.Arcade.Components.OverlapCirc function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Physics.Arcade.Components.OverlapRect function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Physics.Arcade.Tilemap namespace has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Physics.Matter.Components namespace has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Physics.Matter.Events namespace has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Physics.Matter.MatterGameObject class has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Physics.Matter.PointerConstraint class has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Scenes.GetPhysicsPlugins function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Scenes.GetScenePlugins function has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Structs.Events namespace has now been exposed on the Phaser namespace (thanks @samme)
  • The Phaser.Tilemaps.Parsers.Tiled function has now been exposed on the Phaser namespace (thanks @samme)
  • Every single Tilemap.Component function has now been made public. This means you can call the Component functions directly, should you need to, outside of the Tilemap system.

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.
  • RenderTexture.fill would fail to fill the correct area under WebGL if the RenderTexture wasn't the same size as the Canvas. It now fills the given region properly.
  • 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.
  • The ProcessQueue was emitting the wrong events internally. It now emits 'add' and 'remove' correctly (thanks @halilcakar)
  • The GridAlign action didn't work if only the height parameter was set. Fix #5019 (thanks @halilcakar)
  • The Color.HSVToRGB function has been rewritten to use the HSL and HSV formula from Wikipedia, giving much better results. Fix #5089 (thanks @DiamondeX)
  • Previously, the easeParams array within a Tweens props object, or a multi-object tween, were ignored and it was only used if set on the root Tween object. It will now work correctly set at any depth. Fix #4292 (thanks @willblackmore)
  • When using Camera.setRenderToTexture its zoom and rotation values would be applied twice. Fix #4221 #4924 #4713 (thanks @wayfu @DanMcgraw @pavel-shirobok)
  • GameObjects.Shape.Grid would render a white fill even if you passed undefined as the fill color in the constructor. It now doesn't render cells if no fill color is given.

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 @khasanovbi @mk360 @volkans80 @jaabberwocky @maikthomas @atursams @LearningCode2023 @DylanC @BenjaminDRichards

Assets 4
Pre-release
Pre-release

@photonstorm photonstorm released this Aug 21, 2020 · 497 commits to master since this release

WebGL Pipeline Updates

If you use a custom WebGL Pipeline in your game, you must update in order to use Phaser 3.50.

Due to the huge amount of work that has taken place in this area, all of the pipelines have been renamed. If you extend any of these pipelines or use them in your game code (referenced by name), then please update accordingly. The name changes are:

  • TextureTintPipeline is now called the MultiPipeline.
  • TextureTintStripPipeline is now called the RopePipeline.
  • ForwardDiffuseLightPipeline is now called the LightPipeline.

To match the new pipeline names, the shader source code has also been renamed.

  • ForwardDiffuse.frag is now called Light.frag.
  • TextureTint.frag is now called Multi.frag.
  • TextureTint.vert is now called Multi.vert.

Other pipeline changes are as follows:

  • Types.Renderer.WebGL.WebGLPipelineConfig is a new TypeDef that helps you easily configure your own Custom Pipeline when using TypeScript and also provides better JSDocs.
  • Types.Renderer.WebGL.WebGLPipelineAttributesConfig is a new TypeDef that helps you easily configure the attributes for your own Custom Pipelines when using TypeScript and also provides better JSDocs.
  • All pipelines will now work out the renderer property automatically, so it's no longer required in the config.
  • All pipelines will now work out the gl property automatically, so it's no longer required in the config.
  • All pipelines will now extract the name property from the config, allowing you to set it externally.
  • All pipelines will now extract the vertexCapacity property from the config, allowing you to set it externally.
  • All pipelines will now extract the vertexSize property from the config, allowing you to set it externally.
  • All pipelines will now extract the vertexData property from the config, allowing you to set it externally.
  • All pipelines will now extract the attributes property from the config, allowing you to set it externally.
  • All pipelines will now extract the topology property from the config, allowing you to set it externally.

Single Pipeline

There is also a new pipeline called SinglePipeline, created to emulate the old TextureTintPipeline. This special pipeline uses just a single texture and makes things a lot easier if you wish to create a custom pipeline, but not have to recode your shaders to work with multiple textures. Instead, just extend SinglePipeline, where-as before you extended the TextureTintPipeline and you won't have to change any of your shader code. However, if you can, you should update it to make it perform faster, but that choice is left up to you.

WebGL Multi-Texture Rendering

The Multi Pipeline (previously 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 draw call-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.
  • 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 that 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.
  • Renderer.WebGL.Utils.parseFragmentShaderMaxTextures is a new function that will take fragment shader source and search it for %count% and %forloop% declarations, replacing them with the required GLSL for multi-texture support, returning the modified source.

Light Pipeline Changes

The Light Pipeline (previously called the Forward Diffuse Light Pipeline), which is responsible for rendering lights under WebGL, has been rewritten to work with the new Multi Pipeline features. 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.
  • The ForwardDiffuseLightPipeline.defaultNormalMap property has changed, it's now an object with a glTexture property that maps to the pipelines default normal map.
  • 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 per-corner tint colors.
  • 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 coordinates. 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

  • 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.Intersects.GetLineToPoints is a new function that checks for the closest point of intersection between a line segment and an array of points, where each pair of points form a line segment.
  • Geom.Intersects.GetRaysFromPointToPolygon is a new function that emits rays out from the given point and detects for intersection against all given polygons, returning the points of intersection in the results array.
  • Geom.Polygon.Translate is a new function that allows you to translate all the points of a polygon by the given values.
  • Geom.Polygon.Simplify is a new function that takes a polygon and simplifies the points by running them through a combination of Douglas-Peucker and Radial Distance algorithms, potentially dramatically reducing the number of points while retaining its shape.
  • WebGLRenderer.setInt1iv will allow you to look-up and set a 1iv uniform on the given shader.
  • 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.
  • TweenManager.getTweensOf has a new parameter includePending. If set, it will also check the pending tweens for the given targets and return those in the results as well. Fix #5260 (thanks @pcharest2000)
  • WebGLPipeline.hasBooted is a new boolean property that tracks if the pipeline has been booted or not, which is now far more important in 3.5 than in previous versions. This is checked in the WebGLRenderer.addPipeline method, and if not set, the pipeline is booted. Fix #5251 #5255 (thanks @telinc1 @rexrainbow)
  • The WebGL Renderer will now add the pipelines during the boot method, instead of init.

Updates and API Changes

  • Earcut, used for polygon triangulation, has been updated from 2.1.4 to 2.2.2.
  • 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.
  • The constant Phaser.Renderer.WebGL.BYTE value has been removed as it wasn't used internally.
  • The constant Phaser.Renderer.WebGL.SHORT value has been removed as it wasn't used internally.
  • The constant Phaser.Renderer.WebGL.UNSIGNED_BYTE value has been removed as it wasn't used internally.
  • The constant Phaser.Renderer.WebGL.UNSIGNED_SHORT value has been removed as it wasn't used internally.
  • The constant Phaser.Renderer.WebGL.FLOAT value has been removed as it wasn't used internally.

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.
  • RenderTexture.fill would fail to fill the correct area under WebGL if the RenderTexture wasn't the same size as the Canvas. It now fills the given region properly.
  • 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.
  • The ProcessQueue was emitting the wrong events internally. It now emits 'add' and 'remove' correctly (thanks @halilcakar)

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 @khasanovbi @mk360

Assets 4
Pre-release
Pre-release

@photonstorm photonstorm released this Aug 6, 2020 · 544 commits to master since this release

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.
  • 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.
  • The ForwardDiffuseLightPipeline.defaultNormalMap property has changed, it's now an object with a glTexture property that maps to the pipelines default normal map.
  • 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

Assets 4
Pre-release
Pre-release

@photonstorm photonstorm released this Jul 24, 2020 · 646 commits to master since this release

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.
  • 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.
  • The ForwardDiffuseLightPipeline.defaultNormalMap property has changed, it's now an object with a glTexture property that maps to the pipelines default normal map.
  • 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.

New Features

  • WebGLRenderer.setInt1iv will allow you to look-up and set a 1iv uniform on the given shader.

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.

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)

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

Assets 4

@photonstorm photonstorm released this Jul 14, 2020 · 743 commits to master since this release

Version 3.24.1 - Rem - 14th July 2020

  • Reverted the PR that added the parent transform to a Static Tilemap Layer as it broke tilemap rendering when the camera was zoomed (thanks @kainage)
  • Fixed an error with the use of the Vector2Like type in the Math.RotateTo function that caused a TypeScript error on compilation

Version 3.24.0 - Rem - 13th July 2020

Arcade Physics New Features, Updates and Fixes

  • When colliding physics groups with the search tree enabled, there was an unnecessary intersection test for each body returned by the search (thanks @samme)
  • When doing an overlap collision, there was an unnecessary intersection test for each pair of overlapping bodies (thanks @samme)
  • Sprite vs. Static Group collision tests now always use the static tree (thanks @samme)
  • Fixed a bug where if you added a static body to a sprite with scale ≠ 1, the body position was incorrect (thanks @samme)
  • If you passed in an array of children when creating a Physics Group, they didn't receive bodies. Fix #5152 (thanks @samme)
  • New types allow for better docs / TypeScript defs especially in the Factory functions: ArcadePhysicsCallback, GameObjectWithBody, GameObjectWithDynamicBody, GameObjectWithStaticBody, ImageWithDynamicBody, ImageWithStaticBody, SpriteWithDynamicBody and SpriteWithStaticBody. Fix #4994 (thanks @samme @gnesher)
  • Body.updateFromGameObject is a new method that extracts the relevant code from preUpdate, allowing you to read the body's new position and center immediately, before the next physics step. It also lets refreshBody work for dynamic bodies, where previously it would error (thanks @samme)
  • Momentum exchange wasn't working correctly vs. immovable bodies. The movable body tended to stop. Fix #4770 (thanks @samme)
  • The Body mass was decreasing the inertia instead of increasing it. Fix #4770 (thanks @samme)
  • The separation vector seemed to be incorrect, causing the slip / slide collisions. The separation is now correct for circle–circle collisions (although not fully for circle–rectangle collisions), part fix #4770 (thanks @samme)
  • The Arcade Body delta was incorrectly calculated on bodies created during the update step, causing the position to be off. Fix #5204 (thanks @zackexplosion @samme)
  • Arcade.Components.Size.setBodySize is a new method available on Arcade Physics Game Objects that allows you to set the body size. This replaces setSize which is now deprecated. Fix #4786 (thanks @wingyplus)

New Features

  • The Animation component has a new property nextAnimsQueue which allows you to sequence Sprite animations to play in order, i.e: this.mole.anims.play('digging').anims.chain('lifting').anims.chain('looking').anims.chain('lowering'); (thanks @tgroborsch)
  • Group.setActive is a new method that will set the active state of a Group, just like it does on other Game Objects (thanks @samme)
  • Group.setName is a new method that will set the name property of a Group, just like it does on other Game Objects (thanks @samme)
  • TWEEN_STOP is a new event dispatched by a Tween when it stops playback (thanks @samme @RollinSafary)
  • You can now specify an onStop callback when creating a Tween as part of the tween config, which is invoked when a Tween stops playback (thanks @samme @RollinSafary)
  • Previously, if you created a timeline and passed no tweens in the config, the timeline would be created but all config properties were ignored. Now the timeline's own properties (completeDelay, loop, loopDelay, useFrames, onStart, onUpdate, onLoop, onYoyo, onComplete, etc.) are set from the config properly (thanks @samme)
  • TextStyle.wordWrapWidth lets you set the maximum width of a line of text (thanks @mikewesthad)
  • TextStyle.wordWrapCallback is a custom function that will is responsible for wrapping the text (thanks @mikewesthad)
  • TextStyle.wordWrapCallbackScope is the scope that will be applied when the wordWrapCallback is invoked (thanks @mikewesthad)
  • TextStyle.wordWrapUseAdvanced controls whether or not to use the advanced wrapping algorithm (thanks @mikewesthad)
  • KeyboardPlugin.removeAllKeys is a new method that allows you to automatically remove all Key instances that the plugin has created, making house-keeping a little easier (thanks @samme)
  • Math.RotateTo is a new function that will position a point at the given angle and distance (thanks @samme)
  • Display.Bounds.GetBounds is a new function that will return the un-transformed bounds of the given Game Object as a Rectangle (thanks @samme)

Updates

  • The Pointer.dragStartX/YGlobal and Pointer.dragX/Y values are now populated from the worldX/Y, which means using those values directly in Input Drag callbacks will now work when the Camera is zoomed. Fix #4755 (thanks @braindx)
  • The browser field has been added to the Phaser package.json pointing to the dist/phaser.js umd build (thanks @FredKSchott)
  • Calling TimeStep.wake() while the loop is running will now cause nothing to happen, rather than sleeping and then waking again (thanks @samme)
  • Container.getBounds will no longer set the temp rect bounds to the first child of the Container by default (which would error if the child had no bounds, like a Graphics object) and instead sets it as it iterates the children (thanks @blopa)
  • File.state will now be set to the FILE_LOADING state while loading and FILE_LOADED after loading (thanks @samme)
  • BaseCamera.cull now moves some of its calculations outside of the cull loop to speed it up (thanks @samme)
  • SceneManager.createSceneFromInstance had a small refactor to avoid a pointless condition (thanks @samme)

Bug Fixes

  • Fixed a TypeError warning when importing JSON objects directly to the url argument of any of the Loader filetypes. Fix #5189 (thanks @awweather @samme)
  • The NOOP function was incorrectly imported by the Mouse and Keyboard Manager. Fix #5170 (thanks @samme @gregolai)
  • When Audio files failed to decode on loading, they would always show 'undefined' as the key in the error log, now they show the actual key (thanks @samme)
  • When the Sprite Sheet parser results in zero frames, the warning will now tell you the texture name that caused it (thanks @samme)
  • KeyboardPlugin.checkDown didn't set the duration to zero if the parameter was omitted, causing it to always return false. Fix #5146 (thanks @lozzajp)
  • If you passed in an array of children when creating a Group, they were not added and removed correctly. Fix #5151 (thanks @samme)
  • When using HTML5 Audio with pauseOnBlur (the default), if you play a sound, schedule stopping the sound (e.g., timer, tween complete callback), leave the page, and return to the page, the sound stop() will error (thanks @samme)
  • Using a Render Texture when you're also using the headless renderer would cause an error (thanks @samme)
  • Ellipse.setWidth would incorrectly set the xRadius to the diameter (thanks @rexrainbow)
  • Ellipse.setHeight would incorrectly set the yRadius to the diameter (thanks @rexrainbow)
  • When specifically setting the parent property in the Game Config to null the canvas was appended to the document body, when it should have been ignored (allowing you to add it to the dom directly). Fix #5191 (thanks @MerganThePirate)
  • Containers will now apply nested masks correctly when using the Canvas Renderer specifically (thanks @scott20145)
  • Calling Scale.startFullScreen would fail in Safari on Mac OS, throwing a fullscreenfailed error. It now triggers fullscreen mode correctly, as on other browsers. Fix #5143 (thanks @samme @novaknole)
  • Calling setCrop on a Matter Physics Sprite would throw a TypeError, but will now crop correctly. Not that it only crops the texture, the body is unaffected. Fix #5211 (thanks @MatthewRorke @samme)
  • The Static Tilemap Layer would ignore the layer rotation and parent transform when using WebGL (but worked in Canvas). Both modes now work in the same manner (thanks @cruzdanilo)
  • Calling getTextBounds on a BitmapText object would return the incorrect values if the origin had been changed, but the text itself had not, as it was using out of date dimensions. Changing the origin now automatically triggers BitmapText to be dirty, forcing the bounds to be refreshed. Fix #5121 (thanks @thenonamezz)
  • The ISO Triangle shape would skip rendering the left side of the first triangle in the batch. It now renders all ISO Triangles correctly. Fix #5164 (thanks @mattjennings)

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 @SanderVanhove @SirJosh3917 @mooreInteractive @A-312 @lozzajp @mikewesthad @j-waters @futuremarc

Assets 4

@photonstorm photonstorm released this Jul 13, 2020 · 753 commits to master since this release

Arcade Physics New Features, Updates and Fixes

  • When colliding physics groups with the search tree enabled, there was an unnecessary intersection test for each body returned by the search (thanks @samme)
  • When doing an overlap collision, there was an unnecessary intersection test for each pair of overlapping bodies (thanks @samme)
  • Sprite vs. Static Group collision tests now always use the static tree (thanks @samme)
  • Fixed a bug where if you added a static body to a sprite with scale ≠ 1, the body position was incorrect (thanks @samme)
  • If you passed in an array of children when creating a Physics Group, they didn't receive bodies. Fix #5152 (thanks @samme)
  • New types allow for better docs / TypeScript defs especially in the Factory functions: ArcadePhysicsCallback, GameObjectWithBody, GameObjectWithDynamicBody, GameObjectWithStaticBody, ImageWithDynamicBody, ImageWithStaticBody, SpriteWithDynamicBody and SpriteWithStaticBody. Fix #4994 (thanks @samme @gnesher)
  • Body.updateFromGameObject is a new method that extracts the relevant code from preUpdate, allowing you to read the body's new position and center immediately, before the next physics step. It also lets refreshBody work for dynamic bodies, where previously it would error (thanks @samme)
  • Momentum exchange wasn't working correctly vs. immovable bodies. The movable body tended to stop. Fix #4770 (thanks @samme)
  • The Body mass was decreasing the inertia instead of increasing it. Fix #4770 (thanks @samme)
  • The separation vector seemed to be incorrect, causing the slip / slide collisions. The separation is now correct for circle–circle collisions (although not fully for circle–rectangle collisions), part fix #4770 (thanks @samme)
  • The Arcade Body delta was incorrectly calculated on bodies created during the update step, causing the position to be off. Fix #5204 (thanks @zackexplosion @samme)
  • Arcade.Components.Size.setBodySize is a new method available on Arcade Physics Game Objects that allows you to set the body size. This replaces setSize which is now deprecated. Fix #4786 (thanks @wingyplus)

New Features

  • The Animation component has a new property nextAnimsQueue which allows you to sequence Sprite animations to play in order, i.e: this.mole.anims.play('digging').anims.chain('lifting').anims.chain('looking').anims.chain('lowering'); (thanks @tgroborsch)
  • Group.setActive is a new method that will set the active state of a Group, just like it does on other Game Objects (thanks @samme)
  • Group.setName is a new method that will set the name property of a Group, just like it does on other Game Objects (thanks @samme)
  • TWEEN_STOP is a new event dispatched by a Tween when it stops playback (thanks @samme @RollinSafary)
  • You can now specify an onStop callback when creating a Tween as part of the tween config, which is invoked when a Tween stops playback (thanks @samme @RollinSafary)
  • Previously, if you created a timeline and passed no tweens in the config, the timeline would be created but all config properties were ignored. Now the timeline's own properties (completeDelay, loop, loopDelay, useFrames, onStart, onUpdate, onLoop, onYoyo, onComplete, etc.) are set from the config properly (thanks @samme)
  • TextStyle.wordWrapWidth lets you set the maximum width of a line of text (thanks @mikewesthad)
  • TextStyle.wordWrapCallback is a custom function that will is responsible for wrapping the text (thanks @mikewesthad)
  • TextStyle.wordWrapCallbackScope is the scope that will be applied when the wordWrapCallback is invoked (thanks @mikewesthad)
  • TextStyle.wordWrapUseAdvanced controls whether or not to use the advanced wrapping algorithm (thanks @mikewesthad)
  • KeyboardPlugin.removeAllKeys is a new method that allows you to automatically remove all Key instances that the plugin has created, making house-keeping a little easier (thanks @samme)
  • Math.RotateTo is a new function that will position a point at the given angle and distance (thanks @samme)
  • Display.Bounds.GetBounds is a new function that will return the un-transformed bounds of the given Game Object as a Rectangle (thanks @samme)

Updates

  • The Pointer.dragStartX/YGlobal and Pointer.dragX/Y values are now populated from the worldX/Y, which means using those values directly in Input Drag callbacks will now work when the Camera is zoomed. Fix #4755 (thanks @braindx)
  • The browser field has been added to the Phaser package.json pointing to the dist/phaser.js umd build (thanks @FredKSchott)
  • Calling TimeStep.wake() while the loop is running will now cause nothing to happen, rather than sleeping and then waking again (thanks @samme)
  • Container.getBounds will no longer set the temp rect bounds to the first child of the Container by default (which would error if the child had no bounds, like a Graphics object) and instead sets it as it iterates the children (thanks @blopa)
  • File.state will now be set to the FILE_LOADING state while loading and FILE_LOADED after loading (thanks @samme)
  • BaseCamera.cull now moves some of its calculations outside of the cull loop to speed it up (thanks @samme)
  • SceneManager.createSceneFromInstance had a small refactor to avoid a pointless condition (thanks @samme)

Bug Fixes

  • Fixed a TypeError warning when importing JSON objects directly to the url argument of any of the Loader filetypes. Fix #5189 (thanks @awweather @samme)
  • The NOOP function was incorrectly imported by the Mouse and Keyboard Manager. Fix #5170 (thanks @samme @gregolai)
  • When Audio files failed to decode on loading, they would always show 'undefined' as the key in the error log, now they show the actual key (thanks @samme)
  • When the Sprite Sheet parser results in zero frames, the warning will now tell you the texture name that caused it (thanks @samme)
  • KeyboardPlugin.checkDown didn't set the duration to zero if the parameter was omitted, causing it to always return false. Fix #5146 (thanks @lozzajp)
  • If you passed in an array of children when creating a Group, they were not added and removed correctly. Fix #5151 (thanks @samme)
  • When using HTML5 Audio with pauseOnBlur (the default), if you play a sound, schedule stopping the sound (e.g., timer, tween complete callback), leave the page, and return to the page, the sound stop() will error (thanks @samme)
  • Using a Render Texture when you're also using the headless renderer would cause an error (thanks @samme)
  • Ellipse.setWidth would incorrectly set the xRadius to the diameter (thanks @rexrainbow)
  • Ellipse.setHeight would incorrectly set the yRadius to the diameter (thanks @rexrainbow)
  • When specifically setting the parent property in the Game Config to null the canvas was appended to the document body, when it should have been ignored (allowing you to add it to the dom directly). Fix #5191 (thanks @MerganThePirate)
  • Containers will now apply nested masks correctly when using the Canvas Renderer specifically (thanks @scott20145)
  • Calling Scale.startFullScreen would fail in Safari on Mac OS, throwing a fullscreenfailed error. It now triggers fullscreen mode correctly, as on other browsers. Fix #5143 (thanks @samme @novaknole)
  • Calling setCrop on a Matter Physics Sprite would throw a TypeError, but will now crop correctly. Not that it only crops the texture, the body is unaffected. Fix #5211 (thanks @MatthewRorke @samme)
  • The Static Tilemap Layer would ignore the layer rotation and parent transform when using WebGL (but worked in Canvas). Both modes now work in the same manner (thanks @cruzdanilo)
  • Calling getTextBounds on a BitmapText object would return the incorrect values if the origin had been changed, but the text itself had not, as it was using out of date dimensions. Changing the origin now automatically triggers BitmapText to be dirty, forcing the bounds to be refreshed. Fix #5121 (thanks @thenonamezz)
  • The ISO Triangle shape would skip rendering the left side of the first triangle in the batch. It now renders all ISO Triangles correctly. Fix #5164 (thanks @mattjennings)

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 @SanderVanhove @SirJosh3917 @mooreInteractive @A-312 @lozzajp @mikewesthad @j-waters @futuremarc

Assets 4

@photonstorm photonstorm released this Apr 27, 2020 · 892 commits to master since this release

JSDocs

The entire Phaser 3 API now has 100% complete JSDoc coverage!

The following sections had their documentation completed in this release:

  • Animations
  • Create
  • Curves
  • Geom
  • Math
  • Renderer
  • Textures
  • Tilemaps

Removed

The following features have been removed in this version of Phaser:

  • Impact Physics has been removed completely and is no longer a choice of physics system. The resulting Scene.impact property and Impact config object have also been removed.

Deprecated

The following features are now deprecated and will be removed in a future version of Phaser:

  • The Light Pipeline and associated components will be removed. This feature was never properly finished and adds too much redundant, non-optional code into the core API. The ability to load normal maps alongside textures will remain, for use in your own lighting shaders, which gives you far more control over the final effect.

New: Rope Game Object

This version of Phaser contains the brand new Rope Game Object. A Rope is a special kind of Game Object that has a repeating texture that runs in a strip, either horizontally or vertically. Unlike a Sprite, you can define how many vertices the Rope has, and can modify each of them during run-time, allowing for some really lovely effects.

Ropes can be created via the Game Object Factory in the normal way (this.add.rope()) and you should look at the examples and documentation for further implementation details.

Note that Ropes are a WebGL only feature.

New Features

  • Line.GetEasedPoints is a new function that will take a Line, a quantity, and an ease function, and returns an array of points where each point has been spaced out across the length of the Line based on the ease function given.
  • XHRSettings.withCredentials is a new boolean property that controls the withCredentials setting of the XHR Request made by the Loader. It indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. You can set this on a per-file basis, or global in the Game Config.
  • Config.loaderWithCredentials is the new global setting for XHRSettings.withCredentials.
  • Camera.renderToGame is a new property used in conjunction with renderToTexture. It controls if the Camera should still render to the Game canvas after rendering to its own texture or not. By default, it will render to both, but you can now toggle this at run-time.
  • Camera.setRenderToTexture has a new optional parameter renderToGame which sets the Camera.renderToGame property, controlling if the Camera should render to both its texture and the Game canvas, or just its texture.
  • The free version of Texture Packer exports a pivot property when using JSON Array or Hash, however the Texture Packer Phaser export uses the anchor property. This update allows the loaders to work with either property, regardless of which export you use (thanks @veleek)
  • get() is a new method in the HTML and Web Audio Sound Managers that will get the first sound in the manager matching the given key, if any (thanks @samme)
  • getAll() is a new method in the HTML and Web Audio Sound Managers that will get all sounds in the manager matching the given key, if any (thanks @samme)
  • removeAll() is a new method in the HTML and Web Audio Sound Managers that will remove all sounds in the manager, destroying them (thanks @samme)
  • stopByKey() is a new method in the HTML and Web Audio Sound Managers that will stop any sound in the manager matching the given key, if any (thanks @samme)
  • Rectangle.FromXY is a new function that will create the smallest Rectangle containing two coordinate pairs, handy for marquee style selections (thanks @samme)
  • PathFollower.pathDelta is a new property that holds the distance the follower has traveled from the previous point to the current one, at the last update (thanks @samme)
  • Vector2.fuzzyEquals is a new method that will check whether the Vector is approximately equal to a given Vector (thanks @samme)
  • Vector2.setAngle is a new method that will set the angle of the Vector (thanks @samme)
  • Vector2.setLength is a new method that will set the length, or magnitude of the Vector (thanks @samme)
  • Vector2.normalizeLeftHand is a new method that will rotate the Vector to its perpendicular, in the negative direction (thanks @samme)
  • Vector2.limit is a new method that will limit the length, or magnitude of the Vector (thanks @samme)
  • Vector2.reflect is a new method that will reflect the Vector off a line defined by a normal (thanks @samme)
  • Vector2.mirror is a new method that will reflect the Vector across another (thanks @samme)
  • Vector2.rotate is a new method that will rotate the Vector by an angle amount (thanks @samme)
  • Math.Angle.Random is a new function that will return a random angle in radians between -pi and pi (thanks @samme)
  • Math.Angle.RandomDegrees is a new function that will return a random angle in degrees between -180 and 180 (thanks @samme)
  • Physics.Arcade.World.fixedStep is a new boolean property that synchronizes the physics fps to the rendering fps when enabled. This can help in some cases where "glitches" can occur in the movement of objects. These glitches are especially noticeable on objects that move at constant speed and the fps are not consistent. Enabling this feature disables the fps and timeScale properties of the Arcade.World class (thanks @jjcapellan)
  • Curves.Path.getTangent is a new method that gets a unit vector tangent at a relative position on the path (thanks @samme)
  • DataManager.inc is a new method that will increase a value for the given key. If the key doesn't already exist in the Data Manager then it is increased from 0 (thanks @rexrainbow)
  • DataManager.toggle is a new method that will toggle a boolean value for the given key. If the key doesn't already exist in the Data Manager then it is toggled from false (thanks @rexrainbow)
  • The Tiled parser will now recognize Tiled point objects and export them with point: true. Equally, Sprites generated via createFromObjects are now just set to the position of the Point object, using the Sprites dimensions. This is a breaking change, so if you are using Point objects and createFromObjects please re-test your maps against this release of Phaser (thanks @samme)
  • You can now use Blob URLs when loading Audio objects via the Loader (thanks @aucguy)
  • You can now use Blob URLs when loading Video objects via the Loader (thanks @aucguy)
  • Tiled Image Collections now have rudimentary support and will create a single tileset per image. This is useful for prototyping, but should not be used heavily in production. See #4964 (thanks @gogoprog)
  • When loading files using your own XHR Settings you can now use the new property headers to define an object containing multiple headers, all of which will be sent with the xhr request (thanks @jorbascrumps)
  • Camera.rotateTo is a new Camera effect that allows you to set the rotation of the camera to a given value of the duration specified (thanks @jan1za)

Updates

  • XHRLoader will now use the XHRSettings.withCredentials as set in the file or global loader config.
  • Animation.setCurrentFrame will no longer try to call setOrigin or updateDisplayOrigin if the Game Object doesn't have the Origin component, preventing unknown function errors.
  • MatterTileBody now extends EventEmitter, meaning you can listen to collision events from Tiles directly and it will no longer throw errors about gameObject.emit not working. Fix #4967 (thanks @reinildo)
  • Added MatterJS.BodyType to GameObject.body type. Fix #4962 (thanks @meisterpeeps)
  • The JSONHash loader didn't load custom pivot information, but JSONArray did. So that functionality has been duplicated into the JSONHash file type (thanks @veleek)
  • When enabling a Game Object for input debug, the debug body's depth was 0. It's now set to be the same depth as the actual Game Object (thanks @mktcode)
  • Spine Files can now be loaded via a manifest, allowing you to specify a prefix in the loader object and providing absolute paths to textures. Fix #4813 (thanks @FostUK @a610569731)
  • collideSpriteVsGroup now exits early when the Sprite has checkCollision.none, skipping an unnecessary iteration of the group (thanks @samme)
  • collideSpriteVsGroup when looping through the tree results now skips bodies with checkCollision.none (thanks @samme)
  • When enabling a Game Object for Input Debugging the created debug shape will now factor in the position, scale and rotation of the Game Objects parent Container, if it has one (thanks @scott20145)

Bug Fixes

  • The conditional checking if the PathFollower was at the end of the path or not was incorrect (thanks @samme)
  • Creating an Arcade Physics Body from a scaled Game Object would use the un-scaled dimensions for the body. They now use the scaled dimensions. This may be a breaking change in some games, so please be aware of it (thanks @samme)
  • Creating an Arcade Physics Static Body from a scaled Game Object would use the un-scaled dimensions for the body. They now use the scaled dimensions. This may be a breaking change in some games, so please be aware of it (thanks @samme)
  • The Arcade Physics Static Body center was incorrect after construction. Probably caused problems with circle collisions. Fix #4770 (thanks @samme)
  • An Arcade Physics Body center and position are now correct after construction and before preUpdate(), for any Game Object origin or scale (thanks @samme)
  • When calling Body.setSize with the center parameter as true the calculated offset would be incorrect for scaled Game Objects. The offset now takes scaling into consideration (thanks @samme)
  • HTML5AudioFile.load would throw an error in strict mode (thanks @samme)
  • When using the No Audio Sound Manager, calling destroy() would cause a Maximum call stack size exceeded error as it was missing 6 setter methods. It will now destroy properly (thanks @samme)
  • When using HTML5 Audio, setting the game or sound volume outside of the range 0-1 would throw an index size error. The value is now clamped before being set (thanks @samme)
  • Sound Managers were still listening to Game BLUR, FOCUS, and PRE_STEP events after being destroyed. These events are now cleared up properly (thanks @samme)
  • In WebGL, the TextureTintPipeline is now set before rendering any camera effects. If the pipeline had been changed, the effects would not run (thanks @TroKEMp)
  • When transitioning to a sleeping Scene, the transition data wasn't sent to the Scene wake method. It's now sent across to both sleeping and waking scenes. Fix #5078 (thanks @MrMadClown)
  • Scale.lockOrientation('portrait') would throw a runtime error in Firefox: 'TypeError: 'mozLockOrientation' called on an object that does not implement interface Screen.' It no longer does this. Fix #5069 (thanks @123survesh)
  • The FILE_COMPLETE event was being emitted twice for a JSON loaded animation file. It now only fires once. Fix #5059 (thanks @jjcapellan)
  • If you restart or stop / start a scene and then queue at least one new file in preload, the scenes update function is called before create, likely causing an error. Fix #5065 (thanks @samme)
  • Circle.GetPoints will now check that stepRate is > 0 to avoid division by zero errors leading to the quantity becoming infinity (thanks @jdcook)
  • Ellipse.GetPoints will now check that stepRate is > 0 to avoid division by zero errors leading to the quantity becoming infinity (thanks @jdcook)
  • Line.GetPoints will now check that stepRate is > 0 to avoid division by zero errors leading to the quantity becoming infinity (thanks @jdcook)
  • Polygon.GetPoints will now check that stepRate is > 0 to avoid division by zero errors leading to the quantity becoming infinity (thanks @jdcook)
  • Rectangle.GetPoints will now check that stepRate is > 0 to avoid division by zero errors leading to the quantity becoming infinity (thanks @jdcook)
  • Triangle.GetPoints will now check that stepRate is > 0 to avoid division by zero errors leading to the quantity becoming infinity (thanks @jdcook)
  • Changing the game size with a scale mode of FIT resulted in a canvas with a incorrect aspect ratio. Fix #4971 (thanks @Kitsee @samme)
  • The Matter Physics Common.isString function would cause a 'TypeError: Invalid calling object' in Internet Explorer (thanks @samme)
  • Arcade.Body.checkCollision.none did not prevent collisions with Tiles. Now it does (thanks @samme)
  • When running in HEADLESS mode, using a Text Game Object would cause a runtime error "Cannot read property gl of null". Fix #4976 (thanks @raimon-segura @samme)
  • The Tilemap LayerData class properties property has been changed from 'object' to an array of objects, which is what Tiled exports when defining layer properties in the editor. Fix #4983 (thanks @Nightspeller)
  • AudioFile and VideoFile had their state set to undefined instead of FILE_PROCESSING (thanks @samme)
  • Container.getBounds would return incorrect values if it had child Containers within it. Fix #4580 (thanks @Minious @thedrint)
  • The Loader no longer prepends the current path to the URL if it's a Blob object (thanks @aucguy)
  • Spine Atlases can now be loaded correctly via Asset Packs, as they now have the right index applied to them (thanks @jdcook)
  • Input events for children inside nested Containers would incorrectly fire depending on the pointer position (thanks @rexrainbow)
  • Animations with both yoyo and repeatDelay set will respect the delay after each yoyo runs (thanks @cruzdanilo)
  • CanvasTexture.setSize forgot to update the width and height properties of the Texture itself. These now match the underlying canvas element. Fix #5054 (thanks @sebbernery)

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:

@JasonHK @supertommy @majalon @samme @MartinBlackburn @halilcakar @jcyuan @MrMadClown @Dinozor @EmilSV @Jazcash

Assets 4

@photonstorm photonstorm released this Jan 15, 2020 · 1199 commits to master since this release

Matter Physics

All of the following are specific to the Matter Physics implementation used by Phaser:

Matter Physics New Features

  • Matter Physics now has 100% JSDoc coverage! Woohoo :)
  • Matter Physics now has brand new TypeScript defs included in the types folder :)
  • MatterDebugConfig is a new configuration object that contains all of the following new Matter debug settings:
  • showAxes- Render all of the body axes?
  • showAngleIndicator- Render just a single body axis?
  • angleColor- The color of the body angle / axes lines.
  • showBroadphase- Render the broadphase grid?
  • broadphaseColor- The color of the broadphase grid.
  • showBounds- Render the bounds of the bodies in the world?
  • boundsColor- The color of the body bounds.
  • showVelocity- Render the velocity of the bodies in the world?
  • velocityColor- The color of the body velocity line.
  • showCollisions- Render the collision points and normals for colliding pairs.
  • collisionColor- The color of the collision points.
  • showSeparation- Render lines showing the separation between bodies.
  • separationColor- The color of the body separation line.
  • showBody- Render the dynamic bodies in the world to the Graphics object?
  • showStaticBody- Render the static bodies in the world to the Graphics object?
  • showInternalEdges- When rendering bodies, render the internal edges as well?
  • renderFill- Render the bodies using a fill color.
  • renderLine- Render the bodies using a line stroke.
  • fillColor- The color value of the fill when rendering dynamic bodies.
  • fillOpacity- The opacity of the fill when rendering dynamic bodies, a value between 0 and 1.
  • lineColor- The color value of the line stroke when rendering dynamic bodies.
  • lineOpacity- The opacity of the line when rendering dynamic bodies, a value between 0 and 1.
  • lineThickness- If rendering lines, the thickness of the line.
  • staticFillColor- The color value of the fill when rendering static bodies.
  • staticLineColor- The color value of the line stroke when rendering static bodies.
  • showSleeping- Render any sleeping bodies (dynamic or static) in the world to the Graphics object?
  • staticBodySleepOpacity] - The amount to multiply the opacity of sleeping static bodies by.
  • sleepFillColor- The color value of the fill when rendering sleeping dynamic bodies.
  • sleepLineColor- The color value of the line stroke when rendering sleeping dynamic bodies.
  • showSensors- Render bodies or body parts that are flagged as being a sensor?
  • sensorFillColor- The fill color when rendering body sensors.
  • sensorLineColor- The line color when rendering body sensors.
  • showPositions- Render the position of non-static bodies?
  • positionSize- The size of the rectangle drawn when rendering the body position.
  • positionColor- The color value of the rectangle drawn when rendering the body position.
  • showJoint- Render all world constraints to the Graphics object?
  • jointColor- The color value of joints when showJoint is set.
  • jointLineOpacity- The line opacity when rendering joints, a value between 0 and 1.
  • jointLineThickness- The line thickness when rendering joints.
  • pinSize- The size of the circles drawn when rendering pin constraints.
  • pinColor- The color value of the circles drawn when rendering pin constraints.
  • springColor- The color value of spring constraints.
  • anchorColor- The color value of constraint anchors.
  • anchorSize- The size of the circles drawn as the constraint anchors.
  • showConvexHulls- When rendering polygon bodies, render the convex hull as well?
  • hullColor- The color value of hulls when showConvexHulls is set.
  • World.renderBody is a new method that will render a single Matter Body to the given Graphics object. This is used internally during debug rendering but is also public. This allows you to control which bodies are rendered and to which Graphics object, should you wish to use them in-game and not just during debugging.
  • World.renderConstraint is a new method that will render a single Matter Constraint, such as a pin or a spring, to the given Graphics object. This is used internally during debug rendering but is also public. This allows you to control which constraints are rendered and to which Graphics object, should you wish to use them in-game and not just during debugging.
  • World.renderConvexHull is a new method that will render the convex hull of a single Matter Body, to the given Graphics object. This is used internally during debug rendering but is also public. This allows you to control which hulls are rendered and to which Graphics object, should you wish to use them in-game and not just during debugging.
  • World.renderGrid is a new method that will render the broadphase Grid to the given graphics instance.
  • World.renderBodyBounds is a new method that will render the bounds of all the given bodies to the given graphics instance.
  • World.renderBodyAxes is a new method that will render the axes of all the given bodies to the given graphics instance.
  • World.renderBodyVelocity is a new method that will render a velocity line for all the given bodies to the given graphics instance.
  • World.renderSeparations is a new method that will render the separations in the current pairs list to the given graphics instance.
  • World.renderCollisions is a new method that will render the collision points and normals in the current pairs list to the given graphics instance.
  • World.getAllBodies is a new method that will return all bodies in the Matter World.
  • World.getAllConstraints is a new method that will return all constraints in the Matter World.
  • World.getAllComposites is a new method that will return all composites in the Matter World.
  • MatterPhysics.composite is a new reference to the Matter.Composite module for easy access from within a Scene.
  • MatterPhysics.detector is a new reference to the Matter.Dectector module for easy access from within a Scene.
  • MatterPhysics.grid is a new reference to the Matter.Grid module for easy access from within a Scene.
  • MatterPhysics.pair is a new reference to the Matter.Pair module for easy access from within a Scene.
  • MatterPhysics.pairs is a new reference to the Matter.Pairs module for easy access from within a Scene.
  • MatterPhysics.query is a new reference to the Matter.Query module for easy access from within a Scene.
  • MatterPhysics.resolver is a new reference to the Matter.Resolver module for easy access from within a Scene.
  • MatterPhysics.sat is a new reference to the Matter.SAT module for easy access from within a Scene.
  • MatterPhysics.constraint is a new reference to the Matter.Constraint module for easy access from within a Scene.
  • MatterPhysics.composites is a new reference to the Matter.Composites module for easy access from within a Scene.
  • MatterPhysics.axes is a new reference to the Matter.Axes module for easy access from within a Scene.
  • MatterPhysics.bounds is a new reference to the Matter.Bounds module for easy access from within a Scene.
  • MatterPhysics.svg is a new reference to the Matter.Svg module for easy access from within a Scene.
  • MatterPhysics.vector is a new reference to the Matter.Vector module for easy access from within a Scene.
  • MatterPhysics.vertices is a new reference to the Matter.Vertices module for easy access from within a Scene.
  • BEFORE_ADD is a new Event dispatched by Matter.World when a Body or Constraint is about to be added to the World.
  • AFTER_ADD is a new Event dispatched by Matter.World when a Body or Constraint has been added to the World.
  • BEFORE_REMOVE is a new Event dispatched by Matter.World when a Body or Constraint is about to be removed from the World.
  • AFTER_REMOVE is a new Event dispatched by Matter.World when a Body or Constraint has been removed from the World.
  • Body.render.lineOpacity is a new property on the Matter Body object that allows for custom debug rendering.
  • Body.render.lineThickness is a new property on the Matter Body object that allows for custom debug rendering.
  • Body.render.fillOpacity is a new property on the Matter Body object that allows for custom debug rendering.
  • World.setCompositeRenderStyle is a new method that lets you quickly set the render style values on the children of the given compposite.
  • World.setBodyRenderStyle is a new method that lets you quickly set the render style values on the given Body.
  • World.setConstraintRenderStyle is a new method that lets you quickly set the render style values on the given Constraint.
  • You can now set restingThresh in the Matter Configuration file to adjust the Resolver property.
  • You can now set restingThreshTangent in the Matter Configuration file to adjust the Resolver property.
  • You can now set positionDampen in the Matter Configuration file to adjust the Resolver property.
  • You can now set positionWarming in the Matter Configuration file to adjust the Resolver property.
  • You can now set frictionNormalMultiplier in the Matter Configuration file to adjust the Resolver property.
  • MatterPhysics.containsPoint is a new method that returns a boolean if any of the given bodies intersect with the given point.
  • MatterPhysics.intersectPoint is a new method that checks which bodies intersect with the given point and returns them.
  • MatterPhysics.intersectRect is a new method that checks which bodies intersect with the given rectangular area, and returns them. Optionally, it can check which bodies are outside of the area.
  • MatterPhysics.intersectRay is a new method that checks which bodies intersect with the given ray segment and returns them. Optionally, you can set the width of the ray.
  • MatterPhysics.intersectBody is a new method that checks which bodies intersect with the given body and returns them. If the bodies are set to not collide this can be used as an overlaps check.
  • MatterPhysics.overlap is a new method that takes a target body and checks to see if it overlaps with any of the bodies given. If they do, optional process and overlap callbacks are invoked, passing the overlapping bodies to them, along with additional collision data.
  • MatterPhysics.setCollisionCategory is a new method that will set the collision filter category to the value given, on all of the bodies given. This allows you to easily set the category on bodies that don't have a Phaser Matter Collision component.
  • MatterPhysics.setCollisionGroup is a new method that will set the collision filter group to the value given, on all of the bodies given. This allows you to easily set the group on bodies that don't have a Phaser Matter Collision component.
  • MatterPhysics.setCollidesWith is a new method that will set the collision filter mask to the value given, on all of the bodies given. This allows you to easily set the filter mask on bodies that don't have a Phaser Matter Collision component.
  • Matter.Body.centerOfMass is a new vec2 property added to the Matter Body object that retains the center of mass coordinates when the Body is first created, or has parts added to it. These are float values, derived from the body position and bounds.
  • Matter.Body.centerOffset is a new vec2 property added to the Matter Body object that retains the center offset coordinates when the Body is first created, or has parts added to it. These are pixel values.
  • Constraint.pointAWorld is a new method added to Matter that returns the world-space position of constraint.pointA, accounting for constraint.bodyA.
  • Constraint.pointBWorld is a new method added to Matter that returns the world-space position of constraint.pointB, accounting for constraint.bodyB.
  • Body.setCentre is a new method added to Matter that allows you to set the center of mass of a Body (please note the English spelling of this function.)
  • Body.scale is a new read-only vector that holds the most recent scale values as passed to Body.scale.
  • Matter.Bodies.flagCoincidentParts is a new function that will flags all internal edges (coincident parts) on an array of body parts. This was previously part of the fromVertices function, but has been made external for outside use.
  • Matter.getMatterBodies is a new function that will return an array of Matter JS Bodies from the given input array, which can be Matter Game Objects, or any class that extends them.
  • Matter.World.has is a new method that will take a Matter Body, or Game Object, and search the world for it. If found, it will return true.
  • Matter now has the option to use the Runner that it ships with. The Matter Runner operates in two modes: fixed and variable. In the fixed mode, the Matter Engine updates at a fixed delta value every frame (which is what Phaser has used since the first version). In variable mode, the delta will be smoothed and capped each frame to keep the simulation constant, but at the cost of determininism. You can configure the runner by setting the runner property in the Matter Config object, both of which are fully covered with JSDocs. As of 3.22 the runner is now used by default in variable (non-fixed) mode. If you wish to return to the previous behavior, set runner: { isFixed: true }.
  • Body.onCollideCallback is a new Matter Body property that can point to a callback to invoke when the body starts colliding.
  • Body.onCollideEndCallback is a new Matter Body property that can point to a callback to invoke when the body stops colliding.
  • Body.onCollideActiveCallback is a new Matter Body property that can point to a callback to invoke for the duration the body is colliding.
  • Body.onCollideWith is a new Matter Body property that holds a mapping between bodies and collision callbacks.
  • MatterGameObject.setOnCollide is a new method available on any Matter Game Object, that sets a callback that is invoked when the body collides with another.
  • MatterGameObject.setOnCollideEnd is a new method available on any Matter Game Object, that sets a callback that is invoked when the body stops colliding.
  • MatterGameObject.setOnCollideActive is a new method available on any Matter Game Object, that sets a callback which is invoked for the duration of the bodies collision with another.
  • MatterGameObject.setOnCollideWith is a new method available on any Matter Game Object, that allows you to set a callback to be invoked whenever the body collides with another specific body, or array of bodies.
  • Body.gravityScale is a new vector property that allows you to scale the effect of world gravity on a specific Body.
  • MatterPhysics._tempVec2 is a new private internal vector used for velocity and force calculations.
  • MatterPhysics.setVelocity is a new method that will set both the horizontal and vertical linear velocity of the given physics bodies. This can be used on all Matter bodies, not just those created via the factory.
  • MatterPhysics.setVelocityX is a new method that will set the horizontal linear velocity of the given physics bodies. This can be used on all Matter bodies, not just those created via the factory.
  • MatterPhysics.setVelocityY is a new method that will set the vertical linear velocity of the given physics bodies. This can be used on all Matter bodies, not just those created via the factory.
  • MatterPhysics.setAngularVelocity is a new method that will set the angular velocity of the given physics bodies. This can be used on all Matter bodies, not just those created via the factory.
  • MatterPhysics.applyForce is a new method that applies a force to a body, at the bodies current position, including resulting torque. This can be used on all Matter bodies, not just those created via the factory.
  • MatterPhysics.applyForceFromPosition is a new method that applies a force to a body from the given world position, including resulting torque. If no angle is given, the current body angle is used. This can be used on all Matter bodies, not just those created via the factory.
  • MatterPhysics.fromSVG is a new method that allows you to create a Body from the given SVG path data.
  • The Matter.Factory.velocity method has been removed. Please now use MatterPhysics.setVelocity instead.
  • The Matter.Factory.angularVelocity method has been removed. Please now use MatterPhysics.setAngularVelocity instead.
  • The Matter.Factory.force method has been removed. Please now use MatterPhysics.applyForce instead.
  • MatterBodyConfig is a new type def that contains all of the Body configuration properties. This is now used through-out the JSDocs to aid in code-completion.
  • MatterBodyRenderConfig is a new type def that contains all of the Body debug rendering configuration properties. This is now used through-out the JSDocs to aid in code-completion.
  • MatterChamferConfig is a new type def that contains all of the chamfer configuration properties. This is now used through-out the JSDocs to aid in code-completion.
  • MatterCollisionFilter is a new type def that contains all of the collision configuration properties. This is now used through-out the JSDocs to aid in code-completion.
  • MatterConstraintConfig is a new type def that contains all of the constraint configuration properties. This is now used through-out the JSDocs to aid in code-completion.
  • MatterConstraintRenderConfig is a new type def that contains all of the Constraint debug rendering configuration properties. This is now used through-out the JSDocs to aid in code-completion.
  • MatterSetBodyConfig is a new type def that contains all of the Constraint debug rendering configuration properties. This is now used through-out the JSDocs to aid in code-completion.
  • MatterPhysics.getConstraintLength is a new method that will return the length of the given constraint, as this is something you cannot get from the constraint properties directly.
  • MatterPhysics.alignBody is a new method that will align a Body, or Matter Game Object, against the given coordinates, using the given alignment constant. For example, this allows you to easily position a body to the BOTTOM_LEFT, or TOP_CENTER, or a coordinate. Alignment is based on the body bounds.
  • Phaser.Types.Physics.Matter.MatterBody is a new type def that contains all of the valid Matter Body objects. This is now used through-out the JSDocs to aid in code-completion.
  • Matter.BodyBounds is a new class that contains methods to help you extract world coordinates from various points around the bounds of a Matter Body. Because Matter bodies are positioned based on their center of mass, and not a dimension based center, you often need to get the bounds coordinates in order to properly align them in the world. You can access this new class via this.matter.bodyBounds.
  • The method signature for Matter.PhysicsEditorParser.parseBody has changed. It now takes (x, y, config, options) and no longer has width and height parameters. Please see the updated documentation for more details if you were calling this method directly.
  • MatterPhysics.fromPhysicsEditor is a new method that allows you to create a Matter Body based on the given PhysicsEditor shape data. Previously, you could only using PhysicsEditor data with a Matter Game Object, but now you can create a body directly using it.
  • Matter.PhysicsJSONParser is a new parser that will create Matter bodies from JSON physics data files. Currently onto the Phaser Physics Tracer app exports in this format, but details are published in the JSDocs, so any app can do so.
  • Matter.Factory.fromJSON is a new method that will create a body from a JSON physics data file.
  • The SetBody Matter component can now automatically use shapes created in the Phaser Physics Tracer App in the JSON data format.
  • Matter.Components.Sleep.setToSleep is a new method available on any Matter Game Object that will send the body to sleep, if Engine sleeping has been enabled.
  • Matter.Components.Sleep.setAwake is a new method available on any Matter Game Object that will awake a body from sleep, if Engine sleeping has been enabled.

Matter Physics Updates

  • The debug property in the Matter World Config is now a MatterDebugConfig option instead of a boolean. However, if a boolean is given, it will use the default debug config values.
  • The following MatterWorldConfig options have now been removed: debugShowBody, debugShowStaticBody, debugBodyColor, debugBodyFillColor, debugStaticBodyColor, debugShowJoint, debugJointColor, debugWireframes, debugShowInternalEdges, debugShowConvexHulls, debugConvexHullColor and debugShowSleeping. These can all be set via the new MatterDebugConfig object instead.
  • The object World.defaults has been removed. Defaults are now access via World.debugDefaults.
  • World.renderBodies has been rewritten to cache commonly-used values and avoid a situation when a single body would be rendered twice.
  • The private method World.renderConvexHulls has been removed as it's no longer used internally.
  • The private method World.renderWireframes has been removed as it's no longer used internally.
  • The method World.fromPath has been removed. This was never used internally and you can get the same results by calling Vertices.fromPath.
  • The World.setBounds argument thickness now defaults to 64, not 128, to keep it matching the Matter World Config.
  • The Body.render.fillStyle property that existed on the Matter Body object has been removed and replaced with fillColor.
  • The Body.render.strokeStyle property that existed on the Matter Body object has been removed and replaced with lineColor.
  • Matter.Body.render.sprite.xOffset and yOffset are no longer set to anything when a Body is created. They are left as zero, or you can override them in the Body config, in which case the value is added to the sprite origin offset during a call to setExistingBody.
  • The Matter.Mass.centerOfMass component property now returns the pre-calculated Body centerOfMass property, which is much more accurate than the previous bounds offset value.
  • Matter.setExistingBody, which is called interally whenever a Body is set on a Game Object, now uses the new centerOffset values to ensure that the texture frame is correctly centered based on the center of mass, not the Body bounds, allowing for much more accurate body to texture mapping with complex multi-part compound bodies.
  • The Matter.PhysicsEditorParser has been updated so it no longer needs to set the render offsets, and instead uses the center of mass values.
  • If the Matter.Body config doesn't contain a position property, it will now default to using Vertices.centre(body.vertices) as the position. In most cases, this is what you need, so it saves having to pass it in the config object.
  • Bumped Matter Plugin versions to avoid console logs from Common.info and Common.warn.
  • PhysicsEditorParser.parseVertices now uses Bodies.flagCoincidentParts to avoid duplicating code.
  • MatterGameObject has a new optional boolean constructor parameter addToWorld which lets you control if the Body should be added to the world or not. Useful for toggling off should you be merging pre-existing bodies with Game Objects.
  • The Matter.SetBody.setExistingBody function, which all Matter Game Objects have, has a new parameter addToWorld which allows you to control when the body is added to the Matter world should you not require it immediately. It will also only add the body to the world if it doesn't already exist within it, or any of its composites.
  • PointerConstraint has been recoded so that when pressed down, it only polls the World for a body hit test during the next game update. This stops it coming out of sync with the state of the world. Use of the constraint remains the same as before.
  • You can now set gravity: false in your Matter Config and it will reset gravity from the defaults to zero.
  • The internal Matter Composite.setModified function will now emit a compositeModified event, which the Matter World listens for, if debug draw is enabled, so it can update the composite children render styles.
  • Matter.PhysicsEditorParser.parseBody can now accept a MatterBodyConfig file as a 4th parameter. This allows you to set Body properties when the body is created, overriding whatever values may have been set in the PhysicsEditor JSON.

Matter Physics Bug Fixes

  • Due to the rewrite of the debug rendering, it is now possible to render just constraints, where-as before this was only possible if bodies were being rendered as well. Fix #4880 (thanks @roberto257)
  • Matter.PhysicsEditorParser had a bug where it would allow fixtures with non-clockwise sorted vertices through, which would break pointer constraint interaction with these bodies. The parser now sorts the vertices properly. Fix #4261 (thanks @Sanchez3)

New Features

  • TimeStep.smoothStep is a new boolean property that controls if any delta smoothing takes place during the game step. Delta smoothing has been enabled in Phaser since the first version and helps avoid delta spikes and dips, especially after loss of focus. However, you can now easily toggle if this happens via this property and the corresponding FPSConfig property.
  • Phaser.Math.Distance.BetweenPoints is a new function that will return the distance between two Vector2-like objects (thanks @samme)
  • Phaser.Math.Distance.BetweenPointsSquared is a new function that will return the squared distance between two Vector2-like objects (thanks @samme)
  • Phaser.Math.Distance.Chebyshev is a new function that will return the Chebyshev (or chessboard) distance between two Vector2-like objects (thanks @samme)
  • Phaser.Math.Distance.Snake is a new function that will return the rectilinear distance between two Vector2-like objects (thanks @samme)
  • ParticleEmitter.setTint is a new method that will set the tint of emitted particles for the given Emitter only (thanks @samme)
  • ParticleEmitter.remove is a new method that will remove the Emitter from its Emitter Manager (thanks @samme)
  • ParticleEmitterManager.removeEmitter is a new method that will remove the given emitter from the manager, if the emitter belongs to it (thanks @samme)
  • AlphaSingle is a new Game Object Component that allows a Game Object to set its alpha values, but only as a single uniform value, not on a per-quad basis.
  • Actions.AlignTo (in combination with the new Display.Align.To.QuickSet function) allows you to align an array of Game Objects so they sit next to each other, one at a time. The first item isn't moved, the second is moved to sit next to the first, and so on. You can align them using any of the alignment constants (thanks @samme)
  • Scene.Systems.getData is a new method that will return any data that was sent to the Scene by another Scene, i.e. during a run or launch command. You can access it via this.sys.getData() from within your Scene.
  • Group.internalCreateCallback is a new optional callback that is invoked whenever a child is added to a Group. This is the same as createCallback except it's only for use by the parent class, allowing a parent to invoke a creation callback and for you to still provide one via the Group config.
  • Group.internalRemoveCallback is a new optional callback that is invoked whenever a child is removed from a Group. This is the same as removeCallback except it's only for use by the parent class, allowing a parent to invoke a callback and for you to still provide one via the Group config.

Updates

  • Body.deltaXFinal is a new method on Arcade Physics Bodies that will return the final change in the horizontal position of the body, as based on all the steps that took place this frame. This property is calculated during the postUpdate phase, so must be listened for accordingly (thanks Bambosh)
  • Body.deltaYFinal is a new method on Arcade Physics Bodies that will return the final change in the vertical position of the body, as based on all the steps that took place this frame. This property is calculated during the postUpdate phase, so must be listened for accordingly (thanks Bambosh)
  • Body._tx is a new internal private var, holding the Arcade Physics Body combined total delta x value.
  • Body._ty is a new internal private var, holding the Arcade Physics Body combined total delta y value.
  • LineCurve.getUtoTmapping has been updated to return u directly to avoid calculations as it's identical to t in a Line (thanks @rexrainbow)
  • Curve.getSpacedPoints will now take an optional array as the 3rd parameter to store the points results in (thanks @rexrainbow)
  • Trying to play or resume an audio file with an incorrect key will now throw a runtime error, instead of a console warning (thanks @samme)
  • The Shape Game Object now uses the AlphaSingle component, allowing you to uniformly set the alpha of the shape, rather than a quad alpha, which never worked for Shape objects.
  • The Container Game Object now uses the AlphaSingle component, allowing you to uniformly set the alpha of the container, rather than a quad alpha, which never worked consistently across Container children. Fix #4916 (thanks @laineus)
  • The DOMElement Game Object now uses the AlphaSingle component, allowing you to uniformly set the alpha of the element, rather than a quad alpha, which never worked for these objects.
  • The Graphics Game Object now uses the AlphaSingle component, allowing you to uniformly set the alpha of the element, rather than a quad alpha, which never worked for these objects.
  • TweenData has a new property called previous which holds the eased property value prior to the update.
  • The TWEEN_UPDATE event now sends two new parameters to the handler: current and previous which contain the current and previous property values.
  • During collideSpriteVsGroup checks it will now skip bodies that are disabled to save doing a contains test (thanks @samme)
  • Display.Align.In.QuickSet now accepts LEFT_BOTTOM as BOTTOM_LEFT, LEFT_TOP as TOP_LEFT, RIGHT_BOTTOM as BOTTOM_RIGHT and RIGHT_TOP as TOP_RIGHT. Fix #4927 (thanks @zaniar)
  • PhysicsGroup now uses the new internalCreateCallback and internalRemoveCallback to handle its body creation and destruction, allowing you to use your own createCallback and removeCallback as defined in the Group config. Fix #4420 #4657 #4822 (thanks @S4n60w3n @kendistiller @scrubperson)
  • DOMElement has a new private method handleSceneEvent which will handle toggling the display setting of the element when a Scene sleeps and wakes. A DOM Element will now listen for the Scene sleep and wake events. These event listeners are removed in the preDestroy method.
  • A DOMElement will now set the display mode to 'none' during its render if the Scene in which it belongs is no longer visible.

Bug Fixes

  • BitmapText with a maxWidth set wouldn't update the text correctly if it was modified post-creation. You can now update the text and/or width independantly and it'll update correctly. Fix #4881 (thanks @oxguy3)
  • Text objects will no longer add any white-space when word-wrapping if the last line is only one word long. Fix #4867 (thanks @gaamoo @rexrainbow)
  • When Game.destroy is running, Scenes are now destroyed before plugins, avoiding bugs when closing down plugins and deleting Render Textures. Fix #4849 #4876 (thanks @rexrainbow @siyuanqiao)
  • The Mesh and Quad Game Objects have had the GetBounds component removed as it cannot operate on a Mesh as they don't have origins. Fix #4902 (thanks @samme)
  • Setting lineSpacing in the Text Game Object style config would set the value but not apply it to the Text, leaving you to call updateText yourself. If set, it's now applied on instantiation. Fix #4901 (thanks @FantaZZ)
  • External calls to the Fullscreen API using element.requestFullscreen() would be blocked by the Scale Manager. The Scale Manager will no longer call stopFullScreen should it be triggered outside of Phaser (thanks @AdamXA)
  • The Tilemaps.Tile.tint property wasn't working correctly as it expected the colors in the wrong order (BGR instead of RGB). It will now expect them in the correct RGB order (thanks @Aedalus @plissken2013es)
  • The ScaleManager.destroy method wasn't being called when the Game DESTROY event was dispatched, causing minor gc to build up. The destroy method will now be called properly on game destruction. Fix #4944 (thanks @sunshineuoow)
  • FacebookInstantGamesPlugin.showAd and showVideo will now break out of the ad iteration search once a valid ad has been found and called. Previously, it would carry on interating if the async didn't complete quickly. Fix #4888 (thanks @east62687)
  • When playing an Animation, if you were to play another, then pause it, then play another the internal _paused wouldn't get reset, preventing you from them pausing the animations from that point on. You can now play and pause animations at will. Fix #4835 (thanks @murteira)
  • In Actions.GridAlign if you set width to -1 it would align the items vertically, instead of horizontally. It now aligns them horizontally if width is set, or vertically if height is set. Fix #4899 (thanks @BenjaVR)
  • A PathFollower with a very short duration would often not end in the correct place, which is the very end of the Path, due to the tween handling the movement not running one final update when the tween was complete. It will now always end at the final point of the path, no matter how short the duration. Fix #4950 (thanks @bramp)
  • A DOMElement would still remain visible even if the Scene in which it belongs to was sent to sleep. A sleeping Scene shouldn't render anything. DOM Elements will now respond to sleep and wake events from their parent Scene. Fix #4870 (thanks @peonmodel)
  • If a config object was passed to MultiAtlasFile it expected the atlas URL to be in the url property, however the docs and file config expected it in atlasURL. You can now use either of these properties to declare the url. Fix #4815 (thanks @xense)

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:

@fselcukcan Bambosh @louisth @hexus @javigaralva @samme @BeLi4L @jcyuan @javigaralva @T-Grave @bramp @Chnapy @dranitski @RollinSafary @xense

The Matter TypeScript defs have been updated to include lots of missing classes, removed some redundant elements and general fixes. The Phaser TypeScript defs now reference the Matter defs directly and no longer try to parse them from the JSDocs. This allows the MatterJS namespace to work in TypeScript projects without any compilation warnings.

The Spine Plugin now has new TypeScript defs in the types folder thanks to @supertommy

Assets 6

@photonstorm photonstorm released this Nov 22, 2019 · 1540 commits to master since this release

New Features

  • You can now specify the mipmap filter level to be used when creating WebGL textures. This can be set in the Game Config using the new mipmapFilter property, which is a string, such as 'NEAREST_MIPMAP_NEAREST'. Or, you can set the new WebGLRenderer.mipmapFilter property to a valid GLenum. If you set it on the renderer, it will only impact any textures loaded after it has been set, so do so in your Scene init method if you want it to be used for textures you're about to load. By changing the mipmap level you can drastically improve the quality when reducing large textures. Please note, due to WebGL1 limitations, this only works on power-of-two sized textures. It also works on textures created from Canvas, Videos or RenderTextures.
  • BitmapText.setMaxWidth is a new method that allows you to set a maximum width (in pixels) for the BitmapText to take up when rendering. Lines of text longer than maxWidth will be wrapped, based on whitespace, to the next line. This allows you to do word-wrapping on BitmapText objects, something only previously possible on Text objects.
  • BitmapText.wordWrapCharCode is a new property that works with setMaxWidth that allows you to control which character code causes a line-wrap. By default it is 32 (a space character).
  • ArcadePhysics.closest now has an optional targets argument. The targets can be any Arcade Physics Game Object, Body or Static Body and it will return only the closet target from those given (thanks @samme)
  • ArcadePhysics.furthest now has an optional targets argument. The targets can be any Arcade Physics Game Object, Body or Static Body and it will return only the furthest target from those given (thanks @samme)
  • Tilemaps.Parsers.Tiled.CreateGroupLayer is a new function that parses a Tiled group layer and adds in support for Tiled layer groups (introduced in Tiled 1.2.0). Feature #4099 (thanks @Babeetlebum @Olliebrown)
  • The Tilemap system now supports infinite Tilemaps from the Tiled map editor (thanks @Olliebrown)
  • Tilemap.getImageLayerNames is a new method that returns a list of all valid imagelayer names loaded in the Tilemap (thanks @Olliebrown)
  • Tilemap.getObjectLayerNames is a new method that returns a list of all valid objectgroup names loaded in the Tilemap (thanks @Olliebrown)
  • Tilemap.getTileLayerNames is a new method that returns a list of all valid tilelayer names loaded in the Tilemap (thanks @Olliebrown)
  • When forceSetTimeOut is set to true in the Game Config, you can now set the target frame rate by setting the fps.target value (thanks @pavels)
  • Videos can now be loaded from a data URI, allowing for base64 encoded videos to be used in the Loader instead of file based ones. Although, as with all base64 encoded data, we strongly recommend against this (thanks @apasov)
  • Math.MIN_SAFE_INTEGER is a new math const that stores the minimum safe integer for browsers that don't provide this, such as IE (thanks @jronn)
  • Math.MAX_SAFE_INTEGER is a new math const that stores the maximum safe integer for browsers that don't provide this, such as IE (thanks @jronn)
  • KeyCodes.NUMPAD_ADD has been added to the keycodes list (thanks @Martin-Antonov)
  • KeyCodes.NUMPAD_SUBTRACT has been added to the keycodes list (thanks @Martin-Antonov)
  • Video.removeVideoElementOnDestroy is a new boolean property that allows you to control if the Video element is removed from the DOM when the Video Game Object is destroyed.
  • Actions.SetScrollFactor is a new Action that will set the scroll factor on an array of Game Objects, including stepped incremental changes per item (thanks @rexrainbow)
  • Actions.SetScrollFactorX is a new Action that will set the horizontal scroll factor on an array of Game Objects, including stepped incremental changes per item (thanks @rexrainbow)
  • Actions.SetScrollFactorY is a new Action that will set the horizontal scroll factor on an array of Game Objects, including stepped incremental changes per item (thanks @rexrainbow)
  • The Group config object now supports use of the setScrollFactor property to set the value on each child of the Group (thanks @rexrainbow)
  • Group.propertyValueSet is a new method that sets a given property on each Group member (thanks @rexrainbow)
  • Group.propertyValueInc is a new method that adds an amount to a given property on each Group member (thanks @rexrainbow)
  • Group.setX is a new method that sets the x coordinate on each Group member (thanks @rexrainbow)
  • Group.setY is a new method that sets the y coordinate on each Group member (thanks @rexrainbow)
  • Group.setXY is a new method that sets the x and y coordinate on each Group member (thanks @rexrainbow)
  • Group.incX is a new method that increments the x coordinate on each Group member (thanks @rexrainbow)
  • Group.incY is a new method that increments the y coordinate on each Group member (thanks @rexrainbow)
  • Group.incXY is a new method that increments the x and y coordinate on each Group member (thanks @rexrainbow)
  • Group.shiftPosition is a new method that iterates the Group members and shifts the position of each to the previous members position (thanks @rexrainbow)
  • Group.angle is a new method that sets the angle property on each Group member (thanks @rexrainbow)
  • Group.rotate is a new method that sets the rotation property on each Group member (thanks @rexrainbow)
  • Group.rotateAround is a new method that rotates each Group member around the given point, by the given angle (thanks @rexrainbow)
  • Group.rotateAroundDistance is a new method that rotates each Group member around the given point, by the given angle and distance (thanks @rexrainbow)
  • Group.setAlpha is a new method that sets the alpha property on each Group member (thanks @rexrainbow)
  • Group.setTint is a new method that sets the tint property on each Group member (thanks @rexrainbow)
  • Group.setOrigin is a new method that sets the origin property on each Group member (thanks @rexrainbow)
  • Group.scaleX is a new method that sets the x scale on each Group member (thanks @rexrainbow)
  • Group.scaleY is a new method that sets the y scale on each Group member (thanks @rexrainbow)
  • Group.scaleXY is a new method that sets the x and y scale on each Group member (thanks @rexrainbow)
  • Group.setBlendMode is a new method that sets the blend mode on each Group member (thanks @rexrainbow)
  • Group.setHitArea is a new method that passes all Group members to the Input Plugin to enable them for input (thanks @rexrainbow)
  • Group.shuffle is a new method that shuffles all of the Group members in place (thanks @rexrainbow)
  • Group.setVisible is a new method that sets the visible state on each Group member (thanks @rexrainbow)
  • WebAudioSoundManager.setAudioContext is a new method that allows you to set the Sound Manager Audio Context to a different context instance. It will also disconnect and re-create the gain nodes on the new context.
  • Group.type is a new property that holds a string-based name of the Game Object type, as with other GO's (thanks @samme)
  • Arade.Group.type is a new property that holds a string-based name of the Game Object type, as with other GO's (thanks @samme)
  • Arcade.StaticGroup.type is a new property that holds a string-based name of the Game Object type, as with other GO's (thanks @samme)
  • ArcadePhysics.overlapCirc is a new method that allows you to return an array of all Arcade Physics bodies that overlap with the given circular area of the world. It can return either dynamic or static bodies, or a mixture of both (thanks @samme)

Updates

  • Curve.getPoints can now take an optional array as the 3rd parameter in which to store the points results (thanks @rexrainbow)
  • Line.arcLengthDivisions now overrides the default Curve value and is set to 1 to optimize the amount of points returned for a Line curve (thanks @rexrainbow)
  • ArcadePhysics.closest will now no longer ever return the source in the target results (thanks @samme)
  • ArcadePhysics.furthest will now no longer ever return the source in the target results (thanks @samme)
  • RequestAnimationFrame.target is a new property that controls the fps rate (in ms) when setTimeout is used (thanks @pavels)
  • The WebAudioSoundManager.unlock method will now listen for keydown events in order to unlock the Audio Context, as well as touch and pointer events, making it more accessible (thanks Nick Tipping)
  • The requestAnimationFrame polyfill no longer expects a Browserify environment and uses window through-out, it also no longer adds in the same as performance.now does.
  • BitmapText.getTextBounds didn't reset the dirty flag, causing the GetBitmapTextSize function to be called every time the Bitmap Text was rendered. With enough text objects on-screen this could negatively impact performance. The flag is now reset every time the bounds are recalculated.

Bug Fixes

  • The Spine Plugin was not clearing down the resize event listener in WebGL, causing it to still fire even if the Scene was closed. Fix #4808 (thanks @RollinSafary)
  • When a game is created with the HEADLESS renderer, Game.destroy() had no effect and the game kept on running. Now it destroys itself properly. Fix #4804 (thanks @samme)
  • DOM.GetScreenOrientation was returning the wrong consts from the Scale Manager (thanks @jcyuan)
  • When using Input.enableDebug on Game Objects it would not render the debug graphic correctly if the hit area had been offset. It now adjusts the debug correctly for all common hit-area geometry types. Fix #4722 (thanks @HaoboZ @Olliebrown)
  • Light2D was not properly working for DynamicTilemapLayers due to a change in the way tilesets were stored, throwing an Uncaught TypeError at runtime. This is now handled correctly. Fix #4167 #4079 (thanks @koljakutschera @blackjack26 @kainage)
  • Input.dragDistanceThreshold was not working correctly since 3.18, snapping to the wrong drag state unless the time threshold was also set. Fix #4667 (thanks @muliawanw @Olliebrown)
  • Tilemap.convertLayerToStatic would throw an error when used multiple times, due to an error with the layer index count. Fix #4737 (thanks @Olliebrown @Vegita2)
  • The Tween class now uses a cached MAX_SAFE_INTEGER making it compatible with Internet Explorer (thanks @jronn)
  • The StaggerBuilder class now uses a cached MAX_SAFE_INTEGER making it compatible with Internet Explorer (thanks @jronn)
  • The Rectangle.FromPoints function now uses a cached MIN_SAFE_INTEGER making it compatible with Internet Explorer (thanks @jronn)
  • The Video class now uses a cached MIN_SAFE_INTEGER making it compatible with Internet Explorer (thanks @jronn)
  • The Path class now uses a cached MIN_SAFE_INTEGER making it compatible with Internet Explorer (thanks @jronn)
  • Video.destroy has been renamed to Video.preDestroy, so that it now destroys properly like all other Game Objects. Fix #4821 (thanks @rexrainbow)
  • The Video Game Object will now check to see if the browser supports the HTMLVideoElement before creating one (thanks @jcyuan)
  • The DOM.GetScreenOrientation functions would return out-dated consts (thanks @jcyuan)
  • When calling TileSprite.setTexture or setFrame, if the new frame size didn't match the old one, the new fill pattern would become distorted and the potWidth and potHeight values would be incorrect.
  • Timeline callbacks with extra parameters like onStart would miss the first parameter when the callback was invoked. Fix #4810 (thanks @samme)

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 (for contributing loads of new Arcade Physics examples) @dranitski @jcyuan @RollinSafary @ilyaryabchinski @jsoref @jcyuan @ghclark2

Assets 4

@photonstorm photonstorm released this Oct 15, 2019 · 1672 commits to master since this release

Updates

  • The remove-files-webpack-plugin plugin has been moved to a devDependency (thanks @noseglid)

Bug Fixes

  • UpdateList.shutdown wasn't removing the Scene Update event listener, causing actions to be multiplied on Scene restart (such as animation playback). Fix #4799 (thanks @jronn)
  • Container.mask wouldn't render in WebGL due to a change in the way child masks were handled. Container masking now works again as in 3.19. Fix #4803 (thanks @paulsymphony)
  • DynamicTilemapLayer.setCollision would cause an indexOf error when trying to access the layer data. Fix #4800 (thanks @PavelMishin)
  • SceneManager.run (and consequently ScenePlugin.run) was using an out-dated way of checking if a Scene was paused before trying to resume it, causing a Scene to be started again instead of resumed. It now uses the Systems.isPaused function instead. Fix #3931 (thanks @alexeymolchan)

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:

@xSke

Assets 4
You can’t perform that action at this time.