All Versions
58
Latest Version
Avg Release Cycle
31 days
Latest Release
366 days ago

Changelog History
Page 4

  • v3.16.2 Changes

    February 11, 2019

    ๐Ÿš€ This is point release primarily fixes a few important issues that surfaced in 3.16.0. Please be sure to read the Change Log if you are coming from a version < 3.16.0 as it contains lots of important updates.

    Matter Pointer Constraint Changes

    The following changes all effect the Matter JS Pointer Constraint class:

    • Pointer handling has been changed to make more sense. In the previous version, pressing down and then moving the Pointer over a body would start it being dragged, even if the pointer was pressed down well outside of the body bounds. Now, a body can only be dragged by actually pressing down on it, or any of its parts, which is more in-line with how input events should work.
    • ๐Ÿš€ Previously, releasing ANY pointer would stop an object being dragged, even if it wasn't the one actually dragging a body, as in a multi-touch game. Bodies are now bound to the pointer which started their drag and only the release of that pointer will stop them.
    • There is a new Matter Physics Event DRAG_START which is emitted by a Pointer Constraint when it starts dragging a body. Listen for this event from the Matter World instance.
    • There is a new Matter Physics Event DRAG which is emitted by a Pointer Constraint as it drags a body. Listen for this event from the Matter World instance.
    • There is a new Matter Physics Event DRAG_END which is emitted by a Pointer Constraint when it stops dragging a body. Listen for this event from the Matter World instance.
    • The camera property can no longer be set in the config object. Instead it is set every time the Pointer is pressed down on a Body, this resolves issues where you have a multi-camera Scene and want to drag a body in the non-main camera.
    • body is a new property that holds a reference to the Body being dragged, if any.
    • part is a new property that holds a reference to the Body part that was clicked on which started the drag.
    • โœ… The internal getBodyPart method has been renamed to hitTestBody to more accurately reflect what it does.
    • ๐Ÿš€ The class no longer listens for the pointer up event, instead of tracks the active pointer and waits for that to be released. This has reduced the complexity and size of the update method considerably.
    • ๐Ÿš€ stopDrag is a new method that allows you to manually stop an object being dragged, even if the pointer isn't released.
    • This class now has 100% JSDocs.

    โšก๏ธ Updates

    • โšก๏ธ TileSprite.setTileScale has been updated so that the y argument is optional and set to match the x argument, like setScale elsewhere in the API.
    • โšก๏ธ InputManager.time is a new property that holds the most recent time it was updated from the Game step, which plugins can access.
    • InputManager.preStep is a new method that populates some internal properties every step.
    • ๐Ÿšš KeyboardPlugin.time has moved from being a property to being a getter, which returns the time from the InputManager.
    • The scale property has been added to the Scene class (thanks @strangeweekend)
    • ๐Ÿšš Matter.World.remove now uses the Composite.remove method internally. Previously, it used Composite.removeBody which only allowed it to remove bodies from the simulation. Now, it can remove any type of Matter object.
    • When the Matter World creates its wall bounds, the left and right walls now extend further up and down than before, so that in a 4-wall setting there are no gaps in the corners, which previously allowed for fast moving objects that hit a corner intersection point to sometimes travel through it.
    • ๐Ÿš€ Touch inputs will now trigger a POINTER_OUT event if they leave the game (i.e. are released), where-as before they would only trigger the POINTER_UP event. Now, both happen (thanks @rgk)

    ๐Ÿ› Bug Fixes

    • โช The Mesh.setAlpha method has been restored, even though it's empty and does nothing, to prevent runtime errors when adding a Mesh or Quad object to a Container. Fix #4338 #4343 (thanks @pfdtravalmatic @charmingny)
    • โšก๏ธ KeyboardPlugin.checkDown would always fail if using the new event system, because the time value it was checking wasn't updated.
    • Entering Fullscreen mode in the Scale Manager and then pressing ESC would leave the injected fullsceen div in the DOM, causing it to throw a node insertion failure the second time you wanted to enter fullscreen mode. Fix #4352 (thanks @ngdevr)
    • ๐Ÿ”จ Due to the changes in the Input event system, the GAME_OUT event would never fire unless the input system was in legacy mode. The OUT and OVER handlers have been refactored and will now fire as soon as the DOM event happens. As a result the InputManager._emitIsOverEvent property has been removed, as the native event is sent directly to the handler and doesn't need storing locally any more. Fix #4344 (thanks @RademCZ)
    • โž• Added Zone.setBlendMode method as a NOOP function, fixing a bug where if you added a Zone to a Container when running under Canvas it would fail. Fix #4295 (thanks @emanuel15)

    ๐Ÿ“š 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:

    @maretana @CipSoft-Components @brian-lui

  • v3.16.1 Changes

    February 05, 2019

    ๐Ÿ’ฅ Phaser 3.16 is a massive update. The single largest in the history of Phaser 3 and it contains breaking changes. If you're upgrading from an earlier version please do check the log entries below.

    Please note: there is no difference between 3.16.0 and 3.16.1. The version bump was just to get around a stupid npm semver policy.

    Important Namespace Changes

    • ๐Ÿšš The Phaser.Boot namespace has been renamed to Phaser.Core. As a result, the boot folder has been renamed to core. This impacts the TimeStep class and VisibilityHandler function, which have been moved to be under the new namespace.
    • โšก๏ธ The Phaser.Animations namespace was incorrectly exposed in the Phaser entrypoints as Animation (note the lack of plural). This means that if you are creating any custom classes that extend Animation objects using the Phaser namespace, then please update them from Phaser.Animation to Phaser.Animations, i.e. Phaser.Animation.AnimationFrame to Phaser.Animations.AnimationFrame. This doesn't impact you if you created animations directly via the Animation Manager.
    • The keyed Data Manager change data event string has changed from changedata_ to changedata- to keep it consistent with other keyed events. Note the change from _ to -.
    • The Keyboard Plugin keydown dynamic event string has changed from keydown_ to keydown- to keep it consistent with other keyed events. Note the change from _ to -.
    • The Keyboard Plugin keyup dynamic event string has changed from keyup_ to keyup- to keep it consistent with other keyed events. Note the change from _ to -.
    • The texturesready event emitted by the Texture Manager has been renamed to ready.
    • ๐Ÿ”Œ The loadcomplete event emitted by the Loader Plugin has been renamed to postprocess to be reflect what it's used for.
    • Game Objects used to emit a collide event if they had an Arcade Physics Body with onCollide set, that collided with a Tile. This has changed. The event has been renamed to tilecollide and you should now listen for this event from the Arcade Physics World itself: this.physics.world.on('tilecollide'). Game Objects no longer emit this event.
    • Game Objects used to emit an overlap event if they had an Arcade Physics Body with onOverlap set, that overlapped with a Tile. This has changed. The event has been renamed to tileoverlap and you should now listen for this event from the Arcade Physics World itself: this.physics.world.on('tileoverlap'). Game Objects no longer emit this event.
    • The function Phaser.Physics.Impact.SeperateX has been renamed to SeparateX to correct the spelling mistake.
    • The function Phaser.Physics.Impact.SeperateY has been renamed to SeparateY to correct the spelling mistake.
    • The ended event in WebAudioSound has been renamed to complete to make it more consistent with the rest of the API.
    • The ended event in HTML5AudioSound has been renamed to complete to make it more consistent with the rest of the API.
    • ๐Ÿ›  The Phaser.Utils.Objects namespace was incorrectly exposed in the Phaser entrypoints as Object (note the lack of plural), this has now been fixed so all associated functions are properly namespaced.
    • Phaser.GameObjects.Blitter.Bob has been renamed to Phaser.GameObjects.Bob to avoid namespace conflicts in TypeScript.
    • ๐Ÿ’… Phaser.GameObjects.Text.TextStyle has been renamed to Phaser.GameObjects.TextStyle to avoid namespace conflicts in TypeScript.

    Important Changes to the Input System

    In Phaser 3.15 and earlier the Input system worked using an event queue. All native DOM input events, such as from the Mouse, Touch or Keyboard, were picked up by event handlers and stored in a queue within the Input Manager. This queue was then processed during the next game step, all the events were dealt with and then it was cleared, ready to receive more events. As they were processed, the internal Phaser events such as pointerdown or keyup were dispatched to your game code.

    This worked fine in that you were able to guarantee exactly when the events would arrive, because it was always at the same time in the game step. However, it had the side effect of you not being able to do things like open external browser windows, or go into Full Screen mode, during your event handlers - because they weren't "real" events, so didn't pass the browser security checks. To this end, methods like addUpCallback were added to try and provide this support (although it was never possible for keyboard events).

    ๐Ÿ In 3.16 this has changed. The DOM Events now trigger the respective internal events immediately, in the same invocation. So if you click on the canvas, the pointerdown event you receive in your game is still part of the 'native' event handler, so you're now free to do things like go into full screen mode, or open external windows, without any browser warnings or work-arounds.

    โšก๏ธ It does, however, mean that the point at which these handlers are called is no longer always consistent, and is no longer bound to the speed of the Request Animation Frame update. We've tested as much as possible, and so far, things carry on working as before. We've noticed a slight increase in responsiveness, due to the removal of the fractional delay in processing the events, which feels good. However, if for whatever reason this change has broken your game then you're able to easily switch back to the previous version. In your Game Config, create an input object and give it the property queue: true. This will tell Phaser to use the legacy event queue system.

    Please note that we will remove this legacy system in the near future. So, please try and adapt your games to use the new system. If you've found an edge-case where something breaks because of it, please report it so we can look into it.

    ๐Ÿ—„ As a result of this change, the following are now deprecated:

    • ๐Ÿ”Œ InputPlugin.addUpCallback method.
    • ๐Ÿ”Œ InputPlugin.addDownCallback method.
    • ๐Ÿšš InputPlugin.addMoveCallback method.
    • InputManager.queue property.
    • InputManager.domCallbacks property.
    • InputManager._hasUpCallback property.
    • InputManager._hasDownCallback property.
    • ๐Ÿšš InputManager._hasMoveCallback property.
    • InputManager.processDomCallbacks method.
    • InputManager.addUpCallback method.
    • InputManager.addDownCallback method.
    • ๐Ÿšš InputManager.addMoveCallback method.

    keydown and keyup changes

    Due to unification across the event system, the keydown_ and keyup_ dynamic event strings have changed.

    • In all cases the keydown_KEY event name has changed to keydown-KEY. Note the change from an underscore to a hyphen.
    • In all cases the keyup_KEY event name has changed to keyup-KEY. Note the change from an underscore to a hyphen.

    โšก๏ธ You should update your game code accordingly.

    Keyboard Input - New Features

    ๐Ÿ”Œ The specificity of the Keyboard events has been changed to allow you more control over event handling. Previously, the Keyboard Plugin would emit the global keydown-CODE event first (where CODE was a keycode string, like keydown-A), then it would emit the global keydown event. In previous versions, Key objects, created via this.input.keyboard.addKey(), didn't emit events.

    The Key class now extends EventEmitter and emits two new events directly: down and up. This means you can listen for an event from a Key you've created, i.e.: yourKey.on('up', handler).

    ๐Ÿ”Œ The order has also now changed. If it exists, the Key object will dispatch its down event first. Then the Keyboard Plugin will dispatch keydown_CODE and finally the least specific of them all, keydown will be dispatched.

    ๐Ÿ”Œ You also now have the ability to cancel this at any stage either on a local or global level. All event handlers are sent an event object which you can call event.stopImmediatePropagation() on. This will immediately stop any further listeners from being invoked in the current Scene. Therefore, if you call stopImmediatePropagation() in the Key.on handler, then the Keyboard Plugin will not emit either the keydown-CODE or keydown global events. You can also call stopImmediatePropagation() during the keydown-CODE handler, to stop it reaching the global keydown handler. As keydown is last, calling it there has no effect.

    There is also the stopPropagation() function. This works in the same way as stopImmediatePropagation but instead of being local, it works across all of the Scenes in your game. For example, if you had 3 active Scenes (A, B and C, with A at the top of the Scene list), all listening for the same key, calling stopPropagation() in Scene A would stop the event from reaching any handlers in Scenes B or C. Remember that events flow down the Scene list from top to bottom. So, the top-most rendering Scene in the Scene list has priority over any Scene below it.

    All the above also works for keyup events.

    ๐Ÿ†• New in 3.16 is the ability to receive a global keydown or keyup event from any key on the keyboard. Previously, it would only emit the event if it came from one of the keys listed in the KeyCodes file. Now, those global events will fire for any key, regardless of location.

    Keyboard Captures

    0๏ธโƒฃ Key capturing is the way in which you stop a keyboard DOM event from activating anything else in the browser by calling preventDefault on it. For example, in tall web pages, pressing the SPACE BAR causes the page to scroll down. Obviously, if this is also the fire or jump button in your game, you don't want this to happen. So the key needs to be 'captured' to prevent it. Equally, you may wish to also capture the arrow keys, for similar reasons. Key capturing is done on a global level. If you set-up the capture of a key in one Scene, it will be captured globally across the whole game.

    ๐Ÿ”Œ In 3.16 you now do this using the new KeyboardPlugin.addCapture method. This takes keycodes as its argument. You can either pass in a single key code (i.e. 32 for the Space Bar), an array of key codes, or a comma-delimited string - in which case the string is parsed and each code it can work out is captured.

    ๐Ÿ’… To remove a capture you can use the KeyboardPlugin.removeCapture method, which takes the same style arguments as adding captures. To clear all captures call KeyboardPlugin.clearCaptures. Again, remember that these actions are global.

    ๐Ÿ”Œ You can also temporarily enable and disable capturing using KeyboardPlugin.enableGlobalCapture and KeyboardPlugin.disableGlobalCapture. This means if you set-up a bunch of key captures, but then need to disable them all for a while (perhaps you swap focus to a DOM text field), you can call disableGlobalCapture to do this, and when finished in the DOM you can enable captures again with enableGlobalCapture, without having to clear and re-create them all.

    0๏ธโƒฃ Default captures can be defined in the Game Config in the input.keyboard.captures object. The captures are actually stored in the KeyboardManager class. The KeyboardPlugin is just a proxy to methods in the Keyboard Manager, but is how you should interface with it.

    • 0๏ธโƒฃ KeyboardPlugin.addCapture is a new method that allows you to define a set of keycodes to have the default browser behaviors disabled on.
    • ๐Ÿšš KeyboardPlugin.removeCapture is a new method that removes specific previously set key captures.
    • ๐Ÿšš KeyboardPlugin.clearCaptures is a new method that removes all key captures.
    • ๐Ÿ”Œ KeyboardPlugin.getCaptures is a new method that returns an array of all current key captures.
    • ๐Ÿ”Œ KeyboardPlugin.enableGlobalCapture is a new method that enables any key captures that have been created.
    • ๐Ÿ”Œ KeyboardPlugin.disableGlobalCapture is a new method that disables any key captures that have been created, without removing them from the captures list.
    • 0๏ธโƒฃ KeyboardPlugin.addKey has a new boolean argument enableCapture, which is true by default, that will add a key capture for the Key being created.
    • 0๏ธโƒฃ KeyboardPlugin.addKeys has a new boolean argument enableCapture, which is true by default, that will add a key capture for any Key created by the method.

    โšก๏ธ Other Keyboard Updates and Fixes

    • ๐Ÿ”Œ There is a new class called KeyboardManager. This class is created by the global Input Manager if keyboard access has been enabled in the Game config. It's responsible for handling all browser keyboard events. Previously, the KeyboardPlugin did this which meant that every Scene that had its own Keyboard Plugin was binding more native keyboard events. This was causing problems with parallel Scenes when needing to capture keys. the KeyboardPlugin class still exists, and is still the main point of interface when you call this.input.keyboard in a Scene, but DOM event handling responsibility has been taken away from it. This means there's now only
      one set of bindings ever created, which makes things a lot cleaner.
    • 0๏ธโƒฃ There is a new Game and Scene Config setting input.keyboard.capture which is an array of KeyCodes that the Keyboard Plugin will capture all non-modified key events on. By default it is empty. You can populate it in the config, or use the new capture methods.
    • 0๏ธโƒฃ The Keyboard Manager will now call preventDefault only on non-modified key presses, stopping the keyboard event from hitting the browser. Previously, capturing the R key, for example, would block a CTRL+R page reload, but it now ignores it because of the key modifier.
    • ๐Ÿ’ป If the browser Window loses focus, either from switching to another app, or another tab, all active Keys will be reset. This prevents issues with keys still reporting as being held down after leaving the game and returning to it again. Fix #4134 (thanks @Simplonium)
    • Key.emitOnRepeat is a new boolean property that controls if the Key will continuously emit a down event while being held down (true), or emit the event just once, on first press, and then skip future events (false).
    • Key.setEmitOnRepeat is a new chainable method for setting the emitOnRepeat property.
    • 0๏ธโƒฃ The KeyboardPlugin.addKeys method has a new optional boolean emitOnRepeat which sets that property on all Key objects it creates as part of the call. It defaults to false.
    • 0๏ธโƒฃ The KeyboardPlugin.addKey method has a new optional boolean emitOnRepeat which sets that property on the Key object it creates. It defaults to false.
    • The Key class now extends EventEmitter and emits two events directly: down and up. This means you can listen for an event from a Key you've created, i.e.: yourKey.on('up', handler).
    • The following Key Codes have been added, which include some missing alphabet letters in Persian and Arabic: SEMICOLON_FIREFOX, COLON, COMMA_FIREFOX_WINDOWS, COMMA_FIREFOX, BRACKET_RIGHT_FIREFOX and BRACKET_LEFT_FIREFOX (thanks @wmateam)
    • Key.onDown is a new method that handles the Key being pressed down, including down repeats.
    • ๐Ÿš€ Key.onUp is a new method that handles the Key being released.
    • ๐Ÿ”Œ Key.destroy is a new method that handles Key instance destruction. It is called automatically in KeyboardPlugin.destroy.
    • ๐Ÿšš The Key.preventDefault property has been removed. This is now handled by the global keyboard capture methods.
    • ๐Ÿ Key.metaKey is a new boolean property which indicates if the Meta Key was held down when the Key was pressed. On a Mac the Meta Key is Command. On a Windows keyboard, it's the Windows key.
    • InputManager.keyboard is a new property that instantiates the global Keyboard Manager, if enabled in the game config.
    • 0๏ธโƒฃ The KeyboardPlugin.addKey method has a new boolean property enableCapture which automatically prevents default on the Key being created.
    • 0๏ธโƒฃ The KeyboardPlugin.addKeys method has a new boolean property enableCapture which automatically prevents default on Keys being created.
    • ๐Ÿšš Phaser.Input.Keyboard.ProcessKeyDown has been removed as it's no longer required, Key.onDown handles it instead.
    • ๐Ÿšš Phaser.Input.Keyboard.ProcessKeyUp has been removed as it's no longer required, Key.onUp handles it instead.
    • 0๏ธโƒฃ The Keyboard Manager has a property called captures which is an array of keycodes, as populated by the Game Config. Any key code in the array will have preventDefault called on it if pressed.
    • ๐Ÿ”Œ KeyboardPlugin.manager is a new property that references the Keyboard Manager and is used internally.
    • ๐Ÿšš KeyboardPlugin.target has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.queue has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.onKeyHandler has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.startListeners has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.stopListeners has been removed as it's no longer used by the class.

    โšก๏ธ Mouse and Touch Input - New Features, Updates and Fixes

    • โšก๏ธ The Mouse Manager class has been updated to remove some commented out code and refine the startListeners method.
    • When enabling a Game Object for input it will now use the width and height properties of the Game Object first, falling back to the frame size if not found. This stops a bug when enabling BitmapText objects for input and it using the font texture as the hit area size, rather than the text itself.
    • ๐Ÿ“ฆ Pointer.smoothFactor is a float-value that allows you to automatically apply smoothing to the Pointer position as it moves. This is ideal when you want something smoothly tracking a pointer in a game, or are need a smooth drawing motion for an art package. The default value is zero, meaning disabled. Set to a small number, such as 0.2, to enable.
    • 0๏ธโƒฃ Config.inputSmoothFactor is a new property that allows you to set the smoothing factor for all Pointers the game creates. The default value is zero, which is disabled. Set in the game config as input: { smoothFactor: value }.
    • ๐Ÿšš InputManager.transformPointer has a new boolean argument wasMove, which controls if the pointer is being transformed after a move or up/down event.
    • โšก๏ธ Pointer.velocity is a new Vector2 that contains the velocity of the Pointer, based on the current and previous positions. The velocity is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The velocity is updated based on Pointer movement and doesn't require a button to be pressed first.
    • โšก๏ธ Pointer.angle is a new property that contains the angle of the Pointer, in radians, based on the current and previous positions. The angle is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The angle is updated based on Pointer movement and doesn't require a button to be pressed first.
    • โšก๏ธ Pointer.distance is a new property that contains the distance of the Pointer, in radians, based on the current and previous positions. The distance is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The distance is updated based on Pointer movement and doesn't require a button to be pressed first.
    • 0๏ธโƒฃ Pointer.motionFactor is a new property that controls how much smoothing to apply to the Pointer positions each frame. This value is passed to the Smooth Step Interpolation that is used to calculate the velocity, angle and distance of the Pointer. It's applied every frame until the midPoint reaches the current position of the Pointer. The default value is 0.2.
    • โšก๏ธ The Input Plugin was emitting a preUpdate event, with the capital U, instead of preupdate. This has now been corrected. Fix #4185 (thanks @gadelan)
    • โšก๏ธ Pointer.updateMotion is a new method that is called automatically, each step, by the Input Manager. It's responsible for calculating the Pointer velocity, angle and distance properties.
    • โšก๏ธ Pointer.time is a new property that holds the time the Pointer was last updated by the Game step.
    • โšก๏ธ Pointer.getDistance has been updated. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • Pointer.getDistanceX is a new method that will return the horizontal distance between the Pointer's previous and current coordinates. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • Pointer.getDistanceY is a new method that will return the horizontal distance between the Pointer's previous and current coordinates. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • ๐Ÿš€ Pointer.getDuration is a new method that will return the duration the Pointer was held down for. If the Pointer has a button pressed down at the time this method is called, it will return the duration since the Pointer's button was pressed down. If no button is held down, it will return the last recorded duration, based on the time the Pointer button was released.
    • ๐Ÿš€ Pointer.getAngle is a new method that will return the angle between the Pointer coordinates. If the Pointer has a button pressed down at the time this method is called, it will return the angle between the Pointer's downX and downY values and the current position. If no button is held down, it will return the last recorded angle, based on where the Pointer was when the button was released.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mousedown listener for the game canvas and then call window.focus when detected (assuming the game config autoFocus property was true). Responsibility for this has now been moved to the Mouse Manager onMouseDown handler.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mouseout listener for the game canvas and then set game.isOver when detected. Responsibility for this has now been moved to the Mouse Manager, which sets the new Input Manager isOver property directly.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mouseover listener for the game canvas and then set game.isOver when detected. Responsibility for this has now been moved to the Mouse Manager, which sets the new Input Manager isOver property directly.
    • ๐Ÿšš The Phaser.Game.isOver property has been moved. You can now find it in the Input Manager and it's also accessible via the Input Plugin, which means you can do this.input.isOver from within a Scene. This makes more sense as it's input related and not a game level property.
    • ๐Ÿšš The Input Plugin has a new event you can listen to: gameover, which is triggered whenever the mouse or a pointer is moved over the Game canvas. Listen to it with this.input.on('gameover') from within a Scene.
    • ๐Ÿ”Œ The Input Plugin has a new event you can listen to: gameout, which is triggered whenever the mouse or a pointer leaves the Game canvas. Listen to it with this.input.on('gameout') from within a Scene.
    • ๐Ÿ”Œ The Game used to emit a mouseover event when the mouse entered the game canvas. This is no longer emitted by the Game itself and can instead be listened for using the new Input Plugin event gameover.
    • ๐Ÿ”Œ The Game used to emit a mouseout event when the mouse left the game canvas. This is no longer emitted by the Game itself and can instead be listened for using the new Input Plugin event gameout.
    • ๐Ÿš€ If the window object exists (which it will in normal browser environments) new mouseup and touchend event listeners are bound to it and trigger the normal mouseup or touchend events within the internal input system. This means you will now get a pointerup event from the Input Plugin even if the pointer is released outside of the game canvas. Pointers will also no longer think they are still 'down' if released outside the canvas and then moved inside again in their new state.
    • The window will now have focus called on it by the Touch Manager, as well as the Mouse Manager, if the autoFocus game config property is enabled.
    • ๐Ÿ”Œ The Input Plugin has a new event you can listen to: pointerdownoutside, which is triggered whenever the mouse or a pointer is pressed down while outside of the Game canvas. Listen to it with this.input.on('pointerdownoutside') from within a Scene.
    • ๐Ÿš€ The Input Plugin has a new event you can listen to: pointerupoutside, which is triggered whenever the mouse or a pointer is released while outside of the Game canvas. Listen to it with this.input.on('pointerupoutside') from within a Scene.
    • Pointer.downElement is a new property that holds the target of the DOM Event that triggered when the Pointer was pressed down. If this is within the game, this will be the game canvas element.
    • ๐Ÿš€ Pointer.upElement is a new property that holds the target of the DOM Event that triggered when the Pointer was released. If this is within the game, this will be the game canvas element.
    • ๐Ÿšš The Pointer.dragState property has been removed. This is no longer used internally as it has to be tracked per Scene, not on a global level.
    • ๐Ÿ”Œ InputPlugin.setDragState is a new internal method that sets the drag state for the given Pointer.
    • ๐Ÿ”Œ InputPlugin.getDragState is a new internal method that gets the drag state for the given Pointer.
    • Draggable Game Objects would not work if you had multiple Scenes running in parallel, with draggable objects in both of them. Only the top-most Scene would work fully. Items in the bottom Scene would never finish their drag cycle, causing them to get stuck. Fix #4249 #4278 (thanks @probt @iArePJ)
    • Pointer.leftButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.rightButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.middleButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.backButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.forwardButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • โšก๏ธ Pointer.up, Pointer.move and Pointer.down now use in to check for the existance of the buttons property on the event, causing it to be set even if equal to zero, which it is when there are no buttons down. This also fixes an issue where the buttons didn't update during a move event (thanks @SonnyCampbell @rexrainbow)

    ๐Ÿ”„ Changes as a result of the new Scale Manager

    3.16 introduces the completed Scale Manager. This is fully documented, but the class, all methods and all properties. It also includes a folder full of examples in the Phaser Labs, so you're strongly recommended to start there.

    • If you set the Game Config property zoom to be > 1 then it will automatically enable pixelArt mode, unless you set pixelArt: false in the config.
    • ๐ŸŽ There is a new property in the Game Config called autoRound, which controls if the canvas size and style sizes are passed through Math.floor or not. On some devices this can help with performance and anti-aliasing. The default is false (turned off).
    • ๐Ÿšš The Game Config property autoResize has been removed as it's now redundant.
    • โšก๏ธ The WebGL and Canvas Renderers no longer change the Canvas size in their resize methods. They just update internal properties.
    • The WebGL and Canvas Renderers now read the width, height and resolution values from the Scale Manager, not the Game Config.
    • ๐Ÿšš CameraManager.baseScale property has been removed as it's no longer used anywhere.
    • The BaseCamera and Camera preRender methods now only take a resolution argument and use it internally for their transforms.
    • InputManager.scaleManager is a new property that is a reference to the Scale Manager. This is populated in the boot method.
    • ๐Ÿšš The InputManager.transformX method has been removed. This is now available in the ScaleManager.
    • ๐Ÿšš The InputManager.transformY method has been removed. This is now available in the ScaleManager.
    • ๐Ÿšš The InputManager.scale property has been removed. This is now available in the ScaleManager under displayScale.
    • ๐Ÿšš The InputManager.resize method has been removed as this process is now handled by the ScaleManager.
    • ๐Ÿšš The InputManager.bounds property has been removed as this process is now handled by the ScaleManager.
    • โšก๏ธ The InputManager.updateBounds method has been removed as this process is now handled by the ScaleManager.
    • ๐Ÿšš The InputManager.getOffsetX method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getOffsetY method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getScaleX method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getScaleY method has been removed as it's no longer required.
    • ๐Ÿšš The SceneManager.resize method has been removed as it's no longer required.
    • ๐Ÿšš The Scene.Systems.resize method has been removed as it's no longer required.
    • Scenes will no longer dispatch the resize event. You should now listen for this event from the Scale Manager instead.
    • ๐Ÿšš BaseCamera.config has been removed as it's no longer required.
    • BaseCamera.scaleManager is a new property that references the Scale Manager and is used internally for size checks.
    • ๐Ÿšš The Game.resize method has been removed as it's no longer required. You should now call ScaleManager.resize instead.
    • The Game will no longer dispatch the resize event. You should now listen for this event from the Scale Manager instead.

    โšก๏ธ Facebook Instant Games Updates and Fixes

    • โž• Added the Leaderboard.getConnectedScores method, to get a list of scores from player connected entries.
    • โšก๏ธ The loadPlayerPhoto function in the Instant Games plugin now listens for the updated Loader event correctly, causing the photocomplete event to fire properly.
    • ๐Ÿ“š Leaderboard.setScore now emits the LeaderboardScore object with the setscore event, as the documentation said it did.
    • Leaderboard.getPlayerScore now only populates the playerScore property if the entry isn't null.
    • If the setScore or getPlayerScore calls fail, it will return null as the score instance, instead of causing a run-time error.
    • You can now pass an object or a string to setScore and objects will be automatically stringified.
    • The preloadAds method will now only create an AdInstance object if the interstitial loadSync promise resolves.
    • The preloadVideoAds method will now only create an AdInstance object if the interstitial loadSync promise resolves.
    • The preloadAds method will now emit the adsnofill event, if there are no ads in the inventory to load.
    • The preloadVideoAds method will now emit the adsnofill event, if there are no ads in the inventory to load.
    • The showAd method will now emit the adsnotloaded event, if there are no ads loaded matching the given Placement ID.
    • The showVideo method will now emit the adsnotloaded event, if there are no ads loaded matching the given Placement ID.
    • ๐Ÿ‘‰ Showing an ad will emit the adfinished event when the ad is closed, previously this event was called showad but the new name better reflects what has happened.
    • ๐Ÿ”Œ The Facebook Plugin is now available in the Phaser.Scene class template under the facebook property (thanks @bryanwood)
    • ๐Ÿ›  Fixed the Leaderboard.getScores method to now take the arguments into account. Fix #4271 (thanks @Oramy)
    • ๐Ÿ›  Fixed an API validation error in the chooseContext method. Fix #4248 (thanks @yadurajiv)

    ๐Ÿ†• New Features

    • ๐Ÿ“š You can now load external Scene files using the new load.sceneFile method. This allows you to dynamically load a Scene into the Scene Manager of your game, and swap to it at will. Please see the documentation and examples for further details.
    • The data object being sent to the Dynamic Bitmap Text callback now has a new property parent, which is a reference to the Bitmap Text instance that owns the data object (thanks ornyth)
    • The WebGL Renderer has a new method clearPipeline, which will clear down the current pipeline and reset the blend mode, ready for the context to be passed to a 3rd party library.
    • The WebGL Renderer has a new method rebindPipeline, which will rebind the given pipeline instance, reset the blank texture and reset the blend mode. This is useful for recovering from 3rd party libs that have modified the gl context.
    • ๐Ÿšš Game Objects have a new property called state. Use this to track the state of a Game Object during its lifetime. For example, it could move from a state of 'moving', to 'attacking', to 'dead'. Phaser itself will never set this property, although plugins are allowed to.
    • Game Objects have a new method called setState which will set the state property in a chainable call.
    • ๐ŸŒ BlendModes.ERASE is a new blend mode that will erase the object being drawn. When used in conjunction with a Render Texture it allows for effects that require you to erase parts of the texture, in either Canvas or WebGL. When used with a transparent game canvas, it allows you to erase parts of the canvas, showing the web page background through.
    • BlendModes.SOURCE_IN is a new Canvas-only blend mode that allows you to use the source-in composite operation when rendering Game Objects.
    • BlendModes.SOURCE_OUT is a new Canvas-only blend mode that allows you to use the source-out composite operation when rendering Game Objects.
    • BlendModes.SOURCE_ATOP is a new Canvas-only blend mode that allows you to use the source-atop composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_OVER is a new Canvas-only blend mode that allows you to use the destination-over composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_IN is a new Canvas-only blend mode that allows you to use the destination-in composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_OUT is a new Canvas-only blend mode that allows you to use the destination-out composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_ATOP is a new Canvas-only blend mode that allows you to use the destination-atop composite operation when rendering Game Objects.
    • BlendModes.LIGHTER is a new Canvas-only blend mode that allows you to use the lighter composite operation when rendering Game Objects.
    • BlendModes.COPY is a new Canvas-only blend mode that allows you to use the copy composite operation when rendering Game Objects.
    • BlendModes.XOR is a new Canvas-only blend mode that allows you to use the xor composite operation when rendering Game Objects.
    • ๐Ÿšš RenderTexture.erase is a new method that will take an object, or array of objects, and draw them to the Render Texture using an ERASE blend mode, resulting in them being removed from the Render Texture. This is really handy for making a bitmap masked texture in Canvas or WebGL (without using an actual mask), or for 'cutting away' part of a texture.
    • There is a new boolean Game Config property called customEnvironment. If set to true it will skip the internal Feature checks when working out which type of renderer to create, allowing you to run Phaser under non-native web environments. If using this value, you must set an explicit renderType of either CANVAS or WEBGL. It cannot be left as AUTO. Fix #4166 (thanks @jcyuan)
    • Animation.nextFrame will advance an animation to the next frame in the sequence instantly, regardless of the animation time or state. You can call this on a Sprite: sprite.anims.nextFrame() (thanks rgk25)
    • Animation.previousFrame will set an animation to the previous frame in the sequence instantly, regardless of the animation time or state. You can call this on a Sprite: sprite.anims.previousFrame() (thanks rgk25)
    • 0๏ธโƒฃ Geom.Intersects.PointToLine has a new optional argument lineThickness (which defaults to 1). This allows you to determine if the point intersects a line of a given thickness, where the line-ends are circular (not square).
    • Geom.Line.GetNearestPoint is a new static method that will return the nearest point on a line to the given point.
    • โœ… Geom.Line.GetShortestDistance is a new static method that will return the shortest distance from a line to the given point.
    • Camera.getBounds is a new method that will return a rectangle containing the bounds of the camera.
    • ๐Ÿšš Camera.centerOnX will move the camera horizontally to be centered on the given coordinate without changing its vertical placement.
    • ๐Ÿšš Camera.centerOnY will move the camera vertically to be centered on the given coordinate without changing its horizontally placement.
    • ๐Ÿ‘€ AnimationManager.exists is a new method that will check to see if an Animation using the given key already exists or not and returns a boolean.
    • animationstart-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationstart-explode.
    • animationrestart-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationrestart-explode.
    • animationcomplete-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationcomplete-explode.
    • โšก๏ธ animationupdate-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationupdate-explode.
    • The Animation class now extends the Event Emitter and dispatches events itself. This allows you to listen for events from a specific Animation, rather than via a Game Object. This is handy, for example, if you had an explosion animation that you wanted to trigger a sound effect when it started. You can now listen for the events from the Animation object directly.
    • The Animation class now emits the start event when played (either forward, or in reverse) by any Game Object.
    • The Animation class now emits the restart event when it restarts playing on any Game Object.
    • The Animation class now emits the complete event when it finishes playing on any Game Object.
    • The Animation Component has a new method called chain which allows you to line-up another animation to start playing as soon as the current one stops, no matter how it stops (either by reaching its natural end, or directly by having stop called on it). You can chain a new animation at any point, including before the current one starts playing, during it, or when it ends (via its animationcomplete callback). Chained animations are specific to a Game Object, meaning different Game Objects can have different chained animations without impacting the global animation they're playing.
    • CanvasTexture.drawFrame is a new method that allows you to draw a texture frame to the CanvasTexture based on the texture key and frame given.
    • CanvasTexture.getIndex is a new method that will take an x/y coordinate and return the Image Data index offset used to retrieve the pixel values.
    • CanvasTexture.getPixels is a new method that will take a region as an x/y and width/height and return all of the pixels in that region from the CanvasTexture.
    • CanvasTexture.setPixel is a new method that sets the given pixel in the CanvasTexture to the color and alpha values provided.
    • CanvasTexture.getData is a new method that will extract an ImageData block from the CanvasTexture from the region given.
    • CanvasTexture.putData is a new method that will put an ImageData block at the given coordinates in a CanvasTexture.
    • Line.Extend is a new static function that allows you extend the start and/or end points of a Line by the given amounts.
    • Vector2.LEFT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.RIGHT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.UP is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.DOWN is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.ONE is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.ZERO is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.LEFT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.RIGHT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.UP is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.DOWN is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.FORWARD is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.BACK is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.ONE is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Geometery Mask has a new property called invertAlpha in WebGL, which works in the same way as the flag on the Bitmap Mask and allows you to invert the function of the stencil buffer, i.e. non-drawn shapes become invisible, and drawn shapes visible (thanks @tfelix)
    • The Arcade Physics Body has a new property maxSpeed which limits the vector length of the Body velocity. You can set it via the method setMaxSpeed and it is applied in the World.computeVelocity method (thanks @Edwin222 @rexrainbow)
    • WebGLRenderer.snapshotArea is a new method that allows you to grab an image of the given region of the canvas during the post-render step and have it sent to your defined callback. This is the same as snapshot except you control the area being grabbed, so is more efficient if you only need a smaller area.
    • WebGLRenderer.snapshotPixel is a new method that allows you to grab a single pixel from the game canvas, post-render. It returns the result as a Color object to your specified callback.
    • CanvasRenderer.snapshotArea is a new method that allows you to grab an image of the given region of the canvas during the post-render step and have it sent to your defined callback. This is the same as snapshot except you control the area being grabbed, so is more efficient if you only need a smaller area.
    • CanvasRenderer.snapshotPixel is a new method that allows you to grab a single pixel from the game canvas, post-render. It returns the result as a Color object to your specified callback.
    • SceneManager.getScenes is a new method that will return all current Scenes being managed by the Scene Manager. You can optionally return only active scenes and reverse the order in which they are returned in the array.
    • DOM.GetTarget is a new helper function that will return a reference to a DOM Element based on the given string or node.
    • ๐Ÿ”Œ GameObjects.Extern is a new special type of Game Object that allows you to pass rendering off to a 3rd party. When you create an Extern and place it in the display list of a Scene, the renderer will process the list as usual. When it finds an Extern it will flush the current batch, clear down the pipeline and prepare a transform matrix which your render function can take advantage of, if required. The Extern Game Object is used heavily by the Spine Plugin, but can also be used by other libraries such as three.js, allowing them to render directly into a Phaser game.

    โšก๏ธ Updates

    • 0๏ธโƒฃ You can now modify this.physics.world.debugGraphic.defaultStrokeWidth to set the stroke width of any debug drawn body, previously it was always 1 (thanks @samme)
    • ๐Ÿ’… TextStyle.setFont has a new optional argument updateText which will sets if the text should be automatically updated or not (thanks @DotTheGreat)
    • ProcessQueue.destroy now sets the internal toProcess counter to zero.
    • ๐Ÿšš The PathFollower.pathRotationVerticalAdjust property has been removed. It was supposed to flipY a follower when it reversed path direction, but after some testing it appears it has never worked and it's easier to do this using events, so the property and associated config value are removed. The verticalAdjust argument from the setRotateToPath method has been removed as well.
    • ๐Ÿšš The config value preserveDrawingBuffer has been removed as it has never been used by the WebGL Renderer.
    • ๐Ÿ”Œ PluginManager.install returns null if the plugin failed to install in all cases.
    • PluginFile will now install the plugin into the current Scene as long as the start or mapping arguments are provided.
    • MATH_CONST no longer requires or sets the Random Data Generator, this is now done in the Game Config, allowing you to require the math constants without pulling in a whole copy of the RNG with it.
    • The Dynamic Bitmap Text Canvas Renderer was creating a new data object every frame for the callback. It now uses the callbackData object instead, like the WebGL renderer does.
    • WebGLRenderer.setBlendMode has a new optional argument force, which will force the given blend mode to be set, regardless of the current settings.
    • ๐Ÿšš The method DisplayList.sortGameObjects has been removed. It has thrown a runtime error since v3.3.0(!) which no-one even spotted which is a good indication of how little the method was used. The display list is automatically sorted anyway, so if you need to sort a small section of it, just use the standard JavaScript Array sort method (thanks ornyth)
    • ๐Ÿšš The method DisplayList.getTopGameObject has been removed. It has thrown a runtime error since v3.3.0(!) which no-one even spotted which is a good indication of how little the method was used (thanks ornyth)
    • โšก๏ธ WebGLRenderer.setFramebuffer has a new optional boolean argument updateScissor, which will reset the scissor to match the framebuffer size, or clear it.
    • WebAudioSoundManager.onFocus will not try to resume the Audio Context if it's still locked.
    • WebAudioSoundManager.onBlur will not try to suspend the Audio Context if it's still locked.
    • ๐Ÿ”Œ When using ScenePlugin.add, to add a new Scene to the Scene Manager, it didn't allow you to include the optional Scene data object. You can now pass this in the call (thanks @kainage)
    • Graphics.stroke is a new alias for the strokePath method, to keep the calls consistent with the Canvas Rendering Context API.
    • Graphics.fill is a new alias for the fillPath method, to keep the calls consistent with the Canvas Rendering Context API.
    • ๐Ÿ”Œ LoaderPlugin.sceneManager is a new property that is a reference to the global Scene Manager, useful for Plugins.
    • ๐Ÿ‘ Whenever Camera.roundPixels was enabled it would use a bitwise operation to truncate the float (x |= 0) - this has been replaced across all files that used it, with a call to Math.round instead. This gives far better results when zooming cameras both in and out of a Scene, stopping thin gaps appearing between closely packed Game Objects.
    • AnimationManager.create will now return a boolean false if the given key is invalid (i.e. undefined or falsey).
    • โš  AnimationManager.create will no longer raise a console warning if the animation key is already in use. Instead, it will return the animation belonging to that key. A brand new animation will only be created if the key isn't already in use. When this happens, the add event is emitted by the Animation Manager. If no event is emitted, the animation already existed.
    • ArcadePhysics.Body.destroy will now only add itself to the World pendingDestroy list if the world property exists. This prevents Cannot read property 'pendingDestroy' of undefined errors if you try to delete a physics body in a callback and then immediately change Scene (which tells the physics work to also delete all bodies)
    • ๐Ÿšš The Animation Component restart method has had is sole key argument removed. Previously, you had to pass in the key of the animation you wished to reverse, but now you can just call the method directly, and as long as there is an animation playing, it will automatically start playing in reverse, without the nee for a key (the way it should have been originally)
    • Animation.play and playReverse will now accept either a string-based key of the animation to play (like before), or you can pass in an Animation instance, and it will play that animation.
    • CanvasTexture.clear now has 4 new optional arguments: x, y, width, height which allow you to define the region of the texture to be cleared. If not provided it will clear the whole texture, which is the same behavior as before.
    • ๐ŸŽ EarCut, the polygon triangulation library used by the Graphics and WebGL classes, has been upgraded from 2.1.1 to 2.1.4. 2.1.2 fixed a few race conditions where bad input would cause an error. 2.1.3 improved performance for bigger inputs (5-12%) and 2.1.4 fixed a race condition that could lead to a freeze on degenerate input.
    • TextureTintPipeline.batchQuad and batchTri have two new optional arguments texture and unit which are used to re-set the batch texture should the method cause a batch flush.
    • TextureTintPipeline.requireTextureBatch is a new internal method that helps speed-up the creation of texture batches. It is used in conjunction with setTexture2D and pushBatch.
    • ๐Ÿ”จ TextureTintPipeline.flush and TextureTintPipeline.pushBatch have been optimized to handle zero based texture units as priority. They've also been refactored to avoid creation of empty texture batches.
    • The WebGLRenderer.setTexture2D method has a new optional argument flush which controls if the pipeline is flushed if the given texture is new, or not. This is used internally to skip flushing during an existing flush.
    • The Tilemap Layer width and height properties are now based on the tilemap tile sizes multiplied by the layer dimensions. This corrects an issue with layer sizes being wrong if you called setBaseTileSize on a Map.
    • The WebGLRenderer will now clear the framebuffer at the start of every render.
    • 0๏ธโƒฃ WebGLRenderer.setScissor now has a new optional argument drawingBufferHeight which allows you to specify the drawing buffer height, rather than use the renderers default value.
    • 0๏ธโƒฃ WebGLRenderer.pushScissor now has a new optional argument drawingBufferHeight which allows you to specify the drawing buffer height, rather than use the renderers default value.
    • โช WebGLRenderer.preRender now calls gl.clearColor in order to restore the background clear color in case something, like a Render Texture, has changed it.
    • โšก๏ธ Map.set will now update an existing value if you provide it with a key that already exists within the Map. Previously, if you tried to set the value of a key that existed it would be skipped.
    • MatterSprite would set its type property to be Image. It now sets it to be Sprite as it should do.
    • โšก๏ธ Matter.TileBody.setFromTileCollision no longer checks if the shape is concave or convex before modifying the vertices, as the update to the Matter.js lib in 3.12 stopped this from working with Tiled collision shapes.
    • The Scene transitionstart event is now dispatched by the Target Scene of a transition, regardless if the Scene has a create method or not. Previously, it was only dispatched if the Scene had a create method.
    • ๐Ÿ’ป The Loader will now allow an XHR status of 0 as success too. Normally only status 200 would be accepted as success, but 0 is returned when a file is loaded from the local filesystem (file://). This happens, for example, when opening the index.html of a game in a browser directly, or when using Cordova on iOS. Fix #3464 (thanks @Ithamar)
    • Tween.restart now returns the Tween instance (thanks @rexrainbow)
    • Tween.play now returns the Tween instance (thanks @rexrainbow)
    • ๐Ÿ‘€ Tween.seek now returns the Tween instance (thanks @rexrainbow)
    • Tween.complete now returns the Tween instance (thanks @rexrainbow)
    • Tween.stop now returns the Tween instance (thanks @rexrainbow)
    • List.sort now has an optional parameter handler which allows you to provide your own sort handling function (thanks @jcyuan)
    • Container.sort now has an optional parameter handler which allows you to provide your own sort handling function (thanks @jcyuan)
    • The WebGLRenderer method canvasToTexture will now only set the filter to be NEAREST if antialias is disabled in the game config (i.e. when running in pixelArt mode). This means that Text objects, and other Canvas backed textures, now render with anti-aliasing if everything else does. You can disable this on a per-object basis by calling texture.setFilter(1) on them.
    • ๐Ÿšš CanvasRenderer.snapshotCallback, snapshotType and snapshotEncoder have all been removed as they are no longer required.
    • ๐Ÿ”ง CanvasRenderer.snapshotState is a new object that contains the snapshot configuration data, the same as the WebGL Renderer.
    • ๐Ÿ”ง The signature of the WebGLSnapshot function has changed. It now takes a Snapshot Configuration object as the second parameter.
    • ๐Ÿ”ง The signature of the CanvasSnapshot function has changed. It now takes a Snapshot Configuration object as the second parameter.
    • A Tween Timeline will now set it's internal destroy state before calling either the onComplete callback or sending the COMPLETE event. This means you can now call methods that will change the state of the Timeline, such as play, during the callback handlers, where-as before doing this would have had the internal state changed immediately, preventing it (thanks Lucas Knight)
    • ๐Ÿ’… The AddToDOM method has had the overflowHidden argument removed. The DOM element the canvas is inserted into no longer has overflow: hidden applied to its style. If you wish to have this, please add it directly via CSS.

    ๐Ÿ› Bug Fixes

    • The Rectangle Shape object wouldn't render if it didn't have a stroke, or any other objects on the display list (thanks mliko)
    • ๐Ÿ’… When using a font string instead of setting fontFamily, fontSize and fontStyle in either Text.setStyle or setFont, the style properties wouldn't get set. This isn't a problem while creating the text object, only if modifying it later (thanks @DotTheGreat)
    • ๐Ÿ’… Text.toJSON wasn't saving the font style when using the "font" shorthand to create it. It now saves it correctly. Fix #4141 (thanks @divillysausages)
    • Disabling camera bounds and then moving the camera to an area in a Tilemap that did not have any tile information would throw an Uncaught Reference error as it tried to access tiles that did not exist (thanks @Siyalatas)
    • ๐Ÿ›  Fixed an issue where Sprite Sheets being extracted from a texture atlas would fail if the sheet was either just a single column or single row of sprites. Fix #4096 (thanks @Cirras)
    • ๐Ÿ”ง If you created an Arcade Physics Group without passing a configuration object, and passing an array of non-standard children, it would throw a classType runtime error. It now creates a default config object correctly (thanks @pierpo)
    • The Camera.cull method has been restructured so it now calculates if a Game Object is correctly in view or not before culling it. Although not used internally, if you need to cull objects for a camera, you can now safely use this method. Fix #4092 (thanks @Cirras)
    • ๐Ÿ“œ The Tiled Parser would ignore animated tile data if it was in the new Tiled 1.2 format. This is now accounted for, as well as 1.0 (thanks @nkholski)
    • Array.Matrix.ReverseRows was actually reversing the columns, but now reverses the rows.
    • Array.Matrix.ReverseColumns was actually reversing the rows, but now reverses the columns.
    • UnityAtlas now sets the correct file type key if using a config file object.
    • Starting with version 3.13 in the Canvas Renderer, it was possible for long-running scripts to start to get bogged-down in fillRect calls if the game had a background color set. The context is now saved properly to avoid this. Fix #4056 (thanks @Aveyder)
    • 0๏ธโƒฃ Render Textures created larger than the size of the default canvas would be automatically clipped when drawn to in WebGL. They now reset the gl scissor and drawing height property in order to draw to their full size, regardless of the canvas size. Fix #4139 (thanks @chaoyang805 @iamchristopher)
    • The cameraFilter property of a Game Object will now allow full bitmasks to be set (a value of -1), instead of just those > 0 (thanks @stuartkeith)
    • The PathFollower.startFollow method now properly uses the startAt argument to the method, so you can start a follower off at any point along the path. Fix #3688 (thanks @DannyT @diteix)
    • Static Circular Arcade Physics Bodies now render as circles in the debug display instead of showing their rectangle bounds (thanks @maikthomas)
    • Changing the mute flag on an HTML5AudioSound instance, via the mute setter, now works as it does via the Sound Manager (thanks @Waclaw-I @neon-dev)
    • Changing the volume on an HTML5AudioSound instance, via the volume setter, now works as it does via the Sound Manager (thanks @Waclaw-I)
    • The Dynamic Tilemap Layer WebGL renderer was drawing tiles at the incorrect position if the layer was scaled. Fix #4104 (thanks @the-realest-stu)
    • Tile.tileset now returns the specific Tileset associated with the tile rather than an array of them. Fix #4095 (thanks @quadrupleslap)
    • ๐Ÿ‘ Tile.getCollisionGroup wouldn't return the correct Group after the change to support multiple Tilesets. It now returns the group properly (thanks @jbpuryear)
    • ๐Ÿ‘ Tile.getTileData wouldn't return the correct data after the change to support multiple Tilesets. It now returns the tile data properly (thanks @jbpuryear)
    • ๐Ÿšš The GetTileAt and RemoveTileAt components would error with "Cannot read property 'index' of undefined" if the tile was undefined rather than null. It now handles both cases (thanks @WaSa42)
    • โšก๏ธ Changing TileSprite.width or TileSprite.height will now flag the texture as dirty and call updateDisplayOrigin, allowing you to resize TileSprites dynamically in both Canvas and WebGL.
    • ๐Ÿ›  RandomDataGenerator.shuffle has been fixed to use the proper modifier in the calculation allowing for a more even distribution (thanks wayfinder)
    • ๐Ÿ’ป The Particle Emitter was not recycling dead particles correctly so it was creating new objects every time it emitted (the old particles were then left to the browsers gc to clear up). This has now been recoded so the emitter will properly keep track of dead particles and re-use them (thanks @Waclaw-I for the initial PR)
    • ๐Ÿšš ParticleEmitter.indexSortCallback has been removed as it's no longer required.
    • ๐Ÿšš Particle.index has been removed as it's no longer required. Particles don't need to keep track of their index any more.
    • โšก๏ธ The Particle Emitter no longer needs to call the StableSort.inplace during its preUpdate, saving cpu.
    • Particle.resetPosition is a new method that is called when a particle dies preparing it for firing again in the future.
    • โช The Canvas SetTransform method would save the context state, but it wasn't restored at the end in the following Game Objects: Dynamic Bitmap Text, Graphics, Arc, Curve, Ellipse, Grid, IsoBox, IsoTriangle, Line, Polygon, Rectangle, Star and Triangle. These now all restore the context, meaning if you're using non-canvas sized cameras in Canvas mode, it will now render beyond just the first custom camera.
    • ๐Ÿšš Utils.Array.MoveUp wouldn't let you move an array element to the top-most index in the array. This also impacted Container.moveUp.
    • The Texture Tint Pipeline had a logic error that would cause every 2001st quad to either be invisible, or pick-up the texture of the 2000th quad by mistake. The batchQuad and batchTri methods how handle re-assigning the batch texture if they cause a batch flush as part of their process.
    • Rotating Sprites that used a Normal Map wouldn't rotate the normal map with it causing the lighting effects to become irregular. The normal map vectors are now rotated correctly (thanks @sercant for the PR and @fazzamatazz and @ysraelJMM for the report)
    • Changing scaleX or scaleY on a MatterImage or MatterSprite would cause the body scale to become distorted as the setters didn't use the correct factor when resetting the initial scale. Fix #4206 (thanks @YannCaron)
    • โšก๏ธ StaticBody.reset in Arcade Physics would ignore the x and y values given to it. If given, they're now used to reset the parent Game Object before the body is updated. Fix #4224 (thanks @samme)
    • Static Tilemap Layers wouldn't render correctly if the layer used a tileset with a different size to the base map data (set via setBaseTileSize). They now render correctly in WebGL and Canvas regardless of the base tile size.
    • When using RenderTexture.fill, the alpha argument would be ignored in Canvas mode. It's now used when filling the RenderTexture.
    • ๐Ÿ›  Fixed an issue in WebGLRenderer.setScissor where it was possible to try and compare the scissor size to a non-current scissor if called outside of the render loop (i.e. from RenderTexture.fill) (thanks @hackhat)
    • RenderTexture.fill in WebGL would use gl.clear and a clear color to try and fill the Render Texture. This only worked for full-canvas sized RenderTextures that didn't have a camera zoom applied. It has now been swapped to use the drawFillRect method of the Texture Tint Pipeline, allowing it to work properly regardless of camera zoom or size.
    • Container.getFirst was using an incorrect Array Utils function GetFirstElement when it should have been using GetFirst. It now uses the correct function. Fix #4244 (thanks @miran248)
    • List.getFirst was using an incorrect Array Utils function GetFirstElement when it should have been using GetFirst. It now uses the correct function. Fix #4244 (thanks @miran248)
    • ๐Ÿ›  Fixed an issue where changing the viewport or size of a Camera belonging to a RenderTexture wouldn't impact the rendering and objects will still render outside of the viewport range. It's now converted to a proper gl scissor rect by the renderer, meaning you can limit the area rendered to by adjusting the internal Render Texture cameras viewport. Fix #4243 (thanks @hackhat)
    • CanvasTexture.destroy is a new method that specifically handles the destruction of the CanvasTexture and all of its associated typed arrays. This prevents a memory leak when creating and destroying lots of RenderTextures (which are CanvasTexture backed). Fix #4239 (thanks @sjb933)
    • ๐Ÿšš The Alpha, Flip and Origin components have been removed from the Mesh Game Object (and by extension, Quad as well) as they are not used in the renderer and should be manipulated via the Mesh properties. Fix #4188 (thanks @enriqueto)
    • ๐Ÿšš The processDomCallbacks method in the Input Manager wasn't correctly clearing the once arrays. Responsibility for this has now been passed to the queue methods queueTouchStart, queueTouchMove, queueTouchEnd, queueMouseDown, queueMouseMove and queueMouseUp. Fix #4257 (thanks @iArePJ)
    • โšก๏ธ Arcade Physics now manages when postUpdate should be applied better, stopping it from gaining a zero delta during a further check in the same frame. This fixes various issues, including the mass collision test demo. Fix #4154 (thanks @samme)
    • Arcade Physics could trigger a collide event on a Body even if it performing an overlap check, if the onCollide property was true (thanks @samme)
    • TileSprites no longer cause a crash when using the Headless mode renderer. Fix #4297 (thanks @clesquir)
    • The WebGLRenderer will now apply a transparent background if transparent = true in the game config (thanks @gomachan7)
    • List.sort was missing the scope required for the sort handler, this is now correctly provided internally. Fix #4241 (thanks @jcyuan)
    • Container.sort was missing the scope required for the sort handler, this is now correctly provided internally. Fix #4241 (thanks @jcyuan)
    • DataManager.pop would emit the DataManager instance, instead of the parent, as the first event argument. It now emits the parent as it should do. Fix #4186 (thanks @gadelan)
    • The GetValue function wasn't checking for the existance of '.' in the config property name correctly, causing the branch to always be taken (thanks @kyranet)
    • Safari had permission problems playing HTML5 Audio files on Mac OS. Due to the changes in the input event system audio now plays properly based on user interactions. You still can't play it automatically, though, it will always require a user gesture to begin. Fix #4217 (thanks @increpare)

    Examples and TypeScript

    ๐Ÿ‘ Thanks to the following for helping with the Phaser 3 Examples and TypeScript definitions, either by reporting errors, or even better, fixing them:

    @guilhermehto @samvieten @darkwebdev @RoryO @snowbillr @slothyrulez @jcyuan @jestarray @CzBiX

    Phaser Doc Jam

    ๐Ÿ“š The Phaser Doc Jam was a community-backed effort to try and get the Phaser 3 API documentation to 100% coverage. The Doc Jam is now over and I offer my thanks to the following who helped with docs in this release:

    @16patsle - @gurungrahul2 - @icbat - @samme - @telinc1 - anandu pavanan - blackhawx - candelibas - Diego Romero - doronlinder - Elliott Wallace - eric - Georges Gabereau - Haobo Zhang - henriacle - jak6jak - Jake Jensen - James Van Roose - JamesSkemp - joelahoover - Joey - madclaws - marc136 - Mihail Ilinov - naum303 - NicolasRoehm - nuane - rejacobson - Robert Kowalski - rodri042 - rootasjey - sawamara - scottwestover - sir13tommy - stetso - therealsamf - Tigran - willblackmore - zenwaichi

    ๐Ÿ“„ Also, the following helped with the docs outside of the Doc Jam:

    @bryanwood @jestarray @matosummer @tfelix @imilo @BigZaphod @OmarShehata @16patsle @jcyuan @iam13islucky @FractalBobz Endre

  • v3.16.0 Changes

    February 05, 2019

    ๐Ÿ’ฅ Phaser 3.16 is a massive update. The single largest in the history of Phaser 3 and it contains breaking changes. If you're upgrading from an earlier version please do check the log entries below.

    Important Namespace Changes

    • ๐Ÿšš The Phaser.Boot namespace has been renamed to Phaser.Core. As a result, the boot folder has been renamed to core. This impacts the TimeStep class and VisibilityHandler function, which have been moved to be under the new namespace.
    • โšก๏ธ The Phaser.Animations namespace was incorrectly exposed in the Phaser entrypoints as Animation (note the lack of plural). This means that if you are creating any custom classes that extend Animation objects using the Phaser namespace, then please update them from Phaser.Animation to Phaser.Animations, i.e. Phaser.Animation.AnimationFrame to Phaser.Animations.AnimationFrame. This doesn't impact you if you created animations directly via the Animation Manager.
    • The keyed Data Manager change data event string has changed from changedata_ to changedata- to keep it consistent with other keyed events. Note the change from _ to -.
    • The Keyboard Plugin keydown dynamic event string has changed from keydown_ to keydown- to keep it consistent with other keyed events. Note the change from _ to -.
    • The Keyboard Plugin keyup dynamic event string has changed from keyup_ to keyup- to keep it consistent with other keyed events. Note the change from _ to -.
    • The texturesready event emitted by the Texture Manager has been renamed to ready.
    • ๐Ÿ”Œ The loadcomplete event emitted by the Loader Plugin has been renamed to postprocess to be reflect what it's used for.
    • Game Objects used to emit a collide event if they had an Arcade Physics Body with onCollide set, that collided with a Tile. This has changed. The event has been renamed to tilecollide and you should now listen for this event from the Arcade Physics World itself: this.physics.world.on('tilecollide'). Game Objects no longer emit this event.
    • Game Objects used to emit an overlap event if they had an Arcade Physics Body with onOverlap set, that overlapped with a Tile. This has changed. The event has been renamed to tileoverlap and you should now listen for this event from the Arcade Physics World itself: this.physics.world.on('tileoverlap'). Game Objects no longer emit this event.
    • The function Phaser.Physics.Impact.SeperateX has been renamed to SeparateX to correct the spelling mistake.
    • The function Phaser.Physics.Impact.SeperateY has been renamed to SeparateY to correct the spelling mistake.
    • The ended event in WebAudioSound has been renamed to complete to make it more consistent with the rest of the API.
    • The ended event in HTML5AudioSound has been renamed to complete to make it more consistent with the rest of the API.
    • ๐Ÿ›  The Phaser.Utils.Objects namespace was incorrectly exposed in the Phaser entrypoints as Object (note the lack of plural), this has now been fixed so all associated functions are properly namespaced.
    • Phaser.GameObjects.Blitter.Bob has been renamed to Phaser.GameObjects.Bob to avoid namespace conflicts in TypeScript.
    • ๐Ÿ’… Phaser.GameObjects.Text.TextStyle has been renamed to Phaser.GameObjects.TextStyle to avoid namespace conflicts in TypeScript.

    Important Changes to the Input System

    In Phaser 3.15 and earlier the Input system worked using an event queue. All native DOM input events, such as from the Mouse, Touch or Keyboard, were picked up by event handlers and stored in a queue within the Input Manager. This queue was then processed during the next game step, all the events were dealt with and then it was cleared, ready to receive more events. As they were processed, the internal Phaser events such as pointerdown or keyup were dispatched to your game code.

    This worked fine in that you were able to guarantee exactly when the events would arrive, because it was always at the same time in the game step. However, it had the side effect of you not being able to do things like open external browser windows, or go into Full Screen mode, during your event handlers - because they weren't "real" events, so didn't pass the browser security checks. To this end, methods like addUpCallback were added to try and provide this support (although it was never possible for keyboard events).

    ๐Ÿ In 3.16 this has changed. The DOM Events now trigger the respective internal events immediately, in the same invocation. So if you click on the canvas, the pointerdown event you receive in your game is still part of the 'native' event handler, so you're now free to do things like go into full screen mode, or open external windows, without any browser warnings or work-arounds.

    โšก๏ธ It does, however, mean that the point at which these handlers are called is no longer always consistent, and is no longer bound to the speed of the Request Animation Frame update. We've tested as much as possible, and so far, things carry on working as before. We've noticed a slight increase in responsiveness, due to the removal of the fractional delay in processing the events, which feels good. However, if for whatever reason this change has broken your game then you're able to easily switch back to the previous version. In your Game Config, create an input object and give it the property queue: true. This will tell Phaser to use the legacy event queue system.

    Please note that we will remove this legacy system in the near future. So, please try and adapt your games to use the new system. If you've found an edge-case where something breaks because of it, please report it so we can look into it.

    ๐Ÿ—„ As a result of this change, the following are now deprecated:

    • ๐Ÿ”Œ InputPlugin.addUpCallback method.
    • ๐Ÿ”Œ InputPlugin.addDownCallback method.
    • ๐Ÿšš InputPlugin.addMoveCallback method.
    • InputManager.queue property.
    • InputManager.domCallbacks property.
    • InputManager._hasUpCallback property.
    • InputManager._hasDownCallback property.
    • ๐Ÿšš InputManager._hasMoveCallback property.
    • InputManager.processDomCallbacks method.
    • InputManager.addUpCallback method.
    • InputManager.addDownCallback method.
    • ๐Ÿšš InputManager.addMoveCallback method.

    keydown and keyup changes

    Due to unification across the event system, the keydown_ and keyup_ dynamic event strings have changed.

    • In all cases the keydown_KEY event name has changed to keydown-KEY. Note the change from an underscore to a hyphen.
    • In all cases the keyup_KEY event name has changed to keyup-KEY. Note the change from an underscore to a hyphen.

    โšก๏ธ You should update your game code accordingly.

    Keyboard Input - New Features

    ๐Ÿ”Œ The specificity of the Keyboard events has been changed to allow you more control over event handling. Previously, the Keyboard Plugin would emit the global keydown-CODE event first (where CODE was a keycode string, like keydown-A), then it would emit the global keydown event. In previous versions, Key objects, created via this.input.keyboard.addKey(), didn't emit events.

    The Key class now extends EventEmitter and emits two new events directly: down and up. This means you can listen for an event from a Key you've created, i.e.: yourKey.on('up', handler).

    ๐Ÿ”Œ The order has also now changed. If it exists, the Key object will dispatch its down event first. Then the Keyboard Plugin will dispatch keydown_CODE and finally the least specific of them all, keydown will be dispatched.

    ๐Ÿ”Œ You also now have the ability to cancel this at any stage either on a local or global level. All event handlers are sent an event object which you can call event.stopImmediatePropagation() on. This will immediately stop any further listeners from being invoked in the current Scene. Therefore, if you call stopImmediatePropagation() in the Key.on handler, then the Keyboard Plugin will not emit either the keydown-CODE or keydown global events. You can also call stopImmediatePropagation() during the keydown-CODE handler, to stop it reaching the global keydown handler. As keydown is last, calling it there has no effect.

    There is also the stopPropagation() function. This works in the same way as stopImmediatePropagation but instead of being local, it works across all of the Scenes in your game. For example, if you had 3 active Scenes (A, B and C, with A at the top of the Scene list), all listening for the same key, calling stopPropagation() in Scene A would stop the event from reaching any handlers in Scenes B or C. Remember that events flow down the Scene list from top to bottom. So, the top-most rendering Scene in the Scene list has priority over any Scene below it.

    All the above also works for keyup events.

    ๐Ÿ†• New in 3.16 is the ability to receive a global keydown or keyup event from any key on the keyboard. Previously, it would only emit the event if it came from one of the keys listed in the KeyCodes file. Now, those global events will fire for any key, regardless of location.

    Keyboard Captures

    0๏ธโƒฃ Key capturing is the way in which you stop a keyboard DOM event from activating anything else in the browser by calling preventDefault on it. For example, in tall web pages, pressing the SPACE BAR causes the page to scroll down. Obviously, if this is also the fire or jump button in your game, you don't want this to happen. So the key needs to be 'captured' to prevent it. Equally, you may wish to also capture the arrow keys, for similar reasons. Key capturing is done on a global level. If you set-up the capture of a key in one Scene, it will be captured globally across the whole game.

    ๐Ÿ”Œ In 3.16 you now do this using the new KeyboardPlugin.addCapture method. This takes keycodes as its argument. You can either pass in a single key code (i.e. 32 for the Space Bar), an array of key codes, or a comma-delimited string - in which case the string is parsed and each code it can work out is captured.

    ๐Ÿ’… To remove a capture you can use the KeyboardPlugin.removeCapture method, which takes the same style arguments as adding captures. To clear all captures call KeyboardPlugin.clearCaptures. Again, remember that these actions are global.

    ๐Ÿ”Œ You can also temporarily enable and disable capturing using KeyboardPlugin.enableGlobalCapture and KeyboardPlugin.disableGlobalCapture. This means if you set-up a bunch of key captures, but then need to disable them all for a while (perhaps you swap focus to a DOM text field), you can call disableGlobalCapture to do this, and when finished in the DOM you can enable captures again with enableGlobalCapture, without having to clear and re-create them all.

    0๏ธโƒฃ Default captures can be defined in the Game Config in the input.keyboard.captures object. The captures are actually stored in the KeyboardManager class. The KeyboardPlugin is just a proxy to methods in the Keyboard Manager, but is how you should interface with it.

    • 0๏ธโƒฃ KeyboardPlugin.addCapture is a new method that allows you to define a set of keycodes to have the default browser behaviors disabled on.
    • ๐Ÿšš KeyboardPlugin.removeCapture is a new method that removes specific previously set key captures.
    • ๐Ÿšš KeyboardPlugin.clearCaptures is a new method that removes all key captures.
    • ๐Ÿ”Œ KeyboardPlugin.getCaptures is a new method that returns an array of all current key captures.
    • ๐Ÿ”Œ KeyboardPlugin.enableGlobalCapture is a new method that enables any key captures that have been created.
    • ๐Ÿ”Œ KeyboardPlugin.disableGlobalCapture is a new method that disables any key captures that have been created, without removing them from the captures list.
    • 0๏ธโƒฃ KeyboardPlugin.addKey has a new boolean argument enableCapture, which is true by default, that will add a key capture for the Key being created.
    • 0๏ธโƒฃ KeyboardPlugin.addKeys has a new boolean argument enableCapture, which is true by default, that will add a key capture for any Key created by the method.

    โšก๏ธ Other Keyboard Updates and Fixes

    • ๐Ÿ”Œ There is a new class called KeyboardManager. This class is created by the global Input Manager if keyboard access has been enabled in the Game config. It's responsible for handling all browser keyboard events. Previously, the KeyboardPlugin did this which meant that every Scene that had its own Keyboard Plugin was binding more native keyboard events. This was causing problems with parallel Scenes when needing to capture keys. the KeyboardPlugin class still exists, and is still the main point of interface when you call this.input.keyboard in a Scene, but DOM event handling responsibility has been taken away from it. This means there's now only
      one set of bindings ever created, which makes things a lot cleaner.
    • 0๏ธโƒฃ There is a new Game and Scene Config setting input.keyboard.capture which is an array of KeyCodes that the Keyboard Plugin will capture all non-modified key events on. By default it is empty. You can populate it in the config, or use the new capture methods.
    • 0๏ธโƒฃ The Keyboard Manager will now call preventDefault only on non-modified key presses, stopping the keyboard event from hitting the browser. Previously, capturing the R key, for example, would block a CTRL+R page reload, but it now ignores it because of the key modifier.
    • ๐Ÿ’ป If the browser Window loses focus, either from switching to another app, or another tab, all active Keys will be reset. This prevents issues with keys still reporting as being held down after leaving the game and returning to it again. Fix #4134 (thanks @Simplonium)
    • Key.emitOnRepeat is a new boolean property that controls if the Key will continuously emit a down event while being held down (true), or emit the event just once, on first press, and then skip future events (false).
    • Key.setEmitOnRepeat is a new chainable method for setting the emitOnRepeat property.
    • 0๏ธโƒฃ The KeyboardPlugin.addKeys method has a new optional boolean emitOnRepeat which sets that property on all Key objects it creates as part of the call. It defaults to false.
    • 0๏ธโƒฃ The KeyboardPlugin.addKey method has a new optional boolean emitOnRepeat which sets that property on the Key object it creates. It defaults to false.
    • The Key class now extends EventEmitter and emits two events directly: down and up. This means you can listen for an event from a Key you've created, i.e.: yourKey.on('up', handler).
    • The following Key Codes have been added, which include some missing alphabet letters in Persian and Arabic: SEMICOLON_FIREFOX, COLON, COMMA_FIREFOX_WINDOWS, COMMA_FIREFOX, BRACKET_RIGHT_FIREFOX and BRACKET_LEFT_FIREFOX (thanks @wmateam)
    • Key.onDown is a new method that handles the Key being pressed down, including down repeats.
    • ๐Ÿš€ Key.onUp is a new method that handles the Key being released.
    • ๐Ÿ”Œ Key.destroy is a new method that handles Key instance destruction. It is called automatically in KeyboardPlugin.destroy.
    • ๐Ÿšš The Key.preventDefault property has been removed. This is now handled by the global keyboard capture methods.
    • ๐Ÿ Key.metaKey is a new boolean property which indicates if the Meta Key was held down when the Key was pressed. On a Mac the Meta Key is Command. On a Windows keyboard, it's the Windows key.
    • InputManager.keyboard is a new property that instantiates the global Keyboard Manager, if enabled in the game config.
    • 0๏ธโƒฃ The KeyboardPlugin.addKey method has a new boolean property enableCapture which automatically prevents default on the Key being created.
    • 0๏ธโƒฃ The KeyboardPlugin.addKeys method has a new boolean property enableCapture which automatically prevents default on Keys being created.
    • ๐Ÿšš Phaser.Input.Keyboard.ProcessKeyDown has been removed as it's no longer required, Key.onDown handles it instead.
    • ๐Ÿšš Phaser.Input.Keyboard.ProcessKeyUp has been removed as it's no longer required, Key.onUp handles it instead.
    • 0๏ธโƒฃ The Keyboard Manager has a property called captures which is an array of keycodes, as populated by the Game Config. Any key code in the array will have preventDefault called on it if pressed.
    • ๐Ÿ”Œ KeyboardPlugin.manager is a new property that references the Keyboard Manager and is used internally.
    • ๐Ÿšš KeyboardPlugin.target has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.queue has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.onKeyHandler has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.startListeners has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.stopListeners has been removed as it's no longer used by the class.

    โšก๏ธ Mouse and Touch Input - New Features, Updates and Fixes

    • โšก๏ธ The Mouse Manager class has been updated to remove some commented out code and refine the startListeners method.
    • When enabling a Game Object for input it will now use the width and height properties of the Game Object first, falling back to the frame size if not found. This stops a bug when enabling BitmapText objects for input and it using the font texture as the hit area size, rather than the text itself.
    • ๐Ÿ“ฆ Pointer.smoothFactor is a float-value that allows you to automatically apply smoothing to the Pointer position as it moves. This is ideal when you want something smoothly tracking a pointer in a game, or are need a smooth drawing motion for an art package. The default value is zero, meaning disabled. Set to a small number, such as 0.2, to enable.
    • 0๏ธโƒฃ Config.inputSmoothFactor is a new property that allows you to set the smoothing factor for all Pointers the game creates. The default value is zero, which is disabled. Set in the game config as input: { smoothFactor: value }.
    • ๐Ÿšš InputManager.transformPointer has a new boolean argument wasMove, which controls if the pointer is being transformed after a move or up/down event.
    • โšก๏ธ Pointer.velocity is a new Vector2 that contains the velocity of the Pointer, based on the current and previous positions. The velocity is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The velocity is updated based on Pointer movement and doesn't require a button to be pressed first.
    • โšก๏ธ Pointer.angle is a new property that contains the angle of the Pointer, in radians, based on the current and previous positions. The angle is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The angle is updated based on Pointer movement and doesn't require a button to be pressed first.
    • โšก๏ธ Pointer.distance is a new property that contains the distance of the Pointer, in radians, based on the current and previous positions. The distance is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The distance is updated based on Pointer movement and doesn't require a button to be pressed first.
    • 0๏ธโƒฃ Pointer.motionFactor is a new property that controls how much smoothing to apply to the Pointer positions each frame. This value is passed to the Smooth Step Interpolation that is used to calculate the velocity, angle and distance of the Pointer. It's applied every frame until the midPoint reaches the current position of the Pointer. The default value is 0.2.
    • โšก๏ธ The Input Plugin was emitting a preUpdate event, with the capital U, instead of preupdate. This has now been corrected. Fix #4185 (thanks @gadelan)
    • โšก๏ธ Pointer.updateMotion is a new method that is called automatically, each step, by the Input Manager. It's responsible for calculating the Pointer velocity, angle and distance properties.
    • โšก๏ธ Pointer.time is a new property that holds the time the Pointer was last updated by the Game step.
    • โšก๏ธ Pointer.getDistance has been updated. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • Pointer.getDistanceX is a new method that will return the horizontal distance between the Pointer's previous and current coordinates. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • Pointer.getDistanceY is a new method that will return the horizontal distance between the Pointer's previous and current coordinates. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • ๐Ÿš€ Pointer.getDuration is a new method that will return the duration the Pointer was held down for. If the Pointer has a button pressed down at the time this method is called, it will return the duration since the Pointer's button was pressed down. If no button is held down, it will return the last recorded duration, based on the time the Pointer button was released.
    • ๐Ÿš€ Pointer.getAngle is a new method that will return the angle between the Pointer coordinates. If the Pointer has a button pressed down at the time this method is called, it will return the angle between the Pointer's downX and downY values and the current position. If no button is held down, it will return the last recorded angle, based on where the Pointer was when the button was released.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mousedown listener for the game canvas and then call window.focus when detected (assuming the game config autoFocus property was true). Responsibility for this has now been moved to the Mouse Manager onMouseDown handler.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mouseout listener for the game canvas and then set game.isOver when detected. Responsibility for this has now been moved to the Mouse Manager, which sets the new Input Manager isOver property directly.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mouseover listener for the game canvas and then set game.isOver when detected. Responsibility for this has now been moved to the Mouse Manager, which sets the new Input Manager isOver property directly.
    • ๐Ÿšš The Phaser.Game.isOver property has been moved. You can now find it in the Input Manager and it's also accessible via the Input Plugin, which means you can do this.input.isOver from within a Scene. This makes more sense as it's input related and not a game level property.
    • ๐Ÿšš The Input Plugin has a new event you can listen to: gameover, which is triggered whenever the mouse or a pointer is moved over the Game canvas. Listen to it with this.input.on('gameover') from within a Scene.
    • ๐Ÿ”Œ The Input Plugin has a new event you can listen to: gameout, which is triggered whenever the mouse or a pointer leaves the Game canvas. Listen to it with this.input.on('gameout') from within a Scene.
    • ๐Ÿ”Œ The Game used to emit a mouseover event when the mouse entered the game canvas. This is no longer emitted by the Game itself and can instead be listened for using the new Input Plugin event gameover.
    • ๐Ÿ”Œ The Game used to emit a mouseout event when the mouse left the game canvas. This is no longer emitted by the Game itself and can instead be listened for using the new Input Plugin event gameout.
    • ๐Ÿš€ If the window object exists (which it will in normal browser environments) new mouseup and touchend event listeners are bound to it and trigger the normal mouseup or touchend events within the internal input system. This means you will now get a pointerup event from the Input Plugin even if the pointer is released outside of the game canvas. Pointers will also no longer think they are still 'down' if released outside the canvas and then moved inside again in their new state.
    • The window will now have focus called on it by the Touch Manager, as well as the Mouse Manager, if the autoFocus game config property is enabled.
    • ๐Ÿ”Œ The Input Plugin has a new event you can listen to: pointerdownoutside, which is triggered whenever the mouse or a pointer is pressed down while outside of the Game canvas. Listen to it with this.input.on('pointerdownoutside') from within a Scene.
    • ๐Ÿš€ The Input Plugin has a new event you can listen to: pointerupoutside, which is triggered whenever the mouse or a pointer is released while outside of the Game canvas. Listen to it with this.input.on('pointerupoutside') from within a Scene.
    • Pointer.downElement is a new property that holds the target of the DOM Event that triggered when the Pointer was pressed down. If this is within the game, this will be the game canvas element.
    • ๐Ÿš€ Pointer.upElement is a new property that holds the target of the DOM Event that triggered when the Pointer was released. If this is within the game, this will be the game canvas element.
    • ๐Ÿšš The Pointer.dragState property has been removed. This is no longer used internally as it has to be tracked per Scene, not on a global level.
    • ๐Ÿ”Œ InputPlugin.setDragState is a new internal method that sets the drag state for the given Pointer.
    • ๐Ÿ”Œ InputPlugin.getDragState is a new internal method that gets the drag state for the given Pointer.
    • Draggable Game Objects would not work if you had multiple Scenes running in parallel, with draggable objects in both of them. Only the top-most Scene would work fully. Items in the bottom Scene would never finish their drag cycle, causing them to get stuck. Fix #4249 #4278 (thanks @probt @iArePJ)
    • Pointer.leftButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.rightButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.middleButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.backButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.forwardButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • โšก๏ธ Pointer.up, Pointer.move and Pointer.down now use in to check for the existance of the buttons property on the event, causing it to be set even if equal to zero, which it is when there are no buttons down. This also fixes an issue where the buttons didn't update during a move event (thanks @SonnyCampbell @rexrainbow)

    ๐Ÿ”„ Changes as a result of the new Scale Manager

    3.16 introduces the completed Scale Manager. This is fully documented, but the class, all methods and all properties. It also includes a folder full of examples in the Phaser Labs, so you're strongly recommended to start there.

    • If you set the Game Config property zoom to be > 1 then it will automatically enable pixelArt mode, unless you set pixelArt: false in the config.
    • ๐ŸŽ There is a new property in the Game Config called autoRound, which controls if the canvas size and style sizes are passed through Math.floor or not. On some devices this can help with performance and anti-aliasing. The default is false (turned off).
    • ๐Ÿšš The Game Config property autoResize has been removed as it's now redundant.
    • โšก๏ธ The WebGL and Canvas Renderers no longer change the Canvas size in their resize methods. They just update internal properties.
    • The WebGL and Canvas Renderers now read the width, height and resolution values from the Scale Manager, not the Game Config.
    • ๐Ÿšš CameraManager.baseScale property has been removed as it's no longer used anywhere.
    • The BaseCamera and Camera preRender methods now only take a resolution argument and use it internally for their transforms.
    • InputManager.scaleManager is a new property that is a reference to the Scale Manager. This is populated in the boot method.
    • ๐Ÿšš The InputManager.transformX method has been removed. This is now available in the ScaleManager.
    • ๐Ÿšš The InputManager.transformY method has been removed. This is now available in the ScaleManager.
    • ๐Ÿšš The InputManager.scale property has been removed. This is now available in the ScaleManager under displayScale.
    • ๐Ÿšš The InputManager.resize method has been removed as this process is now handled by the ScaleManager.
    • ๐Ÿšš The InputManager.bounds property has been removed as this process is now handled by the ScaleManager.
    • โšก๏ธ The InputManager.updateBounds method has been removed as this process is now handled by the ScaleManager.
    • ๐Ÿšš The InputManager.getOffsetX method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getOffsetY method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getScaleX method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getScaleY method has been removed as it's no longer required.
    • ๐Ÿšš The SceneManager.resize method has been removed as it's no longer required.
    • ๐Ÿšš The Scene.Systems.resize method has been removed as it's no longer required.
    • Scenes will no longer dispatch the resize event. You should now listen for this event from the Scale Manager instead.
    • ๐Ÿšš BaseCamera.config has been removed as it's no longer required.
    • BaseCamera.scaleManager is a new property that references the Scale Manager and is used internally for size checks.
    • ๐Ÿšš The Game.resize method has been removed as it's no longer required. You should now call ScaleManager.resize instead.
    • The Game will no longer dispatch the resize event. You should now listen for this event from the Scale Manager instead.

    โšก๏ธ Facebook Instant Games Updates and Fixes

    • โž• Added the Leaderboard.getConnectedScores method, to get a list of scores from player connected entries.
    • โšก๏ธ The loadPlayerPhoto function in the Instant Games plugin now listens for the updated Loader event correctly, causing the photocomplete event to fire properly.
    • ๐Ÿ“š Leaderboard.setScore now emits the LeaderboardScore object with the setscore event, as the documentation said it did.
    • Leaderboard.getPlayerScore now only populates the playerScore property if the entry isn't null.
    • If the setScore or getPlayerScore calls fail, it will return null as the score instance, instead of causing a run-time error.
    • You can now pass an object or a string to setScore and objects will be automatically stringified.
    • The preloadAds method will now only create an AdInstance object if the interstitial loadSync promise resolves.
    • The preloadVideoAds method will now only create an AdInstance object if the interstitial loadSync promise resolves.
    • The preloadAds method will now emit the adsnofill event, if there are no ads in the inventory to load.
    • The preloadVideoAds method will now emit the adsnofill event, if there are no ads in the inventory to load.
    • The showAd method will now emit the adsnotloaded event, if there are no ads loaded matching the given Placement ID.
    • The showVideo method will now emit the adsnotloaded event, if there are no ads loaded matching the given Placement ID.
    • ๐Ÿ‘‰ Showing an ad will emit the adfinished event when the ad is closed, previously this event was called showad but the new name better reflects what has happened.
    • ๐Ÿ”Œ The Facebook Plugin is now available in the Phaser.Scene class template under the facebook property (thanks @bryanwood)
    • ๐Ÿ›  Fixed the Leaderboard.getScores method to now take the arguments into account. Fix #4271 (thanks @Oramy)
    • ๐Ÿ›  Fixed an API validation error in the chooseContext method. Fix #4248 (thanks @yadurajiv)

    ๐Ÿ†• New Features

    • ๐Ÿ“š You can now load external Scene files using the new load.sceneFile method. This allows you to dynamically load a Scene into the Scene Manager of your game, and swap to it at will. Please see the documentation and examples for further details.
    • The data object being sent to the Dynamic Bitmap Text callback now has a new property parent, which is a reference to the Bitmap Text instance that owns the data object (thanks ornyth)
    • The WebGL Renderer has a new method clearPipeline, which will clear down the current pipeline and reset the blend mode, ready for the context to be passed to a 3rd party library.
    • The WebGL Renderer has a new method rebindPipeline, which will rebind the given pipeline instance, reset the blank texture and reset the blend mode. This is useful for recovering from 3rd party libs that have modified the gl context.
    • ๐Ÿšš Game Objects have a new property called state. Use this to track the state of a Game Object during its lifetime. For example, it could move from a state of 'moving', to 'attacking', to 'dead'. Phaser itself will never set this property, although plugins are allowed to.
    • Game Objects have a new method called setState which will set the state property in a chainable call.
    • ๐ŸŒ BlendModes.ERASE is a new blend mode that will erase the object being drawn. When used in conjunction with a Render Texture it allows for effects that require you to erase parts of the texture, in either Canvas or WebGL. When used with a transparent game canvas, it allows you to erase parts of the canvas, showing the web page background through.
    • BlendModes.SOURCE_IN is a new Canvas-only blend mode that allows you to use the source-in composite operation when rendering Game Objects.
    • BlendModes.SOURCE_OUT is a new Canvas-only blend mode that allows you to use the source-out composite operation when rendering Game Objects.
    • BlendModes.SOURCE_ATOP is a new Canvas-only blend mode that allows you to use the source-atop composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_OVER is a new Canvas-only blend mode that allows you to use the destination-over composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_IN is a new Canvas-only blend mode that allows you to use the destination-in composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_OUT is a new Canvas-only blend mode that allows you to use the destination-out composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_ATOP is a new Canvas-only blend mode that allows you to use the destination-atop composite operation when rendering Game Objects.
    • BlendModes.LIGHTER is a new Canvas-only blend mode that allows you to use the lighter composite operation when rendering Game Objects.
    • BlendModes.COPY is a new Canvas-only blend mode that allows you to use the copy composite operation when rendering Game Objects.
    • BlendModes.XOR is a new Canvas-only blend mode that allows you to use the xor composite operation when rendering Game Objects.
    • ๐Ÿšš RenderTexture.erase is a new method that will take an object, or array of objects, and draw them to the Render Texture using an ERASE blend mode, resulting in them being removed from the Render Texture. This is really handy for making a bitmap masked texture in Canvas or WebGL (without using an actual mask), or for 'cutting away' part of a texture.
    • There is a new boolean Game Config property called customEnvironment. If set to true it will skip the internal Feature checks when working out which type of renderer to create, allowing you to run Phaser under non-native web environments. If using this value, you must set an explicit renderType of either CANVAS or WEBGL. It cannot be left as AUTO. Fix #4166 (thanks @jcyuan)
    • Animation.nextFrame will advance an animation to the next frame in the sequence instantly, regardless of the animation time or state. You can call this on a Sprite: sprite.anims.nextFrame() (thanks rgk25)
    • Animation.previousFrame will set an animation to the previous frame in the sequence instantly, regardless of the animation time or state. You can call this on a Sprite: sprite.anims.previousFrame() (thanks rgk25)
    • 0๏ธโƒฃ Geom.Intersects.PointToLine has a new optional argument lineThickness (which defaults to 1). This allows you to determine if the point intersects a line of a given thickness, where the line-ends are circular (not square).
    • Geom.Line.GetNearestPoint is a new static method that will return the nearest point on a line to the given point.
    • โœ… Geom.Line.GetShortestDistance is a new static method that will return the shortest distance from a line to the given point.
    • Camera.getBounds is a new method that will return a rectangle containing the bounds of the camera.
    • ๐Ÿšš Camera.centerOnX will move the camera horizontally to be centered on the given coordinate without changing its vertical placement.
    • ๐Ÿšš Camera.centerOnY will move the camera vertically to be centered on the given coordinate without changing its horizontally placement.
    • ๐Ÿ‘€ AnimationManager.exists is a new method that will check to see if an Animation using the given key already exists or not and returns a boolean.
    • animationstart-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationstart-explode.
    • animationrestart-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationrestart-explode.
    • animationcomplete-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationcomplete-explode.
    • โšก๏ธ animationupdate-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationupdate-explode.
    • The Animation class now extends the Event Emitter and dispatches events itself. This allows you to listen for events from a specific Animation, rather than via a Game Object. This is handy, for example, if you had an explosion animation that you wanted to trigger a sound effect when it started. You can now listen for the events from the Animation object directly.
    • The Animation class now emits the start event when played (either forward, or in reverse) by any Game Object.
    • The Animation class now emits the restart event when it restarts playing on any Game Object.
    • The Animation class now emits the complete event when it finishes playing on any Game Object.
    • The Animation Component has a new method called chain which allows you to line-up another animation to start playing as soon as the current one stops, no matter how it stops (either by reaching its natural end, or directly by having stop called on it). You can chain a new animation at any point, including before the current one starts playing, during it, or when it ends (via its animationcomplete callback). Chained animations are specific to a Game Object, meaning different Game Objects can have different chained animations without impacting the global animation they're playing.
    • CanvasTexture.drawFrame is a new method that allows you to draw a texture frame to the CanvasTexture based on the texture key and frame given.
    • CanvasTexture.getIndex is a new method that will take an x/y coordinate and return the Image Data index offset used to retrieve the pixel values.
    • CanvasTexture.getPixels is a new method that will take a region as an x/y and width/height and return all of the pixels in that region from the CanvasTexture.
    • CanvasTexture.setPixel is a new method that sets the given pixel in the CanvasTexture to the color and alpha values provided.
    • CanvasTexture.getData is a new method that will extract an ImageData block from the CanvasTexture from the region given.
    • CanvasTexture.putData is a new method that will put an ImageData block at the given coordinates in a CanvasTexture.
    • Line.Extend is a new static function that allows you extend the start and/or end points of a Line by the given amounts.
    • Vector2.LEFT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.RIGHT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.UP is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.DOWN is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.ONE is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.ZERO is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.LEFT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.RIGHT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.UP is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.DOWN is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.FORWARD is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.BACK is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.ONE is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Geometery Mask has a new property called invertAlpha in WebGL, which works in the same way as the flag on the Bitmap Mask and allows you to invert the function of the stencil buffer, i.e. non-drawn shapes become invisible, and drawn shapes visible (thanks @tfelix)
    • The Arcade Physics Body has a new property maxSpeed which limits the vector length of the Body velocity. You can set it via the method setMaxSpeed and it is applied in the World.computeVelocity method (thanks @Edwin222 @rexrainbow)
    • WebGLRenderer.snapshotArea is a new method that allows you to grab an image of the given region of the canvas during the post-render step and have it sent to your defined callback. This is the same as snapshot except you control the area being grabbed, so is more efficient if you only need a smaller area.
    • WebGLRenderer.snapshotPixel is a new method that allows you to grab a single pixel from the game canvas, post-render. It returns the result as a Color object to your specified callback.
    • CanvasRenderer.snapshotArea is a new method that allows you to grab an image of the given region of the canvas during the post-render step and have it sent to your defined callback. This is the same as snapshot except you control the area being grabbed, so is more efficient if you only need a smaller area.
    • CanvasRenderer.snapshotPixel is a new method that allows you to grab a single pixel from the game canvas, post-render. It returns the result as a Color object to your specified callback.
    • SceneManager.getScenes is a new method that will return all current Scenes being managed by the Scene Manager. You can optionally return only active scenes and reverse the order in which they are returned in the array.
    • DOM.GetTarget is a new helper function that will return a reference to a DOM Element based on the given string or node.
    • ๐Ÿ”Œ GameObjects.Extern is a new special type of Game Object that allows you to pass rendering off to a 3rd party. When you create an Extern and place it in the display list of a Scene, the renderer will process the list as usual. When it finds an Extern it will flush the current batch, clear down the pipeline and prepare a transform matrix which your render function can take advantage of, if required. The Extern Game Object is used heavily by the Spine Plugin, but can also be used by other libraries such as three.js, allowing them to render directly into a Phaser game.

    โšก๏ธ Updates

    • 0๏ธโƒฃ You can now modify this.physics.world.debugGraphic.defaultStrokeWidth to set the stroke width of any debug drawn body, previously it was always 1 (thanks @samme)
    • ๐Ÿ’… TextStyle.setFont has a new optional argument updateText which will sets if the text should be automatically updated or not (thanks @DotTheGreat)
    • ProcessQueue.destroy now sets the internal toProcess counter to zero.
    • ๐Ÿšš The PathFollower.pathRotationVerticalAdjust property has been removed. It was supposed to flipY a follower when it reversed path direction, but after some testing it appears it has never worked and it's easier to do this using events, so the property and associated config value are removed. The verticalAdjust argument from the setRotateToPath method has been removed as well.
    • ๐Ÿšš The config value preserveDrawingBuffer has been removed as it has never been used by the WebGL Renderer.
    • ๐Ÿ”Œ PluginManager.install returns null if the plugin failed to install in all cases.
    • PluginFile will now install the plugin into the current Scene as long as the start or mapping arguments are provided.
    • MATH_CONST no longer requires or sets the Random Data Generator, this is now done in the Game Config, allowing you to require the math constants without pulling in a whole copy of the RNG with it.
    • The Dynamic Bitmap Text Canvas Renderer was creating a new data object every frame for the callback. It now uses the callbackData object instead, like the WebGL renderer does.
    • WebGLRenderer.setBlendMode has a new optional argument force, which will force the given blend mode to be set, regardless of the current settings.
    • ๐Ÿšš The method DisplayList.sortGameObjects has been removed. It has thrown a runtime error since v3.3.0(!) which no-one even spotted which is a good indication of how little the method was used. The display list is automatically sorted anyway, so if you need to sort a small section of it, just use the standard JavaScript Array sort method (thanks ornyth)
    • ๐Ÿšš The method DisplayList.getTopGameObject has been removed. It has thrown a runtime error since v3.3.0(!) which no-one even spotted which is a good indication of how little the method was used (thanks ornyth)
    • โšก๏ธ WebGLRenderer.setFramebuffer has a new optional boolean argument updateScissor, which will reset the scissor to match the framebuffer size, or clear it.
    • WebAudioSoundManager.onFocus will not try to resume the Audio Context if it's still locked.
    • WebAudioSoundManager.onBlur will not try to suspend the Audio Context if it's still locked.
    • ๐Ÿ”Œ When using ScenePlugin.add, to add a new Scene to the Scene Manager, it didn't allow you to include the optional Scene data object. You can now pass this in the call (thanks @kainage)
    • Graphics.stroke is a new alias for the strokePath method, to keep the calls consistent with the Canvas Rendering Context API.
    • Graphics.fill is a new alias for the fillPath method, to keep the calls consistent with the Canvas Rendering Context API.
    • ๐Ÿ”Œ LoaderPlugin.sceneManager is a new property that is a reference to the global Scene Manager, useful for Plugins.
    • ๐Ÿ‘ Whenever Camera.roundPixels was enabled it would use a bitwise operation to truncate the float (x |= 0) - this has been replaced across all files that used it, with a call to Math.round instead. This gives far better results when zooming cameras both in and out of a Scene, stopping thin gaps appearing between closely packed Game Objects.
    • AnimationManager.create will now return a boolean false if the given key is invalid (i.e. undefined or falsey).
    • โš  AnimationManager.create will no longer raise a console warning if the animation key is already in use. Instead, it will return the animation belonging to that key. A brand new animation will only be created if the key isn't already in use. When this happens, the add event is emitted by the Animation Manager. If no event is emitted, the animation already existed.
    • ArcadePhysics.Body.destroy will now only add itself to the World pendingDestroy list if the world property exists. This prevents Cannot read property 'pendingDestroy' of undefined errors if you try to delete a physics body in a callback and then immediately change Scene (which tells the physics work to also delete all bodies)
    • ๐Ÿšš The Animation Component restart method has had is sole key argument removed. Previously, you had to pass in the key of the animation you wished to reverse, but now you can just call the method directly, and as long as there is an animation playing, it will automatically start playing in reverse, without the nee for a key (the way it should have been originally)
    • Animation.play and playReverse will now accept either a string-based key of the animation to play (like before), or you can pass in an Animation instance, and it will play that animation.
    • CanvasTexture.clear now has 4 new optional arguments: x, y, width, height which allow you to define the region of the texture to be cleared. If not provided it will clear the whole texture, which is the same behavior as before.
    • ๐ŸŽ EarCut, the polygon triangulation library used by the Graphics and WebGL classes, has been upgraded from 2.1.1 to 2.1.4. 2.1.2 fixed a few race conditions where bad input would cause an error. 2.1.3 improved performance for bigger inputs (5-12%) and 2.1.4 fixed a race condition that could lead to a freeze on degenerate input.
    • TextureTintPipeline.batchQuad and batchTri have two new optional arguments texture and unit which are used to re-set the batch texture should the method cause a batch flush.
    • TextureTintPipeline.requireTextureBatch is a new internal method that helps speed-up the creation of texture batches. It is used in conjunction with setTexture2D and pushBatch.
    • ๐Ÿ”จ TextureTintPipeline.flush and TextureTintPipeline.pushBatch have been optimized to handle zero based texture units as priority. They've also been refactored to avoid creation of empty texture batches.
    • The WebGLRenderer.setTexture2D method has a new optional argument flush which controls if the pipeline is flushed if the given texture is new, or not. This is used internally to skip flushing during an existing flush.
    • The Tilemap Layer width and height properties are now based on the tilemap tile sizes multiplied by the layer dimensions. This corrects an issue with layer sizes being wrong if you called setBaseTileSize on a Map.
    • The WebGLRenderer will now clear the framebuffer at the start of every render.
    • 0๏ธโƒฃ WebGLRenderer.setScissor now has a new optional argument drawingBufferHeight which allows you to specify the drawing buffer height, rather than use the renderers default value.
    • 0๏ธโƒฃ WebGLRenderer.pushScissor now has a new optional argument drawingBufferHeight which allows you to specify the drawing buffer height, rather than use the renderers default value.
    • โช WebGLRenderer.preRender now calls gl.clearColor in order to restore the background clear color in case something, like a Render Texture, has changed it.
    • โšก๏ธ Map.set will now update an existing value if you provide it with a key that already exists within the Map. Previously, if you tried to set the value of a key that existed it would be skipped.
    • MatterSprite would set its type property to be Image. It now sets it to be Sprite as it should do.
    • โšก๏ธ Matter.TileBody.setFromTileCollision no longer checks if the shape is concave or convex before modifying the vertices, as the update to the Matter.js lib in 3.12 stopped this from working with Tiled collision shapes.
    • The Scene transitionstart event is now dispatched by the Target Scene of a transition, regardless if the Scene has a create method or not. Previously, it was only dispatched if the Scene had a create method.
    • ๐Ÿ’ป The Loader will now allow an XHR status of 0 as success too. Normally only status 200 would be accepted as success, but 0 is returned when a file is loaded from the local filesystem (file://). This happens, for example, when opening the index.html of a game in a browser directly, or when using Cordova on iOS. Fix #3464 (thanks @Ithamar)
    • Tween.restart now returns the Tween instance (thanks @rexrainbow)
    • Tween.play now returns the Tween instance (thanks @rexrainbow)
    • ๐Ÿ‘€ Tween.seek now returns the Tween instance (thanks @rexrainbow)
    • Tween.complete now returns the Tween instance (thanks @rexrainbow)
    • Tween.stop now returns the Tween instance (thanks @rexrainbow)
    • List.sort now has an optional parameter handler which allows you to provide your own sort handling function (thanks @jcyuan)
    • Container.sort now has an optional parameter handler which allows you to provide your own sort handling function (thanks @jcyuan)
    • The WebGLRenderer method canvasToTexture will now only set the filter to be NEAREST if antialias is disabled in the game config (i.e. when running in pixelArt mode). This means that Text objects, and other Canvas backed textures, now render with anti-aliasing if everything else does. You can disable this on a per-object basis by calling texture.setFilter(1) on them.
    • ๐Ÿšš CanvasRenderer.snapshotCallback, snapshotType and snapshotEncoder have all been removed as they are no longer required.
    • ๐Ÿ”ง CanvasRenderer.snapshotState is a new object that contains the snapshot configuration data, the same as the WebGL Renderer.
    • ๐Ÿ”ง The signature of the WebGLSnapshot function has changed. It now takes a Snapshot Configuration object as the second parameter.
    • ๐Ÿ”ง The signature of the CanvasSnapshot function has changed. It now takes a Snapshot Configuration object as the second parameter.
    • A Tween Timeline will now set it's internal destroy state before calling either the onComplete callback or sending the COMPLETE event. This means you can now call methods that will change the state of the Timeline, such as play, during the callback handlers, where-as before doing this would have had the internal state changed immediately, preventing it (thanks Lucas Knight)
    • ๐Ÿ’… The AddToDOM method has had the overflowHidden argument removed. The DOM element the canvas is inserted into no longer has overflow: hidden applied to its style. If you wish to have this, please add it directly via CSS.

    ๐Ÿ› Bug Fixes

    • The Rectangle Shape object wouldn't render if it didn't have a stroke, or any other objects on the display list (thanks mliko)
    • ๐Ÿ’… When using a font string instead of setting fontFamily, fontSize and fontStyle in either Text.setStyle or setFont, the style properties wouldn't get set. This isn't a problem while creating the text object, only if modifying it later (thanks @DotTheGreat)
    • ๐Ÿ’… Text.toJSON wasn't saving the font style when using the "font" shorthand to create it. It now saves it correctly. Fix #4141 (thanks @divillysausages)
    • Disabling camera bounds and then moving the camera to an area in a Tilemap that did not have any tile information would throw an Uncaught Reference error as it tried to access tiles that did not exist (thanks @Siyalatas)
    • ๐Ÿ›  Fixed an issue where Sprite Sheets being extracted from a texture atlas would fail if the sheet was either just a single column or single row of sprites. Fix #4096 (thanks @Cirras)
    • ๐Ÿ”ง If you created an Arcade Physics Group without passing a configuration object, and passing an array of non-standard children, it would throw a classType runtime error. It now creates a default config object correctly (thanks @pierpo)
    • The Camera.cull method has been restructured so it now calculates if a Game Object is correctly in view or not before culling it. Although not used internally, if you need to cull objects for a camera, you can now safely use this method. Fix #4092 (thanks @Cirras)
    • ๐Ÿ“œ The Tiled Parser would ignore animated tile data if it was in the new Tiled 1.2 format. This is now accounted for, as well as 1.0 (thanks @nkholski)
    • Array.Matrix.ReverseRows was actually reversing the columns, but now reverses the rows.
    • Array.Matrix.ReverseColumns was actually reversing the rows, but now reverses the columns.
    • UnityAtlas now sets the correct file type key if using a config file object.
    • Starting with version 3.13 in the Canvas Renderer, it was possible for long-running scripts to start to get bogged-down in fillRect calls if the game had a background color set. The context is now saved properly to avoid this. Fix #4056 (thanks @Aveyder)
    • 0๏ธโƒฃ Render Textures created larger than the size of the default canvas would be automatically clipped when drawn to in WebGL. They now reset the gl scissor and drawing height property in order to draw to their full size, regardless of the canvas size. Fix #4139 (thanks @chaoyang805 @iamchristopher)
    • The cameraFilter property of a Game Object will now allow full bitmasks to be set (a value of -1), instead of just those > 0 (thanks @stuartkeith)
    • The PathFollower.startFollow method now properly uses the startAt argument to the method, so you can start a follower off at any point along the path. Fix #3688 (thanks @DannyT @diteix)
    • Static Circular Arcade Physics Bodies now render as circles in the debug display instead of showing their rectangle bounds (thanks @maikthomas)
    • Changing the mute flag on an HTML5AudioSound instance, via the mute setter, now works as it does via the Sound Manager (thanks @Waclaw-I @neon-dev)
    • Changing the volume on an HTML5AudioSound instance, via the volume setter, now works as it does via the Sound Manager (thanks @Waclaw-I)
    • The Dynamic Tilemap Layer WebGL renderer was drawing tiles at the incorrect position if the layer was scaled. Fix #4104 (thanks @the-realest-stu)
    • Tile.tileset now returns the specific Tileset associated with the tile rather than an array of them. Fix #4095 (thanks @quadrupleslap)
    • ๐Ÿ‘ Tile.getCollisionGroup wouldn't return the correct Group after the change to support multiple Tilesets. It now returns the group properly (thanks @jbpuryear)
    • ๐Ÿ‘ Tile.getTileData wouldn't return the correct data after the change to support multiple Tilesets. It now returns the tile data properly (thanks @jbpuryear)
    • ๐Ÿšš The GetTileAt and RemoveTileAt components would error with "Cannot read property 'index' of undefined" if the tile was undefined rather than null. It now handles both cases (thanks @WaSa42)
    • โšก๏ธ Changing TileSprite.width or TileSprite.height will now flag the texture as dirty and call updateDisplayOrigin, allowing you to resize TileSprites dynamically in both Canvas and WebGL.
    • ๐Ÿ›  RandomDataGenerator.shuffle has been fixed to use the proper modifier in the calculation allowing for a more even distribution (thanks wayfinder)
    • ๐Ÿ’ป The Particle Emitter was not recycling dead particles correctly so it was creating new objects every time it emitted (the old particles were then left to the browsers gc to clear up). This has now been recoded so the emitter will properly keep track of dead particles and re-use them (thanks @Waclaw-I for the initial PR)
    • ๐Ÿšš ParticleEmitter.indexSortCallback has been removed as it's no longer required.
    • ๐Ÿšš Particle.index has been removed as it's no longer required. Particles don't need to keep track of their index any more.
    • โšก๏ธ The Particle Emitter no longer needs to call the StableSort.inplace during its preUpdate, saving cpu.
    • Particle.resetPosition is a new method that is called when a particle dies preparing it for firing again in the future.
    • โช The Canvas SetTransform method would save the context state, but it wasn't restored at the end in the following Game Objects: Dynamic Bitmap Text, Graphics, Arc, Curve, Ellipse, Grid, IsoBox, IsoTriangle, Line, Polygon, Rectangle, Star and Triangle. These now all restore the context, meaning if you're using non-canvas sized cameras in Canvas mode, it will now render beyond just the first custom camera.
    • ๐Ÿšš Utils.Array.MoveUp wouldn't let you move an array element to the top-most index in the array. This also impacted Container.moveUp.
    • The Texture Tint Pipeline had a logic error that would cause every 2001st quad to either be invisible, or pick-up the texture of the 2000th quad by mistake. The batchQuad and batchTri methods how handle re-assigning the batch texture if they cause a batch flush as part of their process.
    • Rotating Sprites that used a Normal Map wouldn't rotate the normal map with it causing the lighting effects to become irregular. The normal map vectors are now rotated correctly (thanks @sercant for the PR and @fazzamatazz and @ysraelJMM for the report)
    • Changing scaleX or scaleY on a MatterImage or MatterSprite would cause the body scale to become distorted as the setters didn't use the correct factor when resetting the initial scale. Fix #4206 (thanks @YannCaron)
    • โšก๏ธ StaticBody.reset in Arcade Physics would ignore the x and y values given to it. If given, they're now used to reset the parent Game Object before the body is updated. Fix #4224 (thanks @samme)
    • Static Tilemap Layers wouldn't render correctly if the layer used a tileset with a different size to the base map data (set via setBaseTileSize). They now render correctly in WebGL and Canvas regardless of the base tile size.
    • When using RenderTexture.fill, the alpha argument would be ignored in Canvas mode. It's now used when filling the RenderTexture.
    • ๐Ÿ›  Fixed an issue in WebGLRenderer.setScissor where it was possible to try and compare the scissor size to a non-current scissor if called outside of the render loop (i.e. from RenderTexture.fill) (thanks @hackhat)
    • RenderTexture.fill in WebGL would use gl.clear and a clear color to try and fill the Render Texture. This only worked for full-canvas sized RenderTextures that didn't have a camera zoom applied. It has now been swapped to use the drawFillRect method of the Texture Tint Pipeline, allowing it to work properly regardless of camera zoom or size.
    • Container.getFirst was using an incorrect Array Utils function GetFirstElement when it should have been using GetFirst. It now uses the correct function. Fix #4244 (thanks @miran248)
    • List.getFirst was using an incorrect Array Utils function GetFirstElement when it should have been using GetFirst. It now uses the correct function. Fix #4244 (thanks @miran248)
    • ๐Ÿ›  Fixed an issue where changing the viewport or size of a Camera belonging to a RenderTexture wouldn't impact the rendering and objects will still render outside of the viewport range. It's now converted to a proper gl scissor rect by the renderer, meaning you can limit the area rendered to by adjusting the internal Render Texture cameras viewport. Fix #4243 (thanks @hackhat)
    • CanvasTexture.destroy is a new method that specifically handles the destruction of the CanvasTexture and all of its associated typed arrays. This prevents a memory leak when creating and destroying lots of RenderTextures (which are CanvasTexture backed). Fix #4239 (thanks @sjb933)
    • ๐Ÿšš The Alpha, Flip and Origin components have been removed from the Mesh Game Object (and by extension, Quad as well) as they are not used in the renderer and should be manipulated via the Mesh properties. Fix #4188 (thanks @enriqueto)
    • ๐Ÿšš The processDomCallbacks method in the Input Manager wasn't correctly clearing the once arrays. Responsibility for this has now been passed to the queue methods queueTouchStart, queueTouchMove, queueTouchEnd, queueMouseDown, queueMouseMove and queueMouseUp. Fix #4257 (thanks @iArePJ)
    • โšก๏ธ Arcade Physics now manages when postUpdate should be applied better, stopping it from gaining a zero delta during a further check in the same frame. This fixes various issues, including the mass collision test demo. Fix #4154 (thanks @samme)
    • Arcade Physics could trigger a collide event on a Body even if it performing an overlap check, if the onCollide property was true (thanks @samme)
    • TileSprites no longer cause a crash when using the Headless mode renderer. Fix #4297 (thanks @clesquir)
    • The WebGLRenderer will now apply a transparent background if transparent = true in the game config (thanks @gomachan7)
    • List.sort was missing the scope required for the sort handler, this is now correctly provided internally. Fix #4241 (thanks @jcyuan)
    • Container.sort was missing the scope required for the sort handler, this is now correctly provided internally. Fix #4241 (thanks @jcyuan)
    • DataManager.pop would emit the DataManager instance, instead of the parent, as the first event argument. It now emits the parent as it should do. Fix #4186 (thanks @gadelan)
    • The GetValue function wasn't checking for the existance of '.' in the config property name correctly, causing the branch to always be taken (thanks @kyranet)
    • Safari had permission problems playing HTML5 Audio files on Mac OS. Due to the changes in the input event system audio now plays properly based on user interactions. You still can't play it automatically, though, it will always require a user gesture to begin. Fix #4217 (thanks @increpare)

    Examples and TypeScript

    ๐Ÿ‘ Thanks to the following for helping with the Phaser 3 Examples and TypeScript definitions, either by reporting errors, or even better, fixing them:

    @guilhermehto @samvieten @darkwebdev @RoryO @snowbillr @slothyrulez @jcyuan @jestarray @CzBiX

    Phaser Doc Jam

    ๐Ÿ“š The Phaser Doc Jam was a community-backed effort to try and get the Phaser 3 API documentation to 100% coverage. The Doc Jam is now over and I offer my thanks to the following who helped with docs in this release:

    @16patsle - @gurungrahul2 - @icbat - @samme - @telinc1 - anandu pavanan - blackhawx - candelibas - Diego Romero - doronlinder - Elliott Wallace - eric - Georges Gabereau - Haobo Zhang - henriacle - jak6jak - Jake Jensen - James Van Roose - JamesSkemp - joelahoover - Joey - madclaws - marc136 - Mihail Ilinov - naum303 - NicolasRoehm - nuane - rejacobson - Robert Kowalski - rodri042 - rootasjey - sawamara - scottwestover - sir13tommy - stetso - therealsamf - Tigran - willblackmore - zenwaichi

    ๐Ÿ“„ Also, the following helped with the docs outside of the Doc Jam:

    @bryanwood @jestarray @matosummer @tfelix @imilo @BigZaphod @OmarShehata @16patsle @jcyuan @iam13islucky @FractalBobz Endre

  • v3.16.0-rc3 Changes

    January 31, 2019

    ๐Ÿ›  The final Scale Manager functionality is included, lots of JSDoc fixes (so the TypeScript defs now generate again) and masses of other small tweaks.

  • v3.16.0-rc2 Changes

    January 30, 2019

    ๐Ÿš€ The second release candidate fixes issues with the new input system across multiple Scenes, as well as fixing keyboard input outside of the legacy handler.

    ๐Ÿ›  It also puts the Externs back as first class Game Objects and fixes numerous other issues which can be found in the Change Log.

  • v3.16.0-rc1 Changes

    January 25, 2019

    โšก๏ธ Facebook Instant Games Updates and Fixes

    • โž• Added the Leaderboard.getConnectedScores method, to get a list of scores from player connected entries.
    • โšก๏ธ The loadPlayerPhoto function in the Instant Games plugin now listens for the updated Loader event correctly, causing the photocomplete event to fire properly.
    • ๐Ÿ“š Leaderboard.setScore now emits the LeaderboardScore object with the setscore event, as the documentation said it did.
    • Leaderboard.getPlayerScore now only populates the playerScore property if the entry isn't null.
    • If the setScore or getPlayerScore calls fail, it will return null as the score instance, instead of causing a run-time error.
    • You can now pass an object or a string to setScore and objects will be automatically stringified.
    • The preloadAds method will now only create an AdInstance object if the interstitial loadSync promise resolves.
    • The preloadVideoAds method will now only create an AdInstance object if the interstitial loadSync promise resolves.
    • The preloadAds method will now emit the adsnofill event, if there are no ads in the inventory to load.
    • The preloadVideoAds method will now emit the adsnofill event, if there are no ads in the inventory to load.
    • The showAd method will now emit the adsnotloaded event, if there are no ads loaded matching the given Placement ID.
    • The showVideo method will now emit the adsnotloaded event, if there are no ads loaded matching the given Placement ID.
    • ๐Ÿ‘‰ Showing an ad will emit the adfinished event when the ad is closed, previously this event was called showad but the new name better reflects what has happened.
    • ๐Ÿ”Œ The Facebook Plugin is now available in the Phaser.Scene class template under the facebook property (thanks @bryanwood)
    • ๐Ÿ›  Fixed the Leaderboard.getScores method to now take the arguments into account. Fix #4271 (thanks @Oramy)
    • ๐Ÿ›  Fixed an API validation error in the chooseContext method. Fix #4248 (thanks @yadurajiv)

    Important Changes to the Input System

    In Phaser 3.15 and earlier the Input system worked using an event queue. All native DOM input events, such as from the Mouse, Touch or Keyboard, were picked up by event handlers and stored in a queue within the Input Manager. This queue was then processed during the next game step, all the events were dealt with and then it was cleared, ready to receive more events. As they were processed, the internal Phaser events such as pointerdown or keyup were dispatched to your game code.

    This worked fine in that you were able to guarantee exactly when the events would arrive, because it was always at the same time in the game step. However, it had the side effect of you not being able to do things like open external browser windows, or go into Full Screen mode, during your event handlers - because they weren't "real" events, so didn't pass the browser security checks. To this end, methods like addUpCallback were added to try and provide this support (although it was never possible for keyboard events).

    ๐Ÿ In 3.16 this has changed. The DOM Events now trigger the respective internal events immediately, in the same invocation. So if you click on the canvas, the pointerdown event you receive in your game is still part of the 'native' event handler, so you're now free to do things like go into full screen mode, or open external windows, without any browser warnings or work-arounds.

    โšก๏ธ It does, however, mean that the point at which these handlers are called is no longer always consistent, and is no longer bound to the speed of the Request Animation Frame update. We've tested as much as possible, and so far, things carry on working as before. We've noticed a slight increase in responsiveness, due to the removal of the fractional delay in processing the events, which feels good. However, if for whatever reason this change has broken your game then you're able to easily switch back to the previous version. In your Game Config, create an input object and give it the property queue: true. This will tell Phaser to use the legacy event queue system.

    Please note that we will remove this legacy system in the near future. So, please try and adapt your games to use the new system. If you've found an edge-case where something breaks because of it, please report it so we can look into it.

    ๐Ÿ—„ As a result of this change, the following are now deprecated:

    • ๐Ÿ”Œ InputPlugin.addUpCallback method.
    • ๐Ÿ”Œ InputPlugin.addDownCallback method.
    • ๐Ÿšš InputPlugin.addMoveCallback method.
    • InputManager.queue property.
    • InputManager.domCallbacks property.
    • InputManager._hasUpCallback property.
    • InputManager._hasDownCallback property.
    • ๐Ÿšš InputManager._hasMoveCallback property.
    • InputManager.processDomCallbacks method.
    • InputManager.addUpCallback method.
    • InputManager.addDownCallback method.
    • ๐Ÿšš InputManager.addMoveCallback method.

    keydown and keyup changes

    Due to unification across the event system, the keydown_ and keyup_ dynamic event strings have changed.

    • In all cases the keydown_KEY event name has changed to keydown-KEY. Note the change from an underscore to a hyphen.
    • In all cases the keyup_KEY event name has changed to keyup-KEY. Note the change from an underscore to a hyphen.

    โšก๏ธ You should update your game code accordingly.

    Keyboard Input - New Features

    ๐Ÿ”Œ The specificity of the Keyboard events has been changed to allow you more control over event handling. Previously, the Keyboard Plugin would emit the global keydown-CODE event first (where CODE was a keycode string, like keydown-A), then it would emit the global keydown event. In previous versions, Key objects, created via this.input.keyboard.addKey(), didn't emit events.

    The Key class now extends EventEmitter and emits two new events directly: down and up. This means you can listen for an event from a Key you've created, i.e.: yourKey.on('up', handler).

    ๐Ÿ”Œ The order has also now changed. If it exists, the Key object will dispatch its down event first. Then the Keyboard Plugin will dispatch keydown_CODE and finally the least specific of them all, keydown will be dispatched.

    ๐Ÿ”Œ You also now have the ability to cancel this at any stage either on a local or global level. All event handlers are sent an event object which you can call event.stopImmediatePropagation() on. This will immediately stop any further listeners from being invoked in the current Scene. Therefore, if you call stopImmediatePropagation() in the Key.on handler, then the Keyboard Plugin will not emit either the keydown-CODE or keydown global events. You can also call stopImmediatePropagation() during the keydown-CODE handler, to stop it reaching the global keydown handler. As keydown is last, calling it there has no effect.

    There is also the stopPropagation() function. This works in the same way as stopImmediatePropagation but instead of being local, it works across all of the Scenes in your game. For example, if you had 3 active Scenes (A, B and C, with A at the top of the Scene list), all listening for the same key, calling stopPropagation() in Scene A would stop the event from reaching any handlers in Scenes B or C. Remember that events flow down the Scene list from top to bottom. So, the top-most rendering Scene in the Scene list has priority over any Scene below it.

    All the above also works for keyup events.

    ๐Ÿ†• New in 3.16 is the ability to receive a global keydown or keyup event from any key on the keyboard. Previously, it would only emit the event if it came from one of the keys listed in the KeyCodes file. Now, those global events will fire for any key, regardless of location.

    Keyboard Captures

    0๏ธโƒฃ Key capturing is the way in which you stop a keyboard DOM event from activating anything else in the browser by calling preventDefault on it. For example, in tall web pages, pressing the SPACE BAR causes the page to scroll down. Obviously, if this is also the fire or jump button in your game, you don't want this to happen. So the key needs to be 'captured' to prevent it. Equally, you may wish to also capture the arrow keys, for similar reasons. Key capturing is done on a global level. If you set-up the capture of a key in one Scene, it will be captured globally across the whole game.

    ๐Ÿ”Œ In 3.16 you now do this using the new KeyboardPlugin.addCapture method. This takes keycodes as its argument. You can either pass in a single key code (i.e. 32 for the Space Bar), an array of key codes, or a comma-delimited string - in which case the string is parsed and each code it can work out is captured.

    ๐Ÿ’… To remove a capture you can use the KeyboardPlugin.removeCapture method, which takes the same style arguments as adding captures. To clear all captures call KeyboardPlugin.clearCaptures. Again, remember that these actions are global.

    ๐Ÿ”Œ You can also temporarily enable and disable capturing using KeyboardPlugin.enableGlobalCapture and KeyboardPlugin.disableGlobalCapture. This means if you set-up a bunch of key captures, but then need to disable them all for a while (perhaps you swap focus to a DOM text field), you can call disableGlobalCapture to do this, and when finished in the DOM you can enable captures again with enableGlobalCapture, without having to clear and re-create them all.

    0๏ธโƒฃ Default captures can be defined in the Game Config in the input.keyboard.captures object. The captures are actually stored in the KeyboardManager class. The KeyboardPlugin is just a proxy to methods in the Keyboard Manager, but is how you should interface with it.

    • 0๏ธโƒฃ KeyboardPlugin.addCapture is a new method that allows you to define a set of keycodes to have the default browser behaviors disabled on.
    • ๐Ÿšš KeyboardPlugin.removeCapture is a new method that removes specific previously set key captures.
    • ๐Ÿšš KeyboardPlugin.clearCaptures is a new method that removes all key captures.
    • ๐Ÿ”Œ KeyboardPlugin.getCaptures is a new method that returns an array of all current key captures.
    • ๐Ÿ”Œ KeyboardPlugin.enableGlobalCapture is a new method that enables any key captures that have been created.
    • ๐Ÿ”Œ KeyboardPlugin.disableGlobalCapture is a new method that disables any key captures that have been created, without removing them from the captures list.
    • 0๏ธโƒฃ KeyboardPlugin.addKey has a new boolean argument enableCapture, which is true by default, that will add a key capture for the Key being created.
    • 0๏ธโƒฃ KeyboardPlugin.addKeys has a new boolean argument enableCapture, which is true by default, that will add a key capture for any Key created by the method.

    โšก๏ธ Other Keyboard Updates and Fixes

    • ๐Ÿ”Œ There is a new class called KeyboardManager. This class is created by the global Input Manager if keyboard access has been enabled in the Game config. It's responsible for handling all browser keyboard events. Previously, the KeyboardPlugin did this which meant that every Scene that had its own Keyboard Plugin was binding more native keyboard events. This was causing problems with parallel Scenes when needing to capture keys. the KeyboardPlugin class still exists, and is still the main point of interface when you call this.input.keyboard in a Scene, but DOM event handling responsibility has been taken away from it. This means there's now only
      one set of bindings ever created, which makes things a lot cleaner.
    • 0๏ธโƒฃ There is a new Game and Scene Config setting input.keyboard.capture which is an array of KeyCodes that the Keyboard Plugin will capture all non-modified key events on. By default it is empty. You can populate it in the config, or use the new capture methods.
    • 0๏ธโƒฃ The Keyboard Manager will now call preventDefault only on non-modified key presses, stopping the keyboard event from hitting the browser. Previously, capturing the R key, for example, would block a CTRL+R page reload, but it now ignores it because of the key modifier.
    • ๐Ÿ’ป If the browser Window loses focus, either from switching to another app, or another tab, all active Keys will be reset. This prevents issues with keys still reporting as being held down after leaving the game and returning to it again. Fix #4134 (thanks @Simplonium)
    • Key.emitOnRepeat is a new boolean property that controls if the Key will continuously emit a down event while being held down (true), or emit the event just once, on first press, and then skip future events (false).
    • Key.setEmitOnRepeat is a new chainable method for setting the emitOnRepeat property.
    • 0๏ธโƒฃ The KeyboardPlugin.addKeys method has a new optional boolean emitOnRepeat which sets that property on all Key objects it creates as part of the call. It defaults to false.
    • 0๏ธโƒฃ The KeyboardPlugin.addKey method has a new optional boolean emitOnRepeat which sets that property on the Key object it creates. It defaults to false.
    • The Key class now extends EventEmitter and emits two events directly: down and up. This means you can listen for an event from a Key you've created, i.e.: yourKey.on('up', handler).
    • The following Key Codes have been added, which include some missing alphabet letters in Persian and Arabic: SEMICOLON_FIREFOX, COLON, COMMA_FIREFOX_WINDOWS, COMMA_FIREFOX, BRACKET_RIGHT_FIREFOX and BRACKET_LEFT_FIREFOX (thanks @wmateam)
    • Key.onDown is a new method that handles the Key being pressed down, including down repeats.
    • ๐Ÿš€ Key.onUp is a new method that handles the Key being released.
    • ๐Ÿ”Œ Key.destroy is a new method that handles Key instance destruction. It is called automatically in KeyboardPlugin.destroy.
    • ๐Ÿšš The Key.preventDefault property has been removed. This is now handled by the global keyboard capture methods.
    • ๐Ÿ Key.metaKey is a new boolean property which indicates if the Meta Key was held down when the Key was pressed. On a Mac the Meta Key is Command. On a Windows keyboard, it's the Windows key.
    • InputManager.keyboard is a new property that instantiates the global Keyboard Manager, if enabled in the game config.
    • 0๏ธโƒฃ The KeyboardPlugin.addKey method has a new boolean property enableCapture which automatically prevents default on the Key being created.
    • 0๏ธโƒฃ The KeyboardPlugin.addKeys method has a new boolean property enableCapture which automatically prevents default on Keys being created.
    • ๐Ÿšš Phaser.Input.Keyboard.ProcessKeyDown has been removed as it's no longer required, Key.onDown handles it instead.
    • ๐Ÿšš Phaser.Input.Keyboard.ProcessKeyUp has been removed as it's no longer required, Key.onUp handles it instead.
    • 0๏ธโƒฃ The Keyboard Manager has a property called captures which is an array of keycodes, as populated by the Game Config. Any key code in the array will have preventDefault called on it if pressed.
    • ๐Ÿ”Œ KeyboardPlugin.manager is a new property that references the Keyboard Manager and is used internally.
    • ๐Ÿšš KeyboardPlugin.target has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.queue has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.onKeyHandler has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.startListeners has been removed as it's no longer used by the class.
    • ๐Ÿšš KeyboardPlugin.stopListeners has been removed as it's no longer used by the class.

    โšก๏ธ Mouse and Touch Input - New Features, Updates and Fixes

    • โšก๏ธ The Mouse Manager class has been updated to remove some commented out code and refine the startListeners method.
    • When enabling a Game Object for input it will now use the width and height properties of the Game Object first, falling back to the frame size if not found. This stops a bug when enabling BitmapText objects for input and it using the font texture as the hit area size, rather than the text itself.
    • ๐Ÿ“ฆ Pointer.smoothFactor is a float-value that allows you to automatically apply smoothing to the Pointer position as it moves. This is ideal when you want something smoothly tracking a pointer in a game, or are need a smooth drawing motion for an art package. The default value is zero, meaning disabled. Set to a small number, such as 0.2, to enable.
    • 0๏ธโƒฃ Config.inputSmoothFactor is a new property that allows you to set the smoothing factor for all Pointers the game creates. The default value is zero, which is disabled. Set in the game config as input: { smoothFactor: value }.
    • ๐Ÿšš InputManager.transformPointer has a new boolean argument wasMove, which controls if the pointer is being transformed after a move or up/down event.
    • โšก๏ธ Pointer.velocity is a new Vector2 that contains the velocity of the Pointer, based on the current and previous positions. The velocity is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The velocity is updated based on Pointer movement and doesn't require a button to be pressed first.
    • โšก๏ธ Pointer.angle is a new property that contains the angle of the Pointer, in radians, based on the current and previous positions. The angle is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The angle is updated based on Pointer movement and doesn't require a button to be pressed first.
    • โšก๏ธ Pointer.distance is a new property that contains the distance of the Pointer, in radians, based on the current and previous positions. The distance is smoothed out each frame according to the Pointer.motionFactor property. This is done for more accurate gesture recognition. The distance is updated based on Pointer movement and doesn't require a button to be pressed first.
    • 0๏ธโƒฃ Pointer.motionFactor is a new property that controls how much smoothing to apply to the Pointer positions each frame. This value is passed to the Smooth Step Interpolation that is used to calculate the velocity, angle and distance of the Pointer. It's applied every frame until the midPoint reaches the current position of the Pointer. The default value is 0.2.
    • โšก๏ธ The Input Plugin was emitting a preUpdate event, with the capital U, instead of preupdate. This has now been corrected. Fix #4185 (thanks @gadelan)
    • โšก๏ธ Pointer.updateMotion is a new method that is called automatically, each step, by the Input Manager. It's responsible for calculating the Pointer velocity, angle and distance properties.
    • โšก๏ธ Pointer.time is a new property that holds the time the Pointer was last updated by the Game step.
    • โšก๏ธ Pointer.getDistance has been updated. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • Pointer.getDistanceX is a new method that will return the horizontal distance between the Pointer's previous and current coordinates. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • Pointer.getDistanceY is a new method that will return the horizontal distance between the Pointer's previous and current coordinates. If called while a button is being held down, it will return the distance between the Pointer's current position and it's down position. If called when a Pointer doesn't have a button down, it will return the historic distance between the up and down positions.
    • ๐Ÿš€ Pointer.getDuration is a new method that will return the duration the Pointer was held down for. If the Pointer has a button pressed down at the time this method is called, it will return the duration since the Pointer's button was pressed down. If no button is held down, it will return the last recorded duration, based on the time the Pointer button was released.
    • ๐Ÿš€ Pointer.getAngle is a new method that will return the angle between the Pointer coordinates. If the Pointer has a button pressed down at the time this method is called, it will return the angle between the Pointer's downX and downY values and the current position. If no button is held down, it will return the last recorded angle, based on where the Pointer was when the button was released.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mousedown listener for the game canvas and then call window.focus when detected (assuming the game config autoFocus property was true). Responsibility for this has now been moved to the Mouse Manager onMouseDown handler.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mouseout listener for the game canvas and then set game.isOver when detected. Responsibility for this has now been moved to the Mouse Manager, which sets the new Input Manager isOver property directly.
    • ๐Ÿšš In previous versions, the VisibilityHandler would create a mouseover listener for the game canvas and then set game.isOver when detected. Responsibility for this has now been moved to the Mouse Manager, which sets the new Input Manager isOver property directly.
    • ๐Ÿšš The Phaser.Game.isOver property has been moved. You can now find it in the Input Manager and it's also accessible via the Input Plugin, which means you can do this.input.isOver from within a Scene. This makes more sense as it's input related and not a game level property.
    • ๐Ÿšš The Input Plugin has a new event you can listen to: gameover, which is triggered whenever the mouse or a pointer is moved over the Game canvas. Listen to it with this.input.on('gameover') from within a Scene.
    • ๐Ÿ”Œ The Input Plugin has a new event you can listen to: gameout, which is triggered whenever the mouse or a pointer leaves the Game canvas. Listen to it with this.input.on('gameout') from within a Scene.
    • ๐Ÿ”Œ The Game used to emit a mouseover event when the mouse entered the game canvas. This is no longer emitted by the Game itself and can instead be listened for using the new Input Plugin event gameover.
    • ๐Ÿ”Œ The Game used to emit a mouseout event when the mouse left the game canvas. This is no longer emitted by the Game itself and can instead be listened for using the new Input Plugin event gameout.
    • ๐Ÿš€ If the window object exists (which it will in normal browser environments) new mouseup and touchend event listeners are bound to it and trigger the normal mouseup or touchend events within the internal input system. This means you will now get a pointerup event from the Input Plugin even if the pointer is released outside of the game canvas. Pointers will also no longer think they are still 'down' if released outside the canvas and then moved inside again in their new state.
    • The window will now have focus called on it by the Touch Manager, as well as the Mouse Manager, if the autoFocus game config property is enabled.
    • ๐Ÿ”Œ The Input Plugin has a new event you can listen to: pointerdownoutside, which is triggered whenever the mouse or a pointer is pressed down while outside of the Game canvas. Listen to it with this.input.on('pointerdownoutside') from within a Scene.
    • ๐Ÿš€ The Input Plugin has a new event you can listen to: pointerupoutside, which is triggered whenever the mouse or a pointer is released while outside of the Game canvas. Listen to it with this.input.on('pointerupoutside') from within a Scene.
    • Pointer.downElement is a new property that holds the target of the DOM Event that triggered when the Pointer was pressed down. If this is within the game, this will be the game canvas element.
    • ๐Ÿš€ Pointer.upElement is a new property that holds the target of the DOM Event that triggered when the Pointer was released. If this is within the game, this will be the game canvas element.
    • ๐Ÿšš The Pointer.dragState property has been removed. This is no longer used internally as it has to be tracked per Scene, not on a global level.
    • ๐Ÿ”Œ InputPlugin.setDragState is a new internal method that sets the drag state for the given Pointer.
    • ๐Ÿ”Œ InputPlugin.getDragState is a new internal method that gets the drag state for the given Pointer.
    • Draggable Game Objects would not work if you had multiple Scenes running in parallel, with draggable objects in both of them. Only the top-most Scene would work fully. Items in the bottom Scene would never finish their drag cycle, causing them to get stuck. Fix #4249 #4278 (thanks @probt @iArePJ)
    • Pointer.leftButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.rightButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.middleButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.backButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • Pointer.forwardButtonDown will now return an actual boolean, rather than the result of the bitwise op (which still evaluated as a boolean, but this is cleaner).
    • โšก๏ธ Pointer.up, Pointer.move and Pointer.down now use in to check for the existance of the buttons property on the event, causing it to be set even if equal to zero, which it is when there are no buttons down. This also fixes an issue where the buttons didn't update during a move event (thanks @SonnyCampbell @rexrainbow)

    ๐Ÿ”„ Changes as a result of the new Scale Manager

    • If you set the Game Config property zoom to be > 1 then it will automatically enable pixelArt mode, unless you set pixelArt: false in the config.
    • ๐ŸŽ There is a new property in the Game Config called autoRound, which controls if the canvas size and style sizes are passed through Math.floor or not. On some devices this can help with performance and anti-aliasing. The default is false (turned off).
    • ๐Ÿšš The Game Config property autoResize has been removed as it's now redundant.
    • โšก๏ธ The WebGL and Canvas Renderers no longer change the Canvas size in their resize methods. They just update internal properties.
    • The WebGL and Canvas Renderers now read the width, height and resolution values from the Scale Manager, not the Game Config.
    • ๐Ÿšš CameraManager.baseScale property has been removed as it's no longer used anywhere.
    • The BaseCamera and Camera preRender methods now only take a resolution argument and use it internally for their transforms.
    • InputManager.scaleManager is a new property that is a reference to the Scale Manager. This is populated in the boot method.
    • ๐Ÿšš The InputManager.transformX method has been removed. This is now available in the ScaleManager.
    • ๐Ÿšš The InputManager.transformY method has been removed. This is now available in the ScaleManager.
    • ๐Ÿšš The InputManager.scale property has been removed. This is now available in the ScaleManager under displayScale.
    • ๐Ÿšš The InputManager.resize method has been removed as this process is now handled by the ScaleManager.
    • ๐Ÿšš The InputManager.bounds property has been removed as this process is now handled by the ScaleManager.
    • โšก๏ธ The InputManager.updateBounds method has been removed as this process is now handled by the ScaleManager.
    • ๐Ÿšš The InputManager.getOffsetX method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getOffsetY method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getScaleX method has been removed as it's no longer required.
    • ๐Ÿšš The InputManager.getScaleY method has been removed as it's no longer required.
    • ๐Ÿšš The SceneManager.resize method has been removed as it's no longer required.
    • ๐Ÿšš The Scene.Systems.resize method has been removed as it's no longer required.
    • Scenes will no longer dispatch the resize event. You should now listen for this event from the Scale Manager instead.
    • ๐Ÿšš BaseCamera.config has been removed as it's no longer required.
    • BaseCamera.scaleManager is a new property that references the Scale Manager and is used internally for size checks.
    • ๐Ÿšš The Game.resize method has been removed as it's no longer required. You should now call ScaleManager.resize instead.
    • The Game will no longer dispatch the resize event. You should now listen for this event from the Scale Manager instead.

    Important Namespace Changes

    • ๐Ÿšš The Phaser.Boot namespace has been renamed to Phaser.Core. As a result, the boot folder has been renamed to core. This impacts the TimeStep class and VisibilityHandler function, which have been moved to be under the new namespace.
    • โšก๏ธ The Phaser.Animations namespace was incorrectly exposed in the Phaser entrypoints as Animation (note the lack of plural). This means that if you are creating any custom classes that extend Animation objects using the Phaser namespace, then please update them from Phaser.Animation to Phaser.Animations, i.e. Phaser.Animation.AnimationFrame to Phaser.Animations.AnimationFrame. This doesn't impact you if you created animations directly via the Animation Manager.
    • The keyed Data Manager change data event string has changed from changedata_ to changedata- to keep it consistent with other keyed events. Note the change from _ to -.
    • The Keyboard Plugin keydown dynamic event string has changed from keydown_ to keydown- to keep it consistent with other keyed events. Note the change from _ to -.
    • The Keyboard Plugin keyup dynamic event string has changed from keyup_ to keyup- to keep it consistent with other keyed events. Note the change from _ to -.
    • The texturesready event emitted by the Texture Manager has been renamed to ready.
    • ๐Ÿ”Œ The loadcomplete event emitted by the Loader Plugin has been renamed to postprocess to be reflect what it's used for.
    • Game Objects used to emit a collide event if they had an Arcade Physics Body with onCollide set, that collided with a Tile. This has changed. The event has been renamed to tilecollide and you should now listen for this event from the Arcade Physics World itself: this.physics.world.on('tilecollide'). Game Objects no longer emit this event.
    • Game Objects used to emit an overlap event if they had an Arcade Physics Body with onOverlap set, that overlapped with a Tile. This has changed. The event has been renamed to tileoverlap and you should now listen for this event from the Arcade Physics World itself: this.physics.world.on('tileoverlap'). Game Objects no longer emit this event.
    • The function Phaser.Physics.Impact.SeperateX has been renamed to SeparateX to correct the spelling mistake.
    • The function Phaser.Physics.Impact.SeperateY has been renamed to SeparateY to correct the spelling mistake.
    • The ended event in WebAudioSound has been renamed to complete to make it more consistent with the rest of the API.
    • The ended event in HTML5AudioSound has been renamed to complete to make it more consistent with the rest of the API.

    ๐Ÿ†• New Features

    • ๐Ÿ“š You can now load external Scene files using the new load.sceneFile method. This allows you to dynamically load a Scene into the Scene Manager of your game, and swap to it at will. Please see the documentation and examples for further details.
    • The data object being sent to the Dynamic Bitmap Text callback now has a new property parent, which is a reference to the Bitmap Text instance that owns the data object (thanks ornyth)
    • The WebGL Renderer has a new method clearPipeline, which will clear down the current pipeline and reset the blend mode, ready for the context to be passed to a 3rd party library.
    • The WebGL Renderer has a new method rebindPipeline, which will rebind the given pipeline instance, reset the blank texture and reset the blend mode. This is useful for recovering from 3rd party libs that have modified the gl context.
    • ๐Ÿšš Game Objects have a new property called state. Use this to track the state of a Game Object during its lifetime. For example, it could move from a state of 'moving', to 'attacking', to 'dead'. Phaser itself will never set this property, although plugins are allowed to.
    • Game Objects have a new method called setState which will set the state property in a chainable call.
    • ๐ŸŒ BlendModes.ERASE is a new blend mode that will erase the object being drawn. When used in conjunction with a Render Texture it allows for effects that require you to erase parts of the texture, in either Canvas or WebGL. When used with a transparent game canvas, it allows you to erase parts of the canvas, showing the web page background through.
    • BlendModes.SOURCE_IN is a new Canvas-only blend mode that allows you to use the source-in composite operation when rendering Game Objects.
    • BlendModes.SOURCE_OUT is a new Canvas-only blend mode that allows you to use the source-out composite operation when rendering Game Objects.
    • BlendModes.SOURCE_ATOP is a new Canvas-only blend mode that allows you to use the source-atop composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_OVER is a new Canvas-only blend mode that allows you to use the destination-over composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_IN is a new Canvas-only blend mode that allows you to use the destination-in composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_OUT is a new Canvas-only blend mode that allows you to use the destination-out composite operation when rendering Game Objects.
    • BlendModes.DESTINATION_ATOP is a new Canvas-only blend mode that allows you to use the destination-atop composite operation when rendering Game Objects.
    • BlendModes.LIGHTER is a new Canvas-only blend mode that allows you to use the lighter composite operation when rendering Game Objects.
    • BlendModes.COPY is a new Canvas-only blend mode that allows you to use the copy composite operation when rendering Game Objects.
    • BlendModes.XOR is a new Canvas-only blend mode that allows you to use the xor composite operation when rendering Game Objects.
    • ๐Ÿšš RenderTexture.erase is a new method that will take an object, or array of objects, and draw them to the Render Texture using an ERASE blend mode, resulting in them being removed from the Render Texture. This is really handy for making a bitmap masked texture in Canvas or WebGL (without using an actual mask), or for 'cutting away' part of a texture.
    • There is a new boolean Game Config property called customEnvironment. If set to true it will skip the internal Feature checks when working out which type of renderer to create, allowing you to run Phaser under non-native web environments. If using this value, you must set an explicit renderType of either CANVAS or WEBGL. It cannot be left as AUTO. Fix #4166 (thanks @jcyuan)
    • Animation.nextFrame will advance an animation to the next frame in the sequence instantly, regardless of the animation time or state. You can call this on a Sprite: sprite.anims.nextFrame() (thanks rgk25)
    • Animation.previousFrame will set an animation to the previous frame in the sequence instantly, regardless of the animation time or state. You can call this on a Sprite: sprite.anims.previousFrame() (thanks rgk25)
    • 0๏ธโƒฃ Geom.Intersects.PointToLine has a new optional argument lineThickness (which defaults to 1). This allows you to determine if the point intersects a line of a given thickness, where the line-ends are circular (not square).
    • Geom.Line.GetNearestPoint is a new static method that will return the nearest point on a line to the given point.
    • โœ… Geom.Line.GetShortestDistance is a new static method that will return the shortest distance from a line to the given point.
    • Camera.getBounds is a new method that will return a rectangle containing the bounds of the camera.
    • ๐Ÿšš Camera.centerOnX will move the camera horizontally to be centered on the given coordinate without changing its vertical placement.
    • ๐Ÿšš Camera.centerOnY will move the camera vertically to be centered on the given coordinate without changing its horizontally placement.
    • ๐Ÿ‘€ AnimationManager.exists is a new method that will check to see if an Animation using the given key already exists or not and returns a boolean.
    • animationstart-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationstart-explode.
    • animationrestart-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationrestart-explode.
    • animationcomplete-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationcomplete-explode.
    • โšก๏ธ animationupdate-key is a new Animation key specific event emitted by a Game Object. For example, if you had an animation with a key of 'explode' you can now listen for animationupdate-explode.
    • The Animation class now extends the Event Emitter and dispatches events itself. This allows you to listen for events from a specific Animation, rather than via a Game Object. This is handy, for example, if you had an explosion animation that you wanted to trigger a sound effect when it started. You can now listen for the events from the Animation object directly.
    • The Animation class now emits the start event when played (either forward, or in reverse) by any Game Object.
    • The Animation class now emits the restart event when it restarts playing on any Game Object.
    • The Animation class now emits the complete event when it finishes playing on any Game Object.
    • The Animation Component has a new method called chain which allows you to line-up another animation to start playing as soon as the current one stops, no matter how it stops (either by reaching its natural end, or directly by having stop called on it). You can chain a new animation at any point, including before the current one starts playing, during it, or when it ends (via its animationcomplete callback). Chained animations are specific to a Game Object, meaning different Game Objects can have different chained animations without impacting the global animation they're playing.
    • CanvasTexture.drawFrame is a new method that allows you to draw a texture frame to the CanvasTexture based on the texture key and frame given.
    • CanvasTexture.getIndex is a new method that will take an x/y coordinate and return the Image Data index offset used to retrieve the pixel values.
    • CanvasTexture.getPixels is a new method that will take a region as an x/y and width/height and return all of the pixels in that region from the CanvasTexture.
    • CanvasTexture.setPixel is a new method that sets the given pixel in the CanvasTexture to the color and alpha values provided.
    • CanvasTexture.getData is a new method that will extract an ImageData block from the CanvasTexture from the region given.
    • CanvasTexture.putData is a new method that will put an ImageData block at the given coordinates in a CanvasTexture.
    • Line.Extend is a new static function that allows you extend the start and/or end points of a Line by the given amounts.
    • Vector2.LEFT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.RIGHT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.UP is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.DOWN is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector2.ONE is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.ZERO is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.LEFT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.RIGHT is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.UP is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.DOWN is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.FORWARD is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.BACK is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Vector3.ONE is a new constant that can be used in Vector comparison operations (thanks @Aedalus)
    • Geometery Mask has a new property called invertAlpha in WebGL, which works in the same way as the flag on the Bitmap Mask and allows you to invert the function of the stencil buffer, i.e. non-drawn shapes become invisible, and drawn shapes visible (thanks @tfelix)
    • The Arcade Physics Body has a new property maxSpeed which limits the vector length of the Body velocity. You can set it via the method setMaxSpeed and it is applied in the World.computeVelocity method (thanks @Edwin222 @rexrainbow)
    • WebGLRenderer.snapshotArea is a new method that allows you to grab an image of the given region of the canvas during the post-render step and have it sent to your defined callback. This is the same as snapshot except you control the area being grabbed, so is more efficient if you only need a smaller area.
    • WebGLRenderer.snapshotPixel is a new method that allows you to grab a single pixel from the game canvas, post-render. It returns the result as a Color object to your specified callback.
    • CanvasRenderer.snapshotArea is a new method that allows you to grab an image of the given region of the canvas during the post-render step and have it sent to your defined callback. This is the same as snapshot except you control the area being grabbed, so is more efficient if you only need a smaller area.
    • CanvasRenderer.snapshotPixel is a new method that allows you to grab a single pixel from the game canvas, post-render. It returns the result as a Color object to your specified callback.

    โšก๏ธ Updates

    • 0๏ธโƒฃ You can now modify this.physics.world.debugGraphic.defaultStrokeWidth to set the stroke width of any debug drawn body, previously it was always 1 (thanks @samme)
    • ๐Ÿ’… TextStyle.setFont has a new optional argument updateText which will sets if the text should be automatically updated or not (thanks @DotTheGreat)
    • ProcessQueue.destroy now sets the internal toProcess counter to zero.
    • ๐Ÿšš The PathFollower.pathRotationVerticalAdjust property has been removed. It was supposed to flipY a follower when it reversed path direction, but after some testing it appears it has never worked and it's easier to do this using events, so the property and associated config value are removed. The verticalAdjust argument from the setRotateToPath method has been removed as well.
    • ๐Ÿšš The config value preserveDrawingBuffer has been removed as it has never been used by the WebGL Renderer.
    • ๐Ÿ”Œ PluginManager.install returns null if the plugin failed to install in all cases.
    • PluginFile will now install the plugin into the current Scene as long as the start or mapping arguments are provided.
    • MATH_CONST no longer requires or sets the Random Data Generator, this is now done in the Game Config, allowing you to require the math constants without pulling in a whole copy of the RNG with it.
    • The Dynamic Bitmap Text Canvas Renderer was creating a new data object every frame for the callback. It now uses the callbackData object instead, like the WebGL renderer does.
    • WebGLRenderer.setBlendMode has a new optional argument force, which will force the given blend mode to be set, regardless of the current settings.
    • ๐Ÿšš The method DisplayList.sortGameObjects has been removed. It has thrown a runtime error since v3.3.0(!) which no-one even spotted which is a good indication of how little the method was used. The display list is automatically sorted anyway, so if you need to sort a small section of it, just use the standard JavaScript Array sort method (thanks ornyth)
    • ๐Ÿšš The method DisplayList.getTopGameObject has been removed. It has thrown a runtime error since v3.3.0(!) which no-one even spotted which is a good indication of how little the method was used (thanks ornyth)
    • โšก๏ธ WebGLRenderer.setFramebuffer has a new optional boolean argument updateScissor, which will reset the scissor to match the framebuffer size, or clear it.
    • WebAudioSoundManager.onFocus will not try to resume the Audio Context if it's still locked.
    • WebAudioSoundManager.onBlur will not try to suspend the Audio Context if it's still locked.
    • ๐Ÿ”Œ When using ScenePlugin.add, to add a new Scene to the Scene Manager, it didn't allow you to include the optional Scene data object. You can now pass this in the call (thanks @kainage)
    • Graphics.stroke is a new alias for the strokePath method, to keep the calls consistent with the Canvas Rendering Context API.
    • Graphics.fill is a new alias for the fillPath method, to keep the calls consistent with the Canvas Rendering Context API.
    • ๐Ÿ”Œ LoaderPlugin.sceneManager is a new property that is a reference to the global Scene Manager, useful for Plugins.
    • ๐Ÿ‘ Whenever Camera.roundPixels was enabled it would use a bitwise operation to truncate the float (x |= 0) - this has been replaced across all files that used it, with a call to Math.round instead. This gives far better results when zooming cameras both in and out of a Scene, stopping thin gaps appearing between closely packed Game Objects.
    • AnimationManager.create will now return a boolean false if the given key is invalid (i.e. undefined or falsey).
    • โš  AnimationManager.create will no longer raise a console warning if the animation key is already in use. Instead, it will return the animation belonging to that key. A brand new animation will only be created if the key isn't already in use. When this happens, the add event is emitted by the Animation Manager. If no event is emitted, the animation already existed.
    • ArcadePhysics.Body.destroy will now only add itself to the World pendingDestroy list if the world property exists. This prevents Cannot read property 'pendingDestroy' of undefined errors if you try to delete a physics body in a callback and then immediately change Scene (which tells the physics work to also delete all bodies)
    • ๐Ÿšš The Animation Component restart method has had is sole key argument removed. Previously, you had to pass in the key of the animation you wished to reverse, but now you can just call the method directly, and as long as there is an animation playing, it will automatically start playing in reverse, without the nee for a key (the way it should have been originally)
    • Animation.play and playReverse will now accept either a string-based key of the animation to play (like before), or you can pass in an Animation instance, and it will play that animation.
    • CanvasTexture.clear now has 4 new optional arguments: x, y, width, height which allow you to define the region of the texture to be cleared. If not provided it will clear the whole texture, which is the same behavior as before.
    • ๐ŸŽ EarCut, the polygon triangulation library used by the Graphics and WebGL classes, has been upgraded from 2.1.1 to 2.1.4. 2.1.2 fixed a few race conditions where bad input would cause an error. 2.1.3 improved performance for bigger inputs (5-12%) and 2.1.4 fixed a race condition that could lead to a freeze on degenerate input.
    • TextureTintPipeline.batchQuad and batchTri have two new optional arguments texture and unit which are used to re-set the batch texture should the method cause a batch flush.
    • TextureTintPipeline.requireTextureBatch is a new internal method that helps speed-up the creation of texture batches. It is used in conjunction with setTexture2D and pushBatch.
    • ๐Ÿ”จ TextureTintPipeline.flush and TextureTintPipeline.pushBatch have been optimized to handle zero based texture units as priority. They've also been refactored to avoid creation of empty texture batches.
    • The WebGLRenderer.setTexture2D method has a new optional argument flush which controls if the pipeline is flushed if the given texture is new, or not. This is used internally to skip flushing during an existing flush.
    • The Tilemap Layer width and height properties are now based on the tilemap tile sizes multiplied by the layer dimensions. This corrects an issue with layer sizes being wrong if you called setBaseTileSize on a Map.
    • The WebGLRenderer will now clear the framebuffer at the start of every render.
    • 0๏ธโƒฃ WebGLRenderer.setScissor now has a new optional argument drawingBufferHeight which allows you to specify the drawing buffer height, rather than use the renderers default value.
    • 0๏ธโƒฃ WebGLRenderer.pushScissor now has a new optional argument drawingBufferHeight which allows you to specify the drawing buffer height, rather than use the renderers default value.
    • โช WebGLRenderer.preRender now calls gl.clearColor in order to restore the background clear color in case something, like a Render Texture, has changed it.
    • โšก๏ธ Map.set will now update an existing value if you provide it with a key that already exists within the Map. Previously, if you tried to set the value of a key that existed it would be skipped.
    • MatterSprite would set its type property to be Image. It now sets it to be Sprite as it should do.
    • โšก๏ธ Matter.TileBody.setFromTileCollision no longer checks if the shape is concave or convex before modifying the vertices, as the update to the Matter.js lib in 3.12 stopped this from working with Tiled collision shapes.
    • The Scene transitionstart event is now dispatched by the Target Scene of a transition, regardless if the Scene has a create method or not. Previously, it was only dispatched if the Scene had a create method.
    • ๐Ÿ’ป The Loader will now allow an XHR status of 0 as success too. Normally only status 200 would be accepted as success, but 0 is returned when a file is loaded from the local filesystem (file://). This happens, for example, when opening the index.html of a game in a browser directly, or when using Cordova on iOS. Fix #3464 (thanks @Ithamar)
    • Tween.restart now returns the Tween instance (thanks @rexrainbow)
    • Tween.play now returns the Tween instance (thanks @rexrainbow)
    • ๐Ÿ‘€ Tween.seek now returns the Tween instance (thanks @rexrainbow)
    • Tween.complete now returns the Tween instance (thanks @rexrainbow)
    • Tween.stop now returns the Tween instance (thanks @rexrainbow)
    • List.sort now has an optional parameter handler which allows you to provide your own sort handling function (thanks @jcyuan)
    • Container.sort now has an optional parameter handler which allows you to provide your own sort handling function (thanks @jcyuan)
    • The WebGLRenderer method canvasToTexture will now only set the filter to be NEAREST if antialias is disabled in the game config (i.e. when running in pixelArt mode). This means that Text objects, and other Canvas backed textures, now render with anti-aliasing if everything else does. You can disable this on a per-object basis by calling texture.setFilter(1) on them.
    • ๐Ÿšš CanvasRenderer.snapshotCallback, snapshotType and snapshotEncoder have all been removed as they are no longer required.
    • ๐Ÿ”ง CanvasRenderer.snapshotState is a new object that contains the snapshot configuration data, the same as the WebGL Renderer.
    • ๐Ÿ”ง The signature of the WebGLSnapshot function has changed. It now takes a Snapshot Configuration object as the second parameter.
    • ๐Ÿ”ง The signature of the CanvasSnapshot function has changed. It now takes a Snapshot Configuration object as the second parameter.

    ๐Ÿ› Bug Fixes

    • The Rectangle Shape object wouldn't render if it didn't have a stroke, or any other objects on the display list (thanks mliko)
    • ๐Ÿ’… When using a font string instead of setting fontFamily, fontSize and fontStyle in either Text.setStyle or setFont, the style properties wouldn't get set. This isn't a problem while creating the text object, only if modifying it later (thanks @DotTheGreat)
    • ๐Ÿ’… Text.toJSON wasn't saving the font style when using the "font" shorthand to create it. It now saves it correctly. Fix #4141 (thanks @divillysausages)
    • Disabling camera bounds and then moving the camera to an area in a Tilemap that did not have any tile information would throw an Uncaught Reference error as it tried to access tiles that did not exist (thanks @Siyalatas)
    • ๐Ÿ›  Fixed an issue where Sprite Sheets being extracted from a texture atlas would fail if the sheet was either just a single column or single row of sprites. Fix #4096 (thanks @Cirras)
    • ๐Ÿ”ง If you created an Arcade Physics Group without passing a configuration object, and passing an array of non-standard children, it would throw a classType runtime error. It now creates a default config object correctly (thanks @pierpo)
    • The Camera.cull method has been restructured so it now calculates if a Game Object is correctly in view or not before culling it. Although not used internally, if you need to cull objects for a camera, you can now safely use this method. Fix #4092 (thanks @Cirras)
    • ๐Ÿ“œ The Tiled Parser would ignore animated tile data if it was in the new Tiled 1.2 format. This is now accounted for, as well as 1.0 (thanks @nkholski)
    • Array.Matrix.ReverseRows was actually reversing the columns, but now reverses the rows.
    • Array.Matrix.ReverseColumns was actually reversing the rows, but now reverses the columns.
    • UnityAtlas now sets the correct file type key if using a config file object.
    • Starting with version 3.13 in the Canvas Renderer, it was possible for long-running scripts to start to get bogged-down in fillRect calls if the game had a background color set. The context is now saved properly to avoid this. Fix #4056 (thanks @Aveyder)
    • 0๏ธโƒฃ Render Textures created larger than the size of the default canvas would be automatically clipped when drawn to in WebGL. They now reset the gl scissor and drawing height property in order to draw to their full size, regardless of the canvas size. Fix #4139 (thanks @chaoyang805 @iamchristopher)
    • The cameraFilter property of a Game Object will now allow full bitmasks to be set (a value of -1), instead of just those > 0 (thanks @stuartkeith)
    • The PathFollower.startFollow method now properly uses the startAt argument to the method, so you can start a follower off at any point along the path. Fix #3688 (thanks @DannyT @diteix)
    • Static Circular Arcade Physics Bodies now render as circles in the debug display instead of showing their rectangle bounds (thanks @maikthomas)
    • Changing the mute flag on an HTML5AudioSound instance, via the mute setter, now works as it does via the Sound Manager (thanks @Waclaw-I @neon-dev)
    • Changing the volume on an HTML5AudioSound instance, via the volume setter, now works as it does via the Sound Manager (thanks @Waclaw-I)
    • The Dynamic Tilemap Layer WebGL renderer was drawing tiles at the incorrect position if the layer was scaled. Fix #4104 (thanks @the-realest-stu)
    • Tile.tileset now returns the specific Tileset associated with the tile rather than an array of them. Fix #4095 (thanks @quadrupleslap)
    • ๐Ÿ‘ Tile.getCollisionGroup wouldn't return the correct Group after the change to support multiple Tilesets. It now returns the group properly (thanks @jbpuryear)
    • ๐Ÿ‘ Tile.getTileData wouldn't return the correct data after the change to support multiple Tilesets. It now returns the tile data properly (thanks @jbpuryear)
    • ๐Ÿšš The GetTileAt and RemoveTileAt components would error with "Cannot read property 'index' of undefined" if the tile was undefined rather than null. It now handles both cases (thanks @WaSa42)
    • โšก๏ธ Changing TileSprite.width or TileSprite.height will now flag the texture as dirty and call updateDisplayOrigin, allowing you to resize TileSprites dynamically in both Canvas and WebGL.
    • ๐Ÿ›  RandomDataGenerator.shuffle has been fixed to use the proper modifier in the calculation allowing for a more even distribution (thanks wayfinder)
    • ๐Ÿ’ป The Particle Emitter was not recycling dead particles correctly so it was creating new objects every time it emitted (the old particles were then left to the browsers gc to clear up). This has now been recoded so the emitter will properly keep track of dead particles and re-use them (thanks @Waclaw-I for the initial PR)
    • ๐Ÿšš ParticleEmitter.indexSortCallback has been removed as it's no longer required.
    • ๐Ÿšš Particle.index has been removed as it's no longer required. Particles don't need to keep track of their index any more.
    • โšก๏ธ The Particle Emitter no longer needs to call the StableSort.inplace during its preUpdate, saving cpu.
    • Particle.resetPosition is a new method that is called when a particle dies preparing it for firing again in the future.
    • โช The Canvas SetTransform method would save the context state, but it wasn't restored at the end in the following Game Objects: Dynamic Bitmap Text, Graphics, Arc, Curve, Ellipse, Grid, IsoBox, IsoTriangle, Line, Polygon, Rectangle, Star and Triangle. These now all restore the context, meaning if you're using non-canvas sized cameras in Canvas mode, it will now render beyond just the first custom camera.
    • ๐Ÿšš Utils.Array.MoveUp wouldn't let you move an array element to the top-most index in the array. This also impacted Container.moveUp.
    • The Texture Tint Pipeline had a logic error that would cause every 2001st quad to either be invisible, or pick-up the texture of the 2000th quad by mistake. The batchQuad and batchTri methods how handle re-assigning the batch texture if they cause a batch flush as part of their process.
    • Rotating Sprites that used a Normal Map wouldn't rotate the normal map with it causing the lighting effects to become irregular. The normal map vectors are now rotated correctly (thanks @sercant for the PR and @fazzamatazz and @ysraelJMM for the report)
    • Changing scaleX or scaleY on a MatterImage or MatterSprite would cause the body scale to become distorted as the setters didn't use the correct factor when resetting the initial scale. Fix #4206 (thanks @YannCaron)
    • โšก๏ธ StaticBody.reset in Arcade Physics would ignore the x and y values given to it. If given, they're now used to reset the parent Game Object before the body is updated. Fix #4224 (thanks @samme)
    • Static Tilemap Layers wouldn't render correctly if the layer used a tileset with a different size to the base map data (set via setBaseTileSize). They now render correctly in WebGL and Canvas regardless of the base tile size.
    • When using RenderTexture.fill, the alpha argument would be ignored in Canvas mode. It's now used when filling the RenderTexture.
    • ๐Ÿ›  Fixed an issue in WebGLRenderer.setScissor where it was possible to try and compare the scissor size to a non-current scissor if called outside of the render loop (i.e. from RenderTexture.fill) (thanks @hackhat)
    • RenderTexture.fill in WebGL would use gl.clear and a clear color to try and fill the Render Texture. This only worked for full-canvas sized RenderTextures that didn't have a camera zoom applied. It has now been swapped to use the drawFillRect method of the Texture Tint Pipeline, allowing it to work properly regardless of camera zoom or size.
    • Container.getFirst was using an incorrect Array Utils function GetFirstElement when it should have been using GetFirst. It now uses the correct function. Fix #4244 (thanks @miran248)
    • List.getFirst was using an incorrect Array Utils function GetFirstElement when it should have been using GetFirst. It now uses the correct function. Fix #4244 (thanks @miran248)
    • ๐Ÿ›  Fixed an issue where changing the viewport or size of a Camera belonging to a RenderTexture wouldn't impact the rendering and objects will still render outside of the viewport range. It's now converted to a proper gl scissor rect by the renderer, meaning you can limit the area rendered to by adjusting the internal Render Texture cameras viewport. Fix #4243 (thanks @hackhat)
    • CanvasTexture.destroy is a new method that specifically handles the destruction of the CanvasTexture and all of its associated typed arrays. This prevents a memory leak when creating and destroying lots of RenderTextures (which are CanvasTexture backed). Fix #4239 (thanks @sjb933)
    • ๐Ÿšš The Alpha, Flip and Origin components have been removed from the Mesh Game Object (and by extension, Quad as well) as they are not used in the renderer and should be manipulated via the Mesh properties. Fix #4188 (thanks @enriqueto)
    • ๐Ÿšš The processDomCallbacks method in the Input Manager wasn't correctly clearing the once arrays. Responsibility for this has now been passed to the queue methods queueTouchStart, queueTouchMove, queueTouchEnd, queueMouseDown, queueMouseMove and queueMouseUp. Fix #4257 (thanks @iArePJ)
    • โšก๏ธ Arcade Physics now manages when postUpdate should be applied better, stopping it from gaining a zero delta during a further check in the same frame. This fixes various issues, including the mass collision test demo. Fix #4154 (thanks @samme)
    • Arcade Physics could trigger a collide event on a Body even if it performing an overlap check, if the onCollide property was true (thanks @samme)
    • TileSprites no longer cause a crash when using the Headless mode renderer. Fix #4297 (thanks @clesquir)
    • The WebGLRenderer will now apply a transparent background if transparent = true in the game config (thanks @gomachan7)
    • List.sort was missing the scope required for the sort handler, this is now correctly provided internally. Fix #4241 (thanks @jcyuan)
    • Container.sort was missing the scope required for the sort handler, this is now correctly provided internally. Fix #4241 (thanks @jcyuan)
    • DataManager.pop would emit the DataManager instance, instead of the parent, as the first event argument. It now emits the parent as it should do. Fix #4186 (thanks @gadelan)

    Examples and TypeScript

    ๐Ÿ‘ Thanks to the following for helping with the Phaser 3 Examples and TypeScript definitions, either by reporting errors, or even better, fixing them:

    @guilhermehto @samvieten @darkwebdev @RoryO @snowbillr @slothyrulez @jcyuan @jestarray

    Phaser Doc Jam

    ๐Ÿ“š The Phaser Doc Jam was a community-backed effort to try and get the Phaser 3 API documentation to 100% coverage. The Doc Jam is now over and I offer my thanks to the following who helped with docs in this release:

    @16patsle - @gurungrahul2 - @icbat - @samme - @telinc1 - anandu pavanan - blackhawx - candelibas - Diego Romero - doronlinder - Elliott Wallace - eric - Georges Gabereau - Haobo Zhang - henriacle - jak6jak - Jake Jensen - James Van Roose - JamesSkemp - joelahoover - Joey - madclaws - marc136 - Mihail Ilinov - naum303 - NicolasRoehm - nuane - rejacobson - Robert Kowalski - rodri042 - rootasjey - sawamara - scottwestover - sir13tommy - stetso - therealsamf - Tigran - willblackmore - zenwaichi

    ๐Ÿ“„ Also, the following helped with the docs outside of the Doc Jam:

    @bryanwood @jestarray @matosummer @tfelix @imilo @BigZaphod @OmarShehata @16patsle @jcyuan @iam13islucky @FractalBobz

  • v3.15.1 Changes

    October 16, 2018

    ๐Ÿ”– Version 3.15.1 - Batou - 16th October 2018

    • Re-enabled Input Manager resizing, which had been left disabled by mistake.

    ๐Ÿ”– Version 3.15.0 - Batou - 16th October 2018

    ๐ŸŽ Note: We are releasing this version ahead of schedule in order to make some very important iOS performance and input related fixes available. It does not contain the new Scale Manager or Spine support, both of which have been moved to 3.16 as they require a few more weeks of development.

    ๐Ÿ†• New Features

    • ๐ŸŽ You can now set the maxLights value in the Game Config, which controls the total number of lights the Light2D shader can render in a single pass. The default is 10. Be careful about pushing this too far. More lights = less performance. Close #4081 (thanks @FrancescoNegri)
    • Rectangle.SameDimensions determines if the two objects (either Rectangles or Rectangle-like) have the same width and height values under strict equality.
    • An ArcadePhysics Group can now pass { enable: false }` in its config to disable all the member bodies (thanks @samme)
    • Body.setEnable is a new chainable method that allows you to toggle the enable state of an Arcade Physics Body (thanks @samme)
    • ๐Ÿ”Œ KeyboardPlugin.resetKeys is a new method that will reset the state of any Key object created by a Scene's Keyboard Plugin.
    • Pointer.wasCanceled is a new boolean property that allows you to tell if a Pointer was cleared due to a touchcancel event. This flag is reset during the next touchstart event for the Pointer.
    • Pointer.touchcancel is a new internal method specifically for handling touch cancel events. It has the same result as touchend without setting any of the up properties, to avoid triggering up event handlers. It will also set the wasCanceled property to true.

    โšก๏ธ Updates

    • ๐Ÿ‘€ WebGLRenderer.deleteTexture will check to see if the texture it is being asked to delete is the currently bound texture or not. If it is, it'll set the blank texture to be bound after deletion. This should stop RENDER WARNING: there is no texture bound to the unit 0 errors if you destroy a Game Object, such as Text or TileSprite, from an async or timed process (thanks jamespierce)
    • โšก๏ธ The RequestAnimationFrame.step and stepTimeout functions have been updated so that the new Frame is requested from raf before the main game step is called. This allows you to now stop the raf callback from within the game update or render loop. Fix #3952 (thanks @tolimeh)
    • If you pass zero as the width or height when creating a TileSprite it will now use the dimensions of the texture frame as the size of the TileSprite. Fix #4073 (thanks @jcyuan)
    • โšก๏ธ TileSprite.setFrame has had both the updateSize and updateOrigin arguments removed as they didn't do anything for TileSprites and were misleading.
    • ๐Ÿšš CameraManager.remove has a new argument runDestroy which, if set, will automatically call Camera.destroy on the Cameras removed from the Camera Manager. You should nearly always allow this to happen (thanks jamespierce)
    • Device.OS has been restructured to allow fake UAs from Chrome dev tools to register iOS devices.
    • Texture batching during the batch flush has been implemented in the TextureTintPipeline which resolves the issues of very low frame rates, especially on iOS devices, when using non-batched textures such as those used by Text or TileSprites. Fix #4110 #4086 (thanks @ivanpopelyshev @sachinhosmani@maximtsai @alexeymolchan)
    • The WebGLRenderer method canvasToTexture has a new optional argument noRepeat which will stop it from using gl.REPEAT entirely. This is now used by the Text object to avoid it potentially switching between a REPEAT and CLAMP texture, causing texture black-outs (thanks @ivanpopelyshev)
    • ๐Ÿ”Œ KeyboardPlugin.resetKeys is now called automatically as part of the Keyboard Plugin shutdown method. This means, when the plugin shuts down, such as when stopping a Scene, it will reset the state of any key held in the plugin. It will also clear the queue of any pending events.
    • The Touch Manager has been rewritten to use declared functions for all touch event handlers, rather than bound functions. This means they will now clear properly when the TouchManager is shut down.
    • There is a new Input constant TOUCH_CANCEL which represents canceled touch events.

    ๐Ÿ› Bug Fixes

    • ๐Ÿ›  Fixed a bug in the canvas rendering of both the Static and Dynamic Tilemap Layers where the camera matrix was being multiplied twice with the layer, causing the scale and placement to be off (thanks galerijanamar)
    • If you set pixelArt to true in your game config (or antialias to false) then TileSprites will now respect this when using the Canvas Renderer and disable smoothing on the internal fill canvas.
    • TileSprites that were set to be interactive before they had rendered once wouldn't receive a valid input hit area, causing input to fail. They now define their size immediately, allowing them to be made interactive without having rendered. Fix #4085 (thanks @DotTheGreat)
    • โš  The Particle Emitter Manager has been given a NOOP method called setBlendMode to stop warnings from being thrown if you added an emitter to a Container in the Canvas renderer. Fix #4083 (thanks @maximtsai)
    • The game.context property would be incorrectly set to null after the WebGLRenderer instance was created (thanks @samme)
    • ๐Ÿ’ป The Touch Manager, Input Manager and Pointer classes all now handle the touchcancel event, such as triggered on iOS when activating an out of browser UI gesture, or in Facebook Instant Games when displaying an overlay ad. This should prevent issues with touch input becoming locked on iOS specifically. Fix #3756 (thanks @sftsk @sachinhosmani @kooappsdevs)
  • v3.15.0 Changes

    October 16, 2018

    ๐ŸŽ Note: We are releasing this version ahead of schedule in order to make some very important iOS performance and input related fixes available. It does not contain the new Scale Manager or Spine support, both of which have been moved to 3.16 as they require a few more weeks of development.

    ๐Ÿ†• New Features

    • ๐ŸŽ You can now set the maxLights value in the Game Config, which controls the total number of lights the Light2D shader can render in a single pass. The default is 10. Be careful about pushing this too far. More lights = less performance. Close #4081 (thanks @FrancescoNegri)
    • Rectangle.SameDimensions determines if the two objects (either Rectangles or Rectangle-like) have the same width and height values under strict equality.
    • An ArcadePhysics Group can now pass { enable: false } in its config to disable all the member bodies (thanks @samme)
    • Body.setEnable is a new chainable method that allows you to toggle the enable state of an Arcade Physics Body (thanks @samme)
    • ๐Ÿ”Œ KeyboardPlugin.resetKeys is a new method that will reset the state of any Key object created by a Scene's Keyboard Plugin.
    • Pointer.wasCanceled is a new boolean property that allows you to tell if a Pointer was cleared due to a touchcancel event. This flag is reset during the next touchstart event for the Pointer.
    • Pointer.touchcancel is a new internal method specifically for handling touch cancel events. It has the same result as touchend without setting any of the up properties, to avoid triggering up event handlers. It will also set the wasCanceled property to true.

    โšก๏ธ Updates

    • ๐Ÿ‘€ WebGLRenderer.deleteTexture will check to see if the texture it is being asked to delete is the currently bound texture or not. If it is, it'll set the blank texture to be bound after deletion. This should stop RENDER WARNING: there is no texture bound to the unit 0 errors if you destroy a Game Object, such as Text or TileSprite, from an async or timed process (thanks jamespierce)
    • โšก๏ธ The RequestAnimationFrame.step and stepTimeout functions have been updated so that the new Frame is requested from raf before the main game step is called. This allows you to now stop the raf callback from within the game update or render loop. Fix #3952 (thanks @tolimeh)
    • If you pass zero as the width or height when creating a TileSprite it will now use the dimensions of the texture frame as the size of the TileSprite. Fix #4073 (thanks @jcyuan)
    • โšก๏ธ TileSprite.setFrame has had both the updateSize and updateOrigin arguments removed as they didn't do anything for TileSprites and were misleading.
    • ๐Ÿšš CameraManager.remove has a new argument runDestroy which, if set, will automatically call Camera.destroy on the Cameras removed from the Camera Manager. You should nearly always allow this to happen (thanks jamespierce)
    • Device.OS has been restructured to allow fake UAs from Chrome dev tools to register iOS devices.
    • Texture batching during the batch flush has been implemented in the TextureTintPipeline which resolves the issues of very low frame rates, especially on iOS devices, when using non-batched textures such as those used by Text or TileSprites. Fix #4110 #4086 (thanks @ivanpopelyshev @sachinhosmani @maximtsai @alexeymolchan)
    • The WebGLRenderer method canvasToTexture has a new optional argument noRepeat which will stop it from using gl.REPEAT entirely. This is now used by the Text object to avoid it potentially switching between a REPEAT and CLAMP texture, causing texture black-outs (thanks @ivanpopelyshev)
    • ๐Ÿ”Œ KeyboardPlugin.resetKeys is now called automatically as part of the Keyboard Plugin shutdown method. This means, when the plugin shuts down, such as when stopping a Scene, it will reset the state of any key held in the plugin. It will also clear the queue of any pending events.
    • The Touch Manager has been rewritten to use declared functions for all touch event handlers, rather than bound functions. This means they will now clear properly when the TouchManager is shut down.
    • There is a new Input constant TOUCH_CANCEL which represents canceled touch events.

    ๐Ÿ› Bug Fixes

    • ๐Ÿ›  Fixed a bug in the canvas rendering of both the Static and Dynamic Tilemap Layers where the camera matrix was being multiplied twice with the layer, causing the scale and placement to be off (thanks galerijanamar)
    • If you set pixelArt to true in your game config (or antialias to false) then TileSprites will now respect this when using the Canvas Renderer and disable smoothing on the internal fill canvas.
    • TileSprites that were set to be interactive before they had rendered once wouldn't receive a valid input hit area, causing input to fail. They now define their size immediately, allowing them to be made interactive without having rendered. Fix #4085 (thanks @DotTheGreat)
    • โš  The Particle Emitter Manager has been given a NOOP method called setBlendMode to stop warnings from being thrown if you added an emitter to a Container in the Canvas renderer. Fix #4083 (thanks @maximtsai)
    • The game.context property would be incorrectly set to null after the WebGLRenderer instance was created (thanks @samme)
    • ๐Ÿ’ป The Touch Manager, Input Manager and Pointer classes all now handle the touchcancel event, such as triggered on iOS when activating an out of browser UI gesture, or in Facebook Instant Games when displaying an overlay ad. This should prevent issues with touch input becoming locked on iOS specifically. Fix #3756 (thanks @sftsk @sachinhosmani @kooappsdevs)
  • v3.14.0 Changes

    October 01, 2018

    โšก๏ธ Tilemap New Features, Updates and Fixes

    • โœ… Both Static and Dynamic Tilemap layers now support rendering multiple tilesets per layer in both Canvas and WebGL. To use multiple tilesets pass in an array of Tileset objects, or strings, to the createStaticLayer and createDynamicLayer methods respectively.
    • โœ… Tilemap.createStaticLayer now supports passing either a Tileset reference, or a string, or an array of them as the 2nd argument. If strings, the string should be the Tileset name (usually defined in Tiled).
    • ๐Ÿ‘ Tilemap.createDynamicLayer now supports passing either a Tileset reference, or a string, or an array of them as the 2nd argument. If strings, the string should be the Tileset name (usually defined in Tiled).
    • ๐Ÿ‘ Tilemap.createBlankDynamicLayer now supports passing either a Tileset reference, or a string, or an array of them as the 2nd argument. If strings, the string should be the Tileset name (usually defined in Tiled).
    • ๐Ÿ‘ Static Tilemap Layers now support tile rotation and flipping. Previously this was a feature only for Dynamic Tilemap Layers, but now both have it. Close #4037 (thanks @thisredone)
    • Tilemap.getTileset is a new method that will return a Tileset based on its name.
    • ๐Ÿ“œ ParseTilesets has been rewritten so it will convert the new data structures of Tiled 1.2 into the format expected by Phaser, allowing you to use either Tiled 1.2.x or Tiled 1.1 JSON exports. Fix #3998 (thanks @martin-pabst @halgorithm)
    • Tilemap.setBaseTileSize now sets the size into the LayerData baseTileWidth and baseTileHeight properties accordingly. Fix #4057 (thanks @imilo)
    • Calling Tilemap.renderDebug ignored the layer world position when drawing to the Graphics object. It will now translate to the layer position before drawing. Fix #4061 (thanks @Zax37)
    • Calling Tilemap.renderDebug ignored the layer scale when drawing to the Graphics object. It will now scale the layer before drawing. Fix #4026 (thanks @JasonHK)
    • The Static Tilemap Layer would stop drawing all tiles from that point on, if it encountered a tile which had invalid texture coordinates (such as a tile from another tileset). It now skips invalid tiles properly again. Fix #4002 (thanks @jdotrjs)
    • If you used a RenderTexture as a tileset then Dynamic Tilemap Layers would render the tiles inversed on the y-axis in WebGL. Fix #4017 (thanks @s-s)
    • If you used a scaled Dynamic Tilemap Layer and rotated or flipped tiles, the tiles that were rotated or flipped would be positioned incorrectly in WebGL. Fix #3778 (thanks @nkholski)
    • StaticTilemapLayer.tileset is now an array of Tileset objects, where-as before it was a single reference.
    • StaticTilemapLayer.vertexBuffer is now an array of WebGLBuffer objects, where-as before it was a single instance.
    • StaticTilemapLayer.bufferData is now an array of ArrayBuffer objects, where-as before it was a single instance.
    • StaticTilemapLayer.vertexViewF32 is now an array of Float3Array objects, where-as before it was a single instance.
    • StaticTilemapLayer.vertexViewU32 is now an array of Uint32Array objects, where-as before it was a single instance.
    • StaticTilemapLayer.dirty is now an array of booleans, where-as before it was a single boolean.
    • StaticTilemapLayer.vertextCount is now an array of integers, where-as before it was a single integer.
    • โšก๏ธ StaticTilemapLayer.updateVBOData() is a new private method that creates the internal VBO data arrays for the WebGL renderer.
    • The StaticTilemapLayer.upload() method has a new parameter tilesetIndex which controls which tileset to prepare the VBO data for.
    • The StaticTilemapLayer.batchTile() method has a new parameter tilesetIndex which controls which tileset to batch the tile for.
    • StaticTilemapLayer.setTilesets() is a new private method that creates the internal tileset references array.
    • DynamicTilemapLayer.tileset is now an array of Tileset objects, where-as before it was a single reference.
    • DynamicTilemapLayer.setTilesets() is a new private method that creates the internal tileset references array.

    ๐Ÿ†• New Features

    • bodyDebugFillColor is a new Matter Physics debug option that allows you to set a color used when drawing filled bodies to the debug Graphic.
    • 0๏ธโƒฃ debugWireframes is a new Matter Physics debug option that allows you to control if the wireframes of the bodies are used when drawing to the debug Graphic. The default is true. If enabled bodies are not filled.
    • debugShowInternalEdges is a new Matter Physics debug option that allows you to set if the internal edges of a body are rendered to the debug Graphic.
    • 0๏ธโƒฃ debugShowConvexHulls is a new Matter Physics debug option that allows you to control if the convex hull of a body is drawn to the debug Graphic. The default is false.
    • debugConvexHullColor is a new Matter Physics debug option that lets you set the color of the convex hull, if being drawn to the debug Graphic.
    • debugShowSleeping is a new Matter Physics debug option that lets you draw sleeping bodies at 50% opacity.
    • Curves.Ellipse.angle is a new getter / setter that handles the rotation of the curve in degrees instead of radians.

    โšก๏ธ Updates

    • โšก๏ธ The Loader has been updated to handle the impact of you destroying the game instance while still processing files. It will no longer throw cache and texture related errors. Fix #4049 (thanks @pantoninho)
    • โšก๏ธ Polygon.setTo can now take a string of space separated numbers when creating the polygon data, i.e.: '40 0 40 20 100 20 100 80 40 80 40 100 0 50'. This update also impacts the Polygon Shape object, which can now also take this format as well.
    • โšก๏ธ The poly-decomp library, as used by Matter.js, has been updated to 0.3.0.
    • Matter.verts, available via this.matter.verts from within a Scene, is a quick way of accessing the Matter Vertices functions.
    • You can now specify the vertices for a Matter fromVerts body as a string.
    • TextureTintPipeline.batchTexture has a new optional argument skipFlip which allows you to control the internal render texture flip Y check.
    • ๐Ÿ— The Device.OS check for node will now do a typeof first to avoid issues with rollup packaged builds needing to shim the variable out. Fix #4058 (thanks @hollowdoor)
    • โšก๏ธ Arcade Physics Bodies will now sync the display origin of the parent Game Object to the body properties as part of the updateBounds call. This means if you change the origin of an AP enabled Game Object, after creation of the body, it will be reflected in the body position. This may or may not be a breaking change for your game. Previously it was expected that the origin should always be 0.5 and you adjust the body using setOffset, but this change makes a bit more sense logically. If you find that your bodies are offset after upgrading to this version then this is likely why. Close #4052 (thanks @SolarOmni)
    • 0๏ธโƒฃ The Texture.getFramesFromTextureSource method has a new boolean argument includeBase, which defaults to false and allows you to set if the base frame should be returned into the array or not.
    • There is a new Animation Event that is dispatched when an animation restarts. Listen for it via Sprite.on('animationrestart').
    • โšก๏ธ All of the Animation Events now pass the Game Object as the final argument, this includes animationstart, animationrestart, animationrepeat, animationupdate and animationcomplete.
    • Curves.Ellipse.rotation is a getter / setter that holds the rotation of the curve. Previously it expected the value in degrees and when getting it returned the value in radians. It now expects the value in radians and returns radians to keep it logical.
    • Set.size will now only set the new size if the value is smaller than the current size, truncating the Set in the process. Values larger than the current size are ignored.
    • ๐Ÿ‘€ Arcade Physics shutdown will check to see if the world instance still exists and only try removing it if so. This prevents errors when stopping a world and then destroying it at a later date.
    • ๐Ÿ’… Text.setFont, Text.setFontFamily, Text.setFontStyle and Text.setStroke will no longer re-measure the parent Text object if their values have not changed.

    ๐Ÿ› Bug Fixes

    • ๐Ÿšš GameObjects added to and removed from Containers no longer listen for the shutdown event at all (thanks Vitali)
    • ๐Ÿšš Sprites now have preDestroy method, which is called automatically by destroy. The method destroys the Animation component, unregistering the remove event in the process and freeing-up resources. Fix #4051 (thanks @Aveyder)
    • โšก๏ธ UpdateList.shutdown wasn't correctly iterating over the pending lists (thanks @felipeprov)
    • Input detection was known to be broken when the game resolution was !== 1 and the Camera zoom level was !== 1. Fix #4010 (thanks @s-s)
    • The Shape.Line object was missing a lineWidth property unless you called the setLineWidth method, causing the line to not render in Canvas only. Fix #4068 (thanks @netgfx)
    • All parts of Matter Body now have the gameObject property set correctly. Previously only the first part of the Body did.
    • When using MatterGameObject and fromVerts as the shape type it wouldn't pass the values to Bodies.fromVertices because of a previous conditional. It now passes them over correctly and the body is only set if the result is valid.
    • The Texture.getFramesFromTextureSource method was returning an array of Frame names by mistake, instead of Frame references. It now returns the Frames themselves.
    • ๐Ÿ”€ When using CanvasTexture.refresh or Graphics.generateTexture it would throw WebGL warnings like 'bindTexture: Attempt to bind a deleted texture'. This was due to the Frames losing sync with the glTexture reference used by their TextureSource. Fix #4050 (thanks @kanthi0802)
    • ๐Ÿ›  Fixed an error in the batchSprite methods in the Canvas and WebGL Renderers that would incorrectly set the frame dimensions on Sprites with the crop component. This was particularly noticeable on Sprites with trimmed animation frames (thanks @sergeod9)
    • ๐Ÿ›  Fixed a bug where the gl scissor wasn't being reset during a renderer resize, causing it to appear as if the canvas didn't resize properly when autoResize was set to true in the game config. Fix #4066 (thanks @Quinten @hsan999)
    • ๐Ÿšš If a Game instance is destroyed without using the removeCanvas argument, it would throw exceptions in the MouseManager after the destroy process has run, as the event listeners were not unbound. They're not unbound, regardless of if the parent canvas is removed or not. Fix #4015 (thanks @garethwhittaker)

    Examples and TypeScript

    A huge thanks to @presidenten for his work on the Phaser 3 Examples. You'll notice they now have a lovely screen shots for every example and the scripts generate them automatically :)

    ๐Ÿ‘ Also, thanks to the following for helping with the Phaser 3 Examples and TypeScript definitions, either by reporting errors, or even better, fixing them:

    @madanus @truncs @samme

    Phaser Doc Jam

    ๐Ÿ“š The Phaser Doc Jam is an on-going effort to ensure that the Phaser 3 API has 100% documentation coverage. Thanks to the monumental effort of myself and the following people we're now really close to that goal! My thanks to:

    31826615 - @16patsle - @bobonthenet - @rgk - @samme - @shaneMLK - @wemyss - ajmetal - andiCR - Arian Fornaris - bsparks - Carl - cyantree - DannyT - Elliott Wallace - felixnemis - griga - Hardylr - henriacle - Hsaka - icbat - Kanthi - Kyle - Lee - Nathaniel Foldan - Peter Pedersen - rootasjey - Sam Frantz - SBCGames - snowbillr - Stephen Hamilton - STuFF - TadejZupancic - telinc1

    ๐Ÿ“š If you'd like to help finish off the last parts of documentation then take a look at the Doc Jam site.

  • v3.13.0 Changes

    September 20, 2018

    ๐Ÿ”Œ Facebook Instant Games Plugin

    ๐Ÿ”€ Phaser 3.13 introduces the new Facebook Instant Games Plugin. The plugin provides a seamless bridge between Phaser and version 6.2 of the Facebook Instant Games SDK. Every single SDK function is available via the plugin and we will keep track of the official SDK to make sure they stay in sync.

    ๐Ÿ”Œ The plugin offers the following features:

    • โšก๏ธ Easy integration with the Phaser Loader so load events update the Facebook progress circle.
    • ๐Ÿ”Œ Events for every plugin method, allowing the async calls of the SDK to be correctly inserted into the Phaser game flow. When SDK calls resolve they will surface naturally as a Phaser event and you'll know you can safely act upon them without potentially doing something mid-way through the game step.
    • ๐Ÿ”Œ All Plugin methods check if the call is part of the supported APIs available in the SDK, without needing to launch an async request first.
    • Instant access to platform, player and locale data.
    • Easily load player photos directly into the Texture Manager, ready for use with a Game Object.
    • Subscribe to game bots.
    • ๐Ÿ”€ The plugin has a built-in Data Manager which makes dealing with data stored on Facebook seamless. Just create whatever data properties you need and they are automatically synced.
    • ๐Ÿ‘Œ Support for FB stats, to retrieve, store and increment stats into cloud storage.
    • ๐Ÿ’พ Save Session data with built-in session length validation.
    • Easy context switching, to swap between game instances and session data retrieval.
    • Easily open a Facebook share, invite, request or game challenge window and populate the text and image content using any image stored in the Texture cache.
    • โšก๏ธ Full Leaderboard support. Retrieve, scan and update leaderboard entries, as well as player matching.
    • ๐Ÿ‘Œ Support for in-app purchases, with product catalogs, the ability to handle purchases, get past purchases and consume previously unlocked purchases.
    • Easily preload a set of interstitial ads, in both banner and video form, then display the ad at any point in your game, with in-built tracking of ads displayed and inventory available.
    • ๐Ÿ“ˆ Plus other features, such as logging to FB Analytics, creating short cuts, switching games, etc.

    ๐Ÿ”Œ The plugin is fully documented and official tutorials and project templates will follow shortly.

    ๐Ÿ†• New Shape Game Objects

    Phaser 3.13 has a new Game Object called Shape, which by itself isn't much use because it's a base class. However, extending that class are 11 different types of Shape (with more to come) and you can use it to create your own custom Shapes as well. Shapes are added to the display list in the exact same way as any other Game Object. For example:

    this.add.rectangle(400, 300, 500, 120, 0x00ff00);
    

    Here we're creating a new Rectangle shape. It's positioned at 400 x 300 in the Scene and has a size of 500 x 120 pixels. The final value is the fill color.

    The thing to remember is that you can treat this Shape just like you'd treat any other Game Object. You can scale it, rotate it, alpha it, blend mode it, change its origin, give it a Camera scroll factor, put it inside a Container or Group, give it input abilities or even give it a physics body. It is, to all intents and purposes, a normal Game Object. The only difference is that when rendering it uses its own special bit of display code.

    The shapes available are as follows:

    • GameObject.Arc - The arc allows you to draw either a circle, or part of a circle. You can set the start and end angle, if the rotation is clockwise or not, and even set the number of iterations the arc will use during rendering.
    • GameObject.Curve - The Curve Shape can take any Phaser Curve object, such as a Spline or Bezier Curve, and add it to the display list.
    • GameObject.Ellipse - An ellipse shape, which is essentially a circle with a differing width and height. It can be filled or stroked (or both!) and as with the arc you can set the 'smoothness' of it, allowing you to decrease the number of points used when creating its polygon data.
    • GameObject.Grid - The Grid Shape object allows you to generate them. You can set the width and height of the grid itself, as well as for the grid cells. The grid can either have a single color, or alternating cell colors and even have outline spacing between the cells, or not.
    • GameObject.Line - Create a Line Shape drawn between any two points, with a color and thickness. In WebGL you can also specify a different thickness for the start and end of the line.
    • GameObject.Polygon - A Polygon is effectively a list of points that is drawn between. The points can be provided in a number of different ways (as Vec2 objects, as an array, etc) and then you can either fill or stroke the resulting shape, or both.
    • GameObject.Rectangle - Simple, but powerful and endlessly useful. Set a width and height and it'll display a Rectangle, with control over the size, fill color and stroke color.
    • GameObject.Star - The Star shape does as its name suggests: it displays a star. You can control the number of points in the star as well as the inner and outer radius of it.
    • GameObject.Triangle - A Triangular shape with full control over the points used to make it and its fill and stroke colors. Internally it uses the batchFillTriangle method in WebGL, making it actually faster to draw than a Quad! Use them happily for bullets or abstract space ships, or anything else you feel like.
    • GameObject.IsoTriangle - This draws an isometric triangle, like a pyramid. You can control the colors of each face, if the pyramid is upside down or not and the width and height of it.
    • GameObject.IsoBox - This draws an isometric box. You can set the colors for each face of the box, as well as the projection angle and also which of the 3 faces are drawn.

    All of the Shape objects render in both Canvas and WebGL and are available via the Game Object Factory.

    โšก๏ธ Pointer and Input Event Updates

    ๐Ÿ”Œ The specificity if the input events has been changed to allow you more control over event handling. Previously, the InputPlugin would emit the global pointerdown event first, and then the Game Object itself would emit the pointerdown event and finally the InputPlugin would emit the gameobjectdown event.

    ๐Ÿ”Œ The order has now changed. The Game Object will dispatch its pointerdown event first. The InputPlugin will then dispatch gameobjectdown and finally the less specific of them all, pointerdown will be dispatched.

    ๐Ÿ†• New in 3.13 is the ability to cancel this at any stage. All events are now sent an event object which you can call event.stopPropagation() on. This will immediately stop any further listeners from being invoked. If you call stopPropagation() after the first Game Object pointerdown event, then no more Game Object's will receive their callbacks and the InputPlugin will not dispatch either of its events.

    ๐Ÿš€ This change has been introduced for pointerdown, pointerup, pointermove, pointerover and pointerout. No other data is included in the event object in this release.

    • The Game Object pointerdown callback signature has changed. It used to send pointer, x, y, camera to the listener. It now sends pointer, x, y, event to the listener. If you still need the camera property you can get it from pointer.camera.
    • The Game Object gameobjectdown callback signature has a new argument. It now sends event as the 3rd argument.
    • The pointerdown event, as dispatched by the InputPlugin, is now sent after the Game Object specific events (GameObject.pointerdown and gameobjectdown). This gives you the chance to cancel the event before the global listener receives it.
    • The Game Object pointerup callback signature has a new argument. It now sends the event as the 4th argument.
    • The Game Object gameobjectup callback signature has a new argument. It now sends event as the 3rd argument.
    • The pointerup event, as dispatched by the InputPlugin, is now sent after the Game Object specific events (GameObject.pointerup and gameobjectup). This gives you the chance to cancel the event before the global listener receives it.
    • ๐Ÿšš The Game Object pointermove callback signature has a new argument. It now sends the event as the 4th argument.
    • ๐Ÿšš The Game Object gameobjectmove callback signature has a new argument. It now sends event as the 3rd argument.
    • The pointermove event, as dispatched by the InputPlugin, is now sent after the Game Object specific events (GameObject.pointermove and gameobjectmove). This gives you the chance to cancel the event before the global listener receives it.
    • The Game Object pointerover callback signature has a new argument. It now sends the event as the 4th argument.
    • The Game Object gameobjectover callback signature has a new argument. It now sends event as the 3rd argument.
    • The pointerover event, as dispatched by the InputPlugin, is now sent after the Game Object specific events (GameObject.pointerover and gameobjectover). This gives you the chance to cancel the event before the global listener receives it.
    • The Game Object pointerout callback signature has a new argument. It now sends the event as the 2nd argument.
    • The Game Object gameobjectout callback signature has a new argument. It now sends event as the 3rd argument.
    • The pointerout event, as dispatched by the InputPlugin, is now sent after the Game Object specific events (GameObject.pointerout and gameobjectout). This gives you the chance to cancel the event before the global listener receives it.

    โšก๏ธ Game Object List Updates

    โšก๏ธ When Sprite's are created they are added to two lists within the Scene - the Display List and the Update List. Under 3.12 when a Scene was shut down it would emit a shutdown event, which Sprites listened out for. When they received it, they would destroy themselves.

    โšก๏ธ After profiling and testing this process has changed slightly. Game Object's no longer listen for the Scene shutdown event. Instead, the Display List and Update List will iterate their children and call destroy on them in turn. If being destroyed by a Scene in this way, the child will skip several expensive operations in its destroy function. More importantly, in busy Scenes you no longer need thousands of event listeners registered. The result is that changing Scene is now up to 100% faster than before. You need not change your code to benefit from this, however, if you were relying on custom Game Objects listening for the Scene shutdown event natively, then this is no longer the case and you'll have to manually add that listener to your classes.

    • The UpdateList will now clear out its internal _list, _pendingRemoval and _pendingInsertion lists on shutdown. Before, it would only clear _list.
    • GameObject.destroy has a new optional boolean argument fromScene, which controls how the destroy process flows.

    Camera Render to Texture

    โœ… In 3.12 a new Camera method called setRenderToTexture was introduced. However, it had known issues so was placed under the experimental flag and you were advised not to use it unless in testing.

    ๐Ÿš€ Thanks to several fixes in this release the experimental flag has been dropped and it's now safe to try using this new feature in production.

    The method sets the Camera to render to a texture instead of to the main canvas. The Camera will redirect all Game Objects it's asked to render to this texture. During the render sequence, the texture itself will then be rendered to the main canvas.

    Doing this gives you the ability to modify the texture before this happens, allowing for special effects such as Camera specific shaders, or post-processing on the texture.

    • Camera.setRenderToTexture is a new method that enables the Camera to render to a target texture instead of the main canvas, allowing for application of special effects at run-time.
    • Camera.clearRenderToTexture is a new method that stops a Camera from rendering to a texture and frees-up all associated resources.
    • Camera.setPipeline allows you to change the WebGL pipeline being used if the Camera is rendering to a texture, effectively swapping the active shader. Call with no arguments to clear the pipeline.
    • Camera.renderToTexture is a boolean property that controls where the Camera renders. It can be toggled on the fly.
    • Camera.canvas is a Canvas Element that the Camera will render to if running under the Canvas Renderer and rendering to a texture.
    • Camera.context is a Rendering Context that the Camera will render to if running under the Canvas Renderer and rendering to a texture.
    • Camera.glTexture is a WebGL Texture that the Camera will render to if running under the WebGL Renderer and rendering to a texture.
    • Camera.framebuffer is a WebGL Frame Buffer that the Camera will render to if running under the WebGL Renderer and rendering to a texture.
    • Camera.pipeline is the Pipeline that the Camera will render with if running under the WebGL Renderer and rendering to a texture with a pipeline set.
    • If you set a Camera to render to a texture then it will emit 2 events during the render loop. First, it will emit the event prerender. This happens right before any Game Object's are drawn to the Camera texture. Then, it will emit the event postrender. This happens after all Game Object's have been drawn, but right before the Camera texture is rendered to the main game canvas. It's the final point at which you can manipulate the texture before it appears in-game.

    ๐Ÿ†• New Features

    • โšก๏ธ The Color object has a new property h which represents the hue of the color. You can tween or adjust this property in real-time and it will automatically update the internal RGB values with it.
    • โšก๏ธ The Color object has a new property s which represents the saturation of the color. You can tween or adjust this property in real-time and it will automatically update the internal RGB values with it.
    • โšก๏ธ The Color object has a new property v which represents the lightness value of the color. You can tween or adjust this property in real-time and it will automatically update the internal RGB values with it.
    • Color.setFromHSV is a new method that will set the color values based on the HSV values given.
    • Color.gray is a new method that will set the color to be a shade of gray based on the amount given.
    • Color.random is a new method that will set the color to be a random hue based on the min and max values given.
    • Color.randomGray is a new method that will set the color to be a random grayscale based on the min and max values given.
    • Color.saturate is a new method that will saturate the color based on the amount given. This is a chainable version of adjusting the saturation property directly.
    • Color.desaturate is a new method that will desaturate the color based on the amount given. This is a chainable version of adjusting the saturation property directly.
    • Color.lighten is a new method that will lighten the color based on the amount given. This is a chainable version of adjusting the value property directly.
    • Color.darken is a new method that will darken the color based on the amount given. This is a chainable version of adjusting the value property directly.
    • Color.brighten is a new method that will brighten the color based on the amount given.
    • The CanvasTexture class has a new property imageData which contains the ImageData of the texture.
    • The CanvasTexture class has a new property data which is a Uint8ClampedArray view into the buffer.
    • The CanvasTexture class has a new property pixels which is a Uint32Array view into the buffer.
    • The CanvasTexture class has a new property buffer which is an ArrayBuffer the same size as the context ImageData.
    • โšก๏ธ The CanvasTexture class has a new method update which refreshes the ImageData and ArrayBuffer based on the texture contents.
    • โšก๏ธ The CanvasTexture class has a new method draw which draws the given Image or Canvas element to the CanvasTexture, then updates the internal ImageData buffer and arrays.
    • The CanvasTexture class has a new method getPixel which will get the color of a specific pixel from the Canvas Texture and store it in the returned Color object. It uses the ArrayBuffer to do this, which is extremely fast, allowing for quick iteration across the canvas data.
    • The WebGLPipeline and WebGLRenderer have new a method setFloat1v which allows you to set a uniform1fv uniform value (thanks @Mattykins)
    • The WebGLPipeline and WebGLRenderer have new a method setFloat2v which allows you to set a uniform2fv uniform value (thanks @Mattykins)
    • The WebGLPipeline and WebGLRenderer have new a method setFloat3v which allows you to set a uniform3fv uniform value (thanks @Mattykins)
    • The WebGLPipeline and WebGLRenderer have new a method setFloat4v which allows you to set a uniform4fv uniform value (thanks @Mattykins)
    • Text.setLineSpacing is a new method that allows you to easily set the line spacing value of a Text object in a chainable call (thanks @RafelSanso)

    โšก๏ธ Updates

    • The Graphics Canvas Renderer will now automatically call beginPath on the target context before processing the command stack. This has the effect of clearing off any sub-paths that may have persisted on the stack from previous Graphics objects or frames. This makes it more in-line with WebGL re: expectations when calling Graphics.clear.
    • ๐Ÿšš initPipeline now defaults to the Texture Tint Pipeline if nothing else is specified. This allowed me to remove explicit strings from 11 different Game Objects, saving some bytes in the process.
    • The RGBToHSV function can now take an optional out argument, which is either a HSVColorObject or a Color object, and the results will be set into that object instead of creating a new one.
    • The HSVToRGB function can now take an optional out argument, which is either a HSVColorObject or a Color object, and the results will be set into that object instead of creating a new one.
    • โšก๏ธ Color.setTo has a new argument updateHSV which allows you to control if the internal HSV values are updated during the same call or not.
    • ๐Ÿ”ง The Text._lineSpacing property has been renamed to lineSpacing and made public, not private. You still set it in the same way, by passing a lineSpacing property to the Text configuration object, but internally it's now clearer.
    • If a Scene is already active (i.e. running) and you call start on it (such as from another Scene) then it will shutdown the Scene first, before starting it again.

    ๐Ÿ› Bug Fixes

    • TileSprite.setTileScale would set the tile position by mistake, instead of the scale. Using the properties directly worked, but the method was incorrect (thanks @alexeymolchan)
    • ๐Ÿ’… Calling Text.setStyle would make the Text vanish if you didn't provide a resolution property in the style configuration object. Calling setStyle now only changes the properties given in the object, leaving any previously changed properties as-is. Fix #4011 (thanks @okcompewter)
    • In Matter.js if a body had its debug render.visible property set to false it wouldn't then render any other debug body beyond it. Now it will just skip bodies with hidden debug graphics (thanks @jf908)
    • ๐Ÿšš If you flagged a Tween as paused in its config, never started it, and then called Tween.stop it wouldn't ever be removed from the _pending array. It's now moved to the Tween Manager's destroy list, ready for removal on the next frame. Fix #4023 (thanks @goldfire)
    • ๐Ÿ— Game Objects would not remove themselves from the Scene's shutdown event handler when destroyed, leading to a build-up over time (thanks @goldfire)
    • The WebGL Renderer will no longer try and just resize a canvas backed texture, instead it will properly delete it then re-create it. Fix #4016 (thanks @alexeymolchan)
    • The Camera background for mini-Cameras (those positioned deep inside another Camera) would be offset incorrectly in WebGL, causing the background fills to be displaced (thanks @aaronfc)
    • โœ… The WebGL Renderer now always enables the SCISSOR_TEST, this allows Game Objects that use the scissor (such as custom objects, or Bitmap Text) to render properly again.
    • โšก๏ธ The Cameras setScene method, which is called automatically when a new Camera is created, will now call updateSystem which correctly increases the custom viewport counter. This fixes an issue with mini-cams inside of larger cameras not clipping their contents properly. If a Camera is moved to another Scene it also now correctly shrinks the total custom viewport counter.
    • ๐Ÿšš Due to the two fixes above another bug was fixed: The ability for you to swap between Cameras with and without setRenderToTexture enabled with custom shaders. Previously if you used this with a custom shader then only the first Camera using the shader would render, the rest would appear black. Now, all Cameras using the custom shader work correctly. As a result all of the 'experimental' Camera rendering properties from 3.12 have been moved to stable.
    • If you destroyed a Game Object that had a custom cursor set during one of its input events the cursor didn't correctly reset. Fix #4033 (thanks @pantoninho)
    • RenderTexture.resize wouldn't correctly resize the texture under WebGL. Fix #4034 (thanks @jbpuryear)
    • Calling setFrame on a TileSprite wouldn't change the frame, it would just change the frame size. Fix #4039 (thanks @Jerenaux)
    • ๐Ÿš€ Zone.setRectangleDropZone used the wrong x and y coordinates for the hit area, causing it to be offset from the zone itself after the changes made for issue #3865 in the 3.12 release.

    ๐Ÿ“š 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:

    @johanlindfors @Arthur3DLHC @JamesSkemp