Phaser v3.60.0 Beta 3
Pre-releaseVersion 3.60.0 - Miku - in development
New Features - Sprite FX
- When defining the
renderTargets
in a WebGL Pipeline config, you can now set optionalwidth
andheight
properties, which will create a Render Target of that exact size, ignoring thescale
value (if also given). WebGLPipeline.isSpriteFX
is a new boolean property that defines if the pipeline is a Sprite FX Pipeline, or not. The default isfalse
.GameObjects.Components.FX
is a new component that provides access to FX specific propertis and methods. The Image and Sprite Game Objects have this component by default.fxPadding
and its related methodsetFXPadding
allow you to set extra padding to be added to the texture the Game Object renders with. This is especially useful for Sprite FX shaders that modify the sprite beyond its bounds, such as glow or shadow effects.- The
WebGLPipeline.setShader
method has a new optional parameterbuffer
that allows you to set the vertex buffer to be bound before the shader is activated. - The
WebGLPipeline.setVertexBuffer
method has a new optional parameterbuffer
that allows you to set the vertex buffer to be bound if you don't want to bind the default one. - The
WebGLRenderer.createTextureFromSource
method has a new optional boolean parameterforceClamp
that will for the clamp wrapping mode even if the texture is a power-of-two. RenderTarget
will now automatically set the wrapping mode to clamp.WebGLPipeline.flipProjectionMatrix
is a new method that allows you to flip the y and bottom projection matrix values via a parameter.PipelineManager.renderTargets
is a new property that holds an array ofRenderTarget
objects that allSpriteFX
pipelines can share, to keep texture memory as low as possible.PipelineManager.maxDimension
is a new property that holds the largest possible target dimension.PipelineManager.frameInc
is a new property that holds the amount theRenderTarget
s will increase in size in each iteration. The default value is 32, meaning it will create targets of size 32, 64, 96, etc. You can control this via the pipeline config object.PipelineManager.targetIndex
is a new property that holds the internal target array offset index. Treat it as read-only.- The Pipeline Manager will now create a bunch of
RenderTarget
objects during itsboot
method. These are sized incrementally from 32px and up (use theframeInc
value to alter this). These targets are shared by all Sprite FX Pipelines. PipelineManager.getRenderTarget
is a new method that will return the aRenderTarget
that best fits the dimensions given. This is typically called by Sprite FX Pipelines, rather than directly.PipelineManager.getSwapRenderTarget
is a new method that will return a 'swap'RenderTarget
that matches the size of the main target. This is called by Sprite FX pipelines and not typically called directly.PipelineManager.getAltSwapRenderTarget
is a new method that will return a 'alternative swap'RenderTarget
that matches the size of the main target. This is called by Sprite FX pipelines and not typically called directly.
New Features - Compressed Texture Support
Phaser 3.60 contains support for Compressed Textures. It can parse both KTX and PVR containers and within those has support for the following formats: ETC, ETC1, ATC, ASTC, BPTC, RGTC, PVRTC, S3TC and S3TCSRB. Compressed Textures differ from normal textures in that their structure is optimized for fast GPU data reads and lower memory consumption. Popular tools that can create compressed textures include PVRTexTool, ASTC Encoder and Texture Packer.
Compressed Textures are loaded using the new this.load.texture
method, which takes a texture configuration object that maps the formats to the files. The browser will then download the first file in the object that it knows it can support. You can also provide Texture Atlas JSON data, or Multi Atlas JSON data, too, so you can use compressed texture atlases. Currently, Texture Packer is the best tool for creating these type of files.
Development of this feature was kindly sponsored by Club Penguin Rewritten (https://cprewritten.net).
TextureSoure.compressionAlgorithm
is now populated with the compression format used by the texture.Types.Textures.CompressedTextureData
is the new compressed texture configuration object type.TextureManager.addCompressedTexture
is a new method that will add a compressed texture, and optionally atlas data into the Texture Manager and return aTexture
object than any Sprite can use.Textures.Parsers.KTXParser
is a new parser for the KTX compression container format.Textures.Parsers.PVRParser
is a new parser for the PVR compression container format.- The
WebGLRenderer.compression
property now holds a more in-depth object containing supported compression formats. - The
WebGLRenderer.createTextureFromSource
method now accepts theCompressedTextureData
data objects and creates WebGL textures from them. WebGLRenderer.getCompressedTextures
is a new method that will populate theWebGLRenderer.compression
object and return its value. This is called automatically when the renderer boots.WebGLRenderer.getCompressedTextureName
is a new method that will return a compressed texture format GLenum based on the given format.
New Features - Multi Tint Pipeline
- If you have a customised Multi Tint Pipeline fragment shader that uses the
%forloop%
declaration, you should update it to follow the new format defined inMulti.frag
. This new shader uses a function calledgetSampler
instead of the often massive if/else glsl blocks from before. Please see the shader code and update your own shaders accordingly. - The
Multi.frag
shader now uses ahighp
precision instead ofmediump
. - The
WebGL.Utils.checkShaderMax
function will no longer use a massive if/else glsl shader check and will instead rely on the value given ingl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS)
. - The
WebGL.Utils.parseFragmentShaderMaxTextures
function no longer supports the%forloop%
declaration. - The internal WebGL Utils function
GenerateSrc
has been removed as it's no longer required internally.
New Features
ScaleManager.getViewPort
is a new method that will return a Rectangle geometry object that matches the visible area of the screen (thanks @rexrainbow)- When starting a Scene and using an invalid key, Phaser will now raise a console warning informing you of this, instead of silently failing. Fix #5811 (thanks @ubershmekel)
GameObjects.Layer.addToDisplayList
andremoveFromDisplayList
are new methods that allows for you to now add a Layer as a child of another Layer. Fix #5799 (thanks @samme)GameObjects.Video.loadURL
has a new optional 4th parametercrossOrigin
. This allows you to specify a cross origin request type when loading the video cross-domain (thanks @rmartell)- You can now set
loader.imageLoadType: "HTMLImageElement"
in your Game Configuration and the Phaser Loader will use an Image Tag to load all images, rather than XHR and a Blob object which is the default. This is a global setting, so all file types that use images, such as Atlas or Spritesheet, will be changed via this flag (thanks @hanzooo) - You can now control the drawing offset of tiles in a Tileset using the new optional property
Tileset.tileOffset
(which is a Vector2). This property is set automatically when Tiled data is parsed and found to contain it. Fix #5633 (thanks @moJiXiang @kainage) - You can now set the alpha value of the Camera Flash effect before running it, where-as previously it was always 1 (thanks @kainage)
- The
Tilemap.createFromObjects
method has been overhauled to support typed tiles from the Tiled Map Editor (https://doc.mapeditor.org/en/stable/manual/custom-properties/#typed-tiles). It will now also examine the Tileset to inherit properties based on the tile gid. It will also now attempt to use the same texture and frame as Tiled when creating the object (thanks @lackhand)
Updates
- When you try to use a frame that is missing on the Texture, it will now give the key of the Texture in the console warning (thanks @samme)
- The
Display.Masks.BitmapMask
destroy
method will now remove the context-lost event handler. - The
hitArea
parameter of theGameObjects.Zone.setDropZone
method is now optional and if not given it will try to create a hit area based on the size of the Zone Game Object (thanks @rexrainbow) BitmapMask.scene
is a new property that allows the Bitmap Mask to reference the Scene it was created in.- The
DOMElement.preUpdate
method has been removed. If you overrode this method, please now seepreRender
instead. DOMElement.preRender
is a new method that will check parent visibility and improve its behavior, responding to the parent even if the Scene is paused or the element is inactive. Dom Elements are also no longer added to the Scene Update List. Fix #5816 (thanks @prakol16 @samme)- Phaser 3 is now built with webpack 5 and all related packages have been updated.
- Previously, an Array Matrix would enforce it had more than 2 rows. This restriction has been removed, allowing you to define and rotate single-row array matrices (thanks @andriibarvynko)
- The Gamepad objects now have full TypeScript definitions thanks to @sylvainpolletvillard
- Lots of configuration objects now have full TypeScript definitions thanks to @16patsle
Particle.fire
will now throw an error if the particle has no texture frame. This prevents an uncaught error later when the particle fails to render. Fix #5838 (thanks @samme @monteiz)ParticleEmitterManager.setEmitterFrames
will now print out console warnings if an invalid texture frame is given, or if no texture frames were set. Fix #5838 (thanks @samme @monteiz)SceneManager.stop
will now ignore the call if the Scene has already been shut down, avoiding potential problems with duplicate event handles. Fix #5826 (thanks @samme)- Removed the
Tint
andFlip
components from theCamera
class. Neither were ever used internally, or during rendering, so it was just confusing having them in the API. - A new
console.error
will be printed if theFile
,MultiFile
,JSONFile
orXMLFile
fail to process or parse correctly, even if they manage to load. Fix #5862 #5851 (thanks @samme @ubershmekel)
Bug Fixes
Animation.createFromAseprite
would calculate an incorrect frame duration if the frames didn't all have the same speed.- The URL scheme
capacitor://
has been added to the protocol check to prevent malformed double-urls in some environments (thanks @consolenaut) - Removed
Config.domBehindCanvas
property as it's never used internally. Fix #5749 (thanks @iamallenchang) dispatchTweenEvent
would overwrite one of the callback's parameters. This fix ensures thatTween.setCallback
now works consistently. Fix #5753 (thanks @andrei-pmbcn @samme)- The context restore event handler is now turned off when a Game Object is destroyed. This helps avoid memory leakage from Text and TileSprite Game Objects, especially if you consistently destroy and recreate your Game instance in a single-page app (thanks @rollinsafary-inomma @rexrainbow @samme)
- When the device does not support WebGL, creating a game with the renderer type set to
Phaser.WEBGL
will now fail with an error. Previously, it would fall back to Canvas. Now it will not fall back to Canvas. If you require that feature, use the AUTO render type. Fix #5583 (thanks @samme) - The
Tilemap.createFromObjects
method will now correctly place both tiles and other objects. Previously, it made the assumption that the origin was 0x1 for all objects, but Tiled only uses this for tiles and uses 0x0 for its other objects. It now handles both. Fix #5789 (thanks @samme) - The
CanvasRenderer.snapshotCanvas
method used an incorrect reference to the canvas, causing the operation to fail. It will now snapshot a canvas correctly. Fix #5792 #5448 (thanks @rollinsafary-inomma @samme @akeboshi1) - The
Tilemap.tileToWorldY
method incorrectly had the parametertileX
. It will worked, but didn't make sense. It is nowtileY
(thanks @mayacoda) - The
Tilemap.convertTilemapLayer
method would fail for isometric tilemaps by not setting the physic body alignment properly. It will now callgetBounds
correctly, allowing for use on non-orthagonal maps. Fix #5764 (thanks @mayacoda) - The
PluginManager.installScenePlugin
method will now check if the plugin is missing from the local keys array and add it back in, if it is (thanks @xiamidaxia) - The Spine Plugin would not work with multiple instances of the same game on a single page. It now stores its renderer reference outside of the plugin, enabling this. Fix #5765 (thanks @xiamidaxia)
- In Arcade Physics, Group vs. self collisions would cause double collision callbacks due to the use of the quad tree. For this specific conditions, the quad tree is now skipped. Fix #5758 (thanks @samme)
- During a call to
GameObject.Shapes.Rectangle.setSize
it will now correctly update the Rectangle object's display origin and default hitArea (thanks @rexrainbow) - The Arcade Physics Body will now recalculate its center after separation with a Tile in time for the values to be correct in the collision callbacks (thanks @samme)
- The
ParseTileLayers
function has been updated so that it no longer breaks when using a Tiled infinite map with empty chunks (thanks @jonnytest1) - The
PutTileAt
function will now set the Tile dimensions from the source Tileset, fixing size related issues when placing tiles manually. Fix #5644 (thanks @moJiXiang @stuffisthings) - The new
Tileset.tileOffset
property fixes an issue with drawing isometric tiles when an offset had been defined in the map data (thanks @moJiXiang) - Fixed issue in
Geom.Intersects.GetLineToLine
function that would fail with colinear lines (thanks @Skel0t) - The
CameraManager.destroy
function will now remove the Scale ManagerRESIZE
event listener created as part ofboot
, where-as before it didn't clean it up, leading to gc issues. Fix #5791 (thanks @liuhongxuan23) - With
roundPixels
set to true in the game or camera config, Sprites will no longer render at sub-pixel positions under CANVAS. Fix #5774 (thanks @samme) - The Camera will now emit
PRE_RENDER
andPOST_RENDER
events under the Canvas Renderer. Fix #5729 (thanks @ddanushkin) - The Multi Pipeline now uses
highp float
precision by default, instead ofmediump
. This fixes issues with strange blue 'spots' appearing under WebGL on some Android devices. Fix #5751 #5659 #5655 (thanks @actionmoon @DuncanPriebe @ddanushkin) - The
Tilemaps.Tile.getBounds
method would take acamera
parameter but then not pass it to the methods called internally, thus ignoring it. It now factors the camera into the returned Rectangle. Tilemap.createFromObjects
has had the rendering of Tiled object layers on isometric maps fixed. Objects contained in object layers generated by Tiled use orthogonal positioning even when the map is isometric and this update accounts for that (thanks @lfarroco)- Timers with very short delays (i.e. 1ms) would only run the callback at the speed of the frame update. It will now try and match the timer rate by iterating the calls per frame. Fix #5863 (thanks @rexrainbow)
- The
Text
,TileSprite
andRenderTexture
Game Objects would call the pre and post batch functions twice by mistake, potentially applying a post fx twice to them. ScaleManager.getParentBounds
will now also check to see if the canvas bounds have changed x or y position, and if so returntrue
, causing the Scale Manager to refresh all of its internal cached values. This fixes an issue where the canvas may have changed position on the page, but not its width or height, so a refresh wasn't triggered. Fix #5884 (thanks @jameswilddev)- The
SceneManager.bootScene
method will now always callLoaderPlugin.start
, even if there are no files in the queue. This means that the Loader will always dispatch itsSTART
andCOMPLETE
events, even if the queue is empty because the files are already cached. You can now rely on theSTART
andCOMPLETE
events to be fired, regardless, using them safely in your preload scene. Fix #5877 (thanks @sipals) - Calling
TimerEvent.reset
in the Timer callback would cause the timer to be added to the Clock's pending removal and insertion lists together, throwing an error. It will now not add to pending removal if the timer was reset. Fix #5887 (thanks @rexrainbow)
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:
@necrokot Golen @Pythux @samme @danfoster @eltociear @sylvainpolletvillard @hanzooo @etherealmachine @DeweyHur @twoco @austinlyon @Arcanorum