After months of hard work, I'm very happy to announce that Phaser 3.17 has been released. There are some significant new features that should make your life easier if you work with HTML Elements over your games, or wish to easily add Shaders in. Plus, there are literally hundreds of updates and fixes across most parts of the API. Let's take a look at some of the headliners:
Shaders
Previously, if you wanted to add a shader into your game, you'd need to create a custom WebGL pipeline. This wasn't too difficult, but it absolutely could have been made easier for when you just want to blast a simple shader onto the screen. Enter, the new Shader Game Object, and its underlying BaseShader display object.
Now, you can create a Shader and manipulate it on-screen just as if it was any other Game Object. This includes positioning, rotation, scaling, making interactive or even giving a physics body.
The GLSL File Loader has also been overhauled, making it a lot more powerful than before, including the ability to load shader bundles - which are single GLSL files that contain multiple shader definitions along with any uniform values they may require.
Using a shader is now as easy as this:
function preload ()
{
this.load.glsl('fireball', 'assets/shaders/shader0.frag');
}
function create ()
{
this.add.shader('fireball', 400, 300, 800, 600);
}Have a look at the Shader examples to see what else they can do, especially when used as bitmap masks!
DOM Elements
DOM Elements have finally left the experimental stage and are now part of the full Phaser release. DOM Element Game Objects are a way to control and manipulate HTML Elements over the top of your game. In order for DOM Elements to display you have to enable them by adding the following to your game configuration object:
dom {
createContainer: true
}When this is added, Phaser will automatically create a DOM Container div that is positioned over the top of the game canvas. This div is sized to match the canvas, and if the canvas size changes, as a result of settings within the Scale Manager, the dom container is resized accordingly.
You can create a DOM Element by either passing in DOMStrings, or by passing in a reference to an existing Element that you wish to be placed under the control of Phaser. For example:
this.add.dom(x, y, 'div', 'background-color: lime; width: 220px; height: 100px; font: 48px Arial', 'Phaser');The above code will insert a div element into the DOM Container at the given x/y coordinate. The DOMString in the 4th argument sets the initial CSS style of the div and the final argument is the inner text. In this case, it will create a lime colored div that is 220px by 100px in size with the text Phaser in it, in an Arial font.
You should nearly always, without exception, use explicitly sized HTML Elements, in order to fully control alignment and positioning of the elements next to regular game content.
Rather than specify the CSS and HTML directly you can use the load.html File Loader to load it into the cache and then use the createFromCache method instead. You can also use createFromHTML and various other methods available in this class to help construct your elements.
Once the element has been created you can then control it like you would any other Game Object. You can set its position, scale, rotation, alpha and other properties. It will move as the main Scene Camera moves and be clipped at the edge of the canvas. It's important to remember some limitations of DOM Elements: The obvious one is that they appear above or below your game canvas. You cannot blend them into the display list, meaning you cannot have a DOM Element, then a Sprite, then another DOM Element behind it.
You can find lots of examples on using DOM Elements in the Phaser 3 Examples repo.
Camera Masks
Masks have been given a huge overhaul in 3.17. You can still create Bitmap or Geometry Masks, but they're a lot smarter under the hood now. Masks can finally be stacked, meaning you can mask a child of a masked container. They restore themselves properly as the display list is processed and make use of caching, meaning performance of Game Objects using the same mask has just increased exponentially. Run this test under 3.17, then swap to 3.16 to see the speed difference :)
As well as improving their internals, I also added a feature I've been after for ages: Camera Masks. I added a new method to the Camera class called setMask and the related clearMask method. You can set either a Geometry or Bitmap Mask on a Camera and, as you'd expect, it will impact anything it renders.
The mask is applied to the top-level, impacting everything it renders. If you were to add another Camera, it would of course not be affected by this mask. Which makes this an interesting way to apply masks selectively.
A special feature of Camera Masks that I added is the ability for them to remain fixed in place. If you use the cursor keys in this demo you'll notice that the mask moves as the camera moves. This is optional. You can also create a static mask on a camera that ignores the camera scrolling. Try pressing the Q and E keys to zoom in and out of the Scene. With the fixed camera, the mask doesn't zoom. With the flexible one, it does. Also, press Z and X to rotate the Camera. Again, the mask rotates with it, but it won't do that with a fixed mask. I believe that having these two options will give you a lot of flexibility when it comes to masking your games.
Other Features
As important as the above are, they aren't the only new features :) There are lots more that aren't quite deserving of their own headline, but as no less useful. For example, Arcade Physics received a handy new method that allows you to get all bodies in a given region. Or, how about the new overlapTiles method, which lets you check a Body against an array of specific tiles, perfect for small subset tests when using a collider is too large.
There's more, too. Thanks to a great pull-request from @florianvazelle there are loads of new Geometry intersection tests, such as Circle to Circle or Triangle to Line which now return the points of intersection, rather than just a boolean response. Which is very handy for your own physics tests.
There are a few new Loader File Types: CSS File allows you to load a CSS file into the current document and have it applied. The Multi Scripts Loader lets you specify an array of external script files to be loaded, much like the load.script method in previous versions, except the array controls the exact order in which the scripts are invoked - allowing you to make a basic require.js style load system without any 3rd party code. The GLSL File Loader was given a boost, too, and now supports shader bundles.
As well as features there are stacks of updates and bug fixes, so if something has been plaguing your development in 3.16, please give the new version a try.
Download Phaser 3.17.0 from the GitHub releases page, or pull it in via the npm package. There are also the pre-built files available on the jsDeliver CDN.
The brand new 3.17 documentation has been updated and published. As before, you can read it online, or check out the repo to have a local copy.
The TypeScript definitions have been improved further still and are now available in the main Phaser repo. So, there's no need to clone another repo when updating Phaser any longer.
As always, please check out the Change Log for comprehensive details about what recent versions contain.
If you'd like to stay abreast of developments then I publish my Developer Logs in the Phaser World newsletter. Subscribe to stay in touch and get all the latest news from the core team and the wider community.
You can also follow Phaser on Twitter and chat with fellow Phaser devs in our Slack and Discord channels.
Phaser 3 wouldn't have been possible without the fantastic support of the community and Patreon. Thank you to everyone who supports our work, who shares our belief in the future of HTML5 gaming, and Phaser's role in that.