Phaser Performance in a Shoebox

Using seperated images instead of texture atlas may cause your Phaser game to perform badly. I would be discussing how packing images in texture atlas helped save a game from crashing on older devices.

So a few weeks ago, I was working with a group of Phaser developers on the performance of their game. They were running into a pitfall where the game ran well on desktop browser but laggy on mobile and crashed on older devices. Reasons for this problem are mostly related to the amount of display objects, garbage collection and memory consumption.

In this post, I would be talking about how packing the images in texture atlas helped with the memory problem.

Texture Atlas is a type of image packaging created by merging multiple images (called frames) into one by putting them side by side on a single canvas. Unlike normal spritesheet, which requires all the frames to be identical in dimension and presents them as a table, texture atlas uses a separated file to record the dimension and position of each frame.

With many processors, an image file is saved in the memory as a texture with dimension of a power of two (aka POT, eg. 2, 4, 8, 16, 128, 256, 512, 1024, 2048, etc.). For example, an image of size 25×129 (3225 pixels) will be saved on a texture of 128×256 (32768 pixels), producing a waste of 9 times the original image. The more images like this are loaded, the more waste the processor produces and the more memory the game uses.

However, if we stack 5 images like that on top of each other into a single image of size 125×129 (16125 pixels), this new image can still be saved in the memory at 128×256, which only produce a waste of 2 times the original size. This new image is called a texture atlas.

A texture atlas includes two parts: An image file (normally png), and an information file (normally json or xml). In this post, I would write about generating texture atlas for Phaser using a software called Shoebox with png image file format and json information file format.

ShoeBox is a free Adobe Air based app for Windows and Mac OSX with game and ui related tools. Each tool uses a drag and drop – or clipboard interaction for a quick workflow.

The software can be downloaded here.

Since none of the original information file templates exported by Shoebox are compatible with Phaser preloading process, the app needs to be reconfigured as follow:

The easy way: Download Phaser.sbx file here on my github repository. Double click the file to load the configuration.

The hard way: Not like it matters, this is just an under the hood explanation. I actually based on an exported file from Adobe Flash:

1. Right click on Spritesheet button on the home screen of Shoebox to open the Spritesheet settings; Change the File Format Loop setting to:

   \t{\n\t\t"filename": "@id",\n\t\t"frame": {"x":@x, "y":@y, "w":@w, "h":@h},\n\t\t"spriteSourceSize": {"x":@fx,"y":@fy,"w":@fw,"h":@fh},\n\t\t"sourceSize": {"w":@fw,"h":@fh}\n\t}@,\n
   

   The code above is the template for the information of each frame. /n and /t are newline and tab. Any thing with @ pre-fix are variable provided by Shoebox (check the list out at the documentation page).

2. Change the File Format Outer setting to:

   {\n"frames": [\n@loop\n],\n"meta": {\n\t"image": "@TexName",\n\t"size": {"w": @W, "h": @H},\n\t"scale": "1"\n}\n}
   

   To create a texture atlas, you can either drag a group of images or a folder on to the Spritesheet button on Shoebox home screen and hit Save and you’re done.

In the case of the game I mentioned, this decreased the memory consumption from above 250Mb to around 80Mb and saved the game from crashing on older devices like iPhone 4. However, the process of changing the code from using images to atlas/spritesheet was a long, tired and time consuming process.

So next time you make a game, pack your sprites from the very start, it definitely worths your overhead time.