February 2015

Using gulp to automate texture atlas and sprite sheet creation for Phaser

I’ve always used TexturePacker to create texture atlases for Phaser. It’s an awesome visual tool that’s really easy to use to create atlases and sprite sheets, but I’m a command line guy and always looking to save time and be more efficient.

While I’ve been working on Crash Landing, I hesitate to update or add new sprites because of the pain of having to go through all the steps to update or add a sprite. It may sound a bit silly, but it really is time consuming having to open up the program, load the old atlas, add or update it and save it back out. I’d rather spend this time coding, or creating new sprites. My dislike for this process makes me not want to create new sprites and iterate quickly.

I first looked into automating TexturePacker, which does have a command line interface, but at the same time being a standalone program I’d have to write a bash script to automate the process, or find a gulp package to interact with the command line (seems a little messy). I plan on building a full workflow for automating more tasks using Gulp, so I did a little research and found a working implementation using existing Node.js packages.

gulp.spritesmith and spritesmith-texturepacker

gulp.spritesmith is a gulp plugin for spritesmith, a node utility to create spritesheets, and spritesmith-texturepacker is an export template for spritesmith to create a .json file compatible with TexturePacker, and thus Phaser.

So let’s get to it. If you’re familiar with gulp already it’s pretty simple to set up. I’m assuming you’ve got npm and are familiar with installing packages. You’ll need gulp in your project, both spritesmith packages above, and I’m also using imagemin to optimize the resulting atlas image file.


npm install --save-dev gulp gulp-spritesmith spritesmith-texturepacker gulp-imagemin

Once installed we just need to create our gulp file with a task to create the texture atlas image and json file.


var gulp = require('gulp');
var spritesmith = require('gulp.spritesmith');
var imagemin = require('gulp-imagemin');
var texturepacker = require('spritesmith-texturepacker');

gulp.task('sprites', function() {
    var spriteData = gulp.src('src/images/sprites/*.png')
        .pipe(spritesmith({
            imgName: 'sprites.png',
            cssName: 'sprites.json',
            algorithm: 'binary-tree',
            cssTemplate: texturepacker
    }));
    spriteData.img.pipe(imagemin()).pipe(gulp.dest('build/images/'));
    spriteData.css.pipe(gulp.dest('build/images'));
});

I’ve created a task (sprites) that pulls all .png files from the src directory, pipes it into spritesmith with the texturepacker template. I save the return value of the operation to spriteData, and individually pipe them out so I can run the image through imagemin.

Now anytime I need to add or update a sprite, I just drop it into the source file and run ‘gulp sprites’.

The .json file outputted will be in JSON hash format. In order to load the spritesheet into a Phaser project you’ll use the atlasJSONHash method. I’m using this:


this.load.atlasJSONHash('sprites', 'build/images/sprites.png', 'build/images/sprites.json');

Each image is saved as a frame in the .json file. You’ll refer to it by the filename minus the extension. As an example, I’m loading the standing.png frame into my player class with the following:


Phaser.Sprite.call(this, game, x, y, 'sprites', 'standing');

So there it is, a simple way to speed up your workflow. Works great if you like to incrementally build out you’re Phaser game like I do.

Early intro screen to Crash Landing

Crash Landing

Crash Landing (tentative title) is an HTML5 game I created during Ludum Dare 29.  The game is written for the browser in JavaScript with a little help from the Phaser.js game framework.

The theme for Ludum Dare 29 was ‘Beneath the surface’, so I created a simple platformer where you must move fast through the level while the ground randomly explodes beneath you.

I stopped working on Crash Landing after the compo, but recently decided it was an idea worth finishing. As I build the game and refactor the code (it’s a horrifying mess), I’ll be writing about various things I’ve learned about Phaser.js, JavaScript, and anything else I learn along the way over on the blog.

Play the most recent build of the game here: Crash Landing

The code is all available on the GitHub repo.