Due to the rapid pace of change some links or details may no longer be correct.

Published in Phaser World Issue 73 on 24th March 2017 by Richard Davey   @photonstorm

Layers, Sprite Flipping and Depth Sorting


Ok we've got a huge update for you this issue, so let's get started!

First of all I published Phaser CE 2.7.4, and.. ahem.. 2.7.5 an hour later, due to a PR I'd merged that broke the runtime, which I hadn't spotted. You can get the latest release from the Phaser site, GitHub, npm or jsDelivr. There are some great new features, including the ability to stop Pointers being paused, tile offsets, FireFox image cache bug fixes, and loads of TypeScript definition updates. It's great to see the community carry on enhancing Phaser 2, and we will continue to merge in PRs and help as we can in the coming months.

Phaser 3 Updates

As I mentioned last week I'm now working on Phaser 3 full time, having given up client work for the next 3 months to give it the dedication it needs to see it released. I still have to manage the company, update the Phaser web site, deal with support, write the newsletter, and all the usual tasks - but on the whole it has meant a lot more time for working on v3, as well as making new examples and tests.

How to edit the demo code

This week is heavy on the demos. I've linked each screen shot to its respective demo, so click them to see them running in browser. But one thing you may want to do is this: In the URL of a demo you'll see it says view.html (followed by the query string). If you change it to say edit.html instead you'll get the Monaco editor running in browser, with the source loaded in it, and a preview to the right. Here you can edit and click 'Run code' as much as you like to tinker around. Of course you can also clone the whole phaser3-examples repo too, but the above is a nice quick way to have a play. And now on with the updates.



Layers are new to Phaser 3 and act in a similar way to layers in Photoshop, in that you can use them to group together Game Objects, and then perform mass visual updates on them, such as changing positions, rotation, scaling, etc. An example may be sticking all the aliens in a Space Invaders game into a layer, and then using the layer methods to move the aliens left / right. In Phaser 2 you had Groups, but these were both visual and logical containers, where-as a Layer is purely a visual container. We will be adding Groups as well, which will be purely logical containers, soon.

It's important to understand that the Layer itself doesn't have a transform - when you add a Game Object to it, it doesn't suddenly reparent the Game Object, or have its transform adjusted to become local to the layer, instead it just becomes a child of the layer and anything you do to the layer is reflected in the children.

We're sticking to our internal rule of having a single level display list, keeping it fast and lean, but still want to provide really useful tools that will let you make games easily, and we honestly feel Layers will do just that.


Oh Flip

This is a simple but really useful addition: we added the ability to flip Game Objects. Just set 'sprite.flipX' to horizontally flip a sprite, or 'flipY' to vertically flip them. The effect is instant and handled by the renderer. In v2 you could achieve this by setting a negative scale, and we've kept support for that in too (we know old habits die hard!) but feel this is cleaner and will be more obvious in the API docs too.


Depth Sorting

Let's be honest, doing depth sorting in Phaser 2 is bloody hard, right? It's easy enough if you've got a very simple scene, as you can move objects up and down the display list. But as soon as you introduce something like a few Groups, or a Tilemap, things get a lot more complicated. This is a problem inherent with traditional deeply nested display lists, and often requires special handling or plugins to get around.

In Phaser 3 however things become a whole lot easier, you simply set the Game Objects z property. This can take any number value (including floats), making it trivial to match the z depth to a y value for example. And it doesn't matter if your objects are in different Layers, it will still work. Sorting only happens if a z property is updated during a frame, so we don't waste time changing the render list if we don't need to. We're also using a stable sort utility function to handle it, rather than the unstable Array.sort method, to avoid those nasty flickering messes that can occur. The end result is fast, and if you've clicked the mushrooms in a field of veg image above, can look beautiful too!

Do you remember a couple of weeks ago, when I was messing around with wireframe 3D objects? (if you missed it, scroll to the bottom of this issue for the Back Issues link), well they are a perfect test for depth sorting that doesn't just rely on a y value. So I took one of the wireframe demos and threw a load of sprites into it, one for each vertex in the shape, and kept the quad lines in too because they looked cool :) You can see it running here:


If you press the space bar while running the demo above it will cycle through different 3D shapes. The z values are being populated by the internal 3D data. The Graphics object itself (i.e. all of the green lines) also has a z index, although only at one depth, which is how the balls can appear 'behind' the lines sometimes. Ideally the demo should have made the balls darker the further away they were, that would help with the depth illusion, but I ran out of time - feel free to have a go though and submit a PR :)

After getting Phaser CE released yesterday I felt the need to try another type of depth sort demo. I'm thankful I did, because in the process we found an issue in our implementation which was then fixed :) but it occurred to me that a really good test of depth sorting is isometric maps. Now v2 has no support for iso maps at all (beyond a really neat community plugin), so I quickly exported a test map from the Tiled map editor, had to read-up on parsing the map data in order to build the world, and then threw it together. I was surprised at how nice the end result looked! And how quick it was to do. But to complete the demo I wanted something walking around the map. I went to OpenGameArt, found a link to an open source RPG game (called Flare) and found a really nice animated skeleton isometric sprite. I took this, added it into the map, and was blown away :) Here's a screen shot (again, click it to run it) - note it's not likely to work on mobile at all because the skeleton sprite sheet is massive (some 4096px wide), so it may not actually load on crappy old GPUs either, but otherwise give it a go!


In the above example you've got an isometric map exported and parsed from Tiled, with a few house sprites (of course with their own z depth), and a bunch of animated skeletons walking around, fighting, and generally doing skeleton like things. Finally the camera pans across the 1600px wide scene and back again.

If you look at the code you'll see I'm using a tween engine to handle sprite animation! This is because the Animation Manager isn't finished yet (it's on my list for next week), but otherwise it's a pretty clean example to have a scroll through. Feel free to add in your own skeletons (lines 190+).

So it's been a good week for sure, and this doesn't even cover everything we did (just the stuff worth demoing). Next week Felipe is working on the post processing engine, so we can apply cool special effects in the renderer, and I'll be carrying on with the Animation Manager. Hope to show you lots more eye candy next week too :)

If you're a patron, or have bought any of our books or plugins, then thank you! It is what's helping us both work on this full time right now. I'm constantly being asked when v3 will be released, and I still can't give a solid answer to that, but what I can say is that it genuinely feels like we're making awesome progress on a very regular basis, and that we're building a really solid and tidy internal structure. There is lots more work to be done of course, but it's an exciting journey for sure!

Phaser 3 Mailing List and Developers Guide

If you're interested in helping evolve the shape of Phaser 3, then please join the Phaser 3 Google Group. Discussions this week have included varying render loops. The group is for anyone who wishes to help shape what the Phaser 3 API and feature-set will contain.

The Phaser 3 Developers Guide is available. Essential reading for anyone who'd like to help build Phaser 3.