Phaser Sprite data objects

When making sprites for a game using Phaser ce as a framework, there is a standard way of setting some data on a per sprite bases. This is the Sprite.data object, an object that defaults to just a plain old javaScript object literal, and is not used my phaser itself internal. So when making a game this is what should be used to park any data, or methods that is part of the game logic that makes up the essence of the project for the sprites. For example if I am making some kind of strategy game that involves the use of a custom Enemy class that I made, then chances are I will be storing an instance of that Enemy Class as a property of sprite.data, or maybe even make sprite.data an instance of that class. In this post I will be writing about an example that will help explain this further.

1 - what to know first

This is a post on using the Sprite.data object for appending properties, and methods to a single Sprite object that are project specific in phaser ce. In this post I am using Sprites, and a solution for making a sprite sheet from canvas, as well as many other phaser ce related topics.As such this is not a getting started post on phaser ce, but just a post on one little topic when it comes to phaser ce game development.

1.1 - This is a phaser ce (2.x) post

In this post I am using phaser ce 2.11.0, not the latest release of phaser that major release is a complete rebuild from the ground up and the code here will break if trying to use it with phaser 3.

2 - Basic example of using a Sprite.data object

For a basic example of using the Sprite.data object I made a simple example that just involves moving a sprite back and forth on the screen using some properties and methods appending to the Sprite.data object.

2.1 - A helper for appending some stuff to Sprite.data

So for this very simple getting started example I made a helper in which I pass a reference to a Phaser.Game instance, and a sprite that I have made before hand, and the helper appends some values, and a method that can be used to accomplish the simple back and forth movement.

var setupDataObject = function (game, sprite) {
 
    // appending some values to the data object
    sprite.data.frame = 0;
    sprite.data.frame_max = 50;
    sprite.data.sprite = sprite;
    sprite.data.game = game;
 
    // step sprite movement method
    sprite.data.step = function () {
 
        this.per = this.frame / this.frame_max;
        this.bias = 1 - Math.abs(0.5 - this.per) / 0.5;
 
        this.sprite.x = this.game.world.centerX - 16 - 100 + 200 * this.bias;
        this.sprite.y = this.game.world.centerY - 16;
 
        this.frame += 1;
        this.frame %= this.frame_max;
 
    };
 
};

When I put together a state object that will make use of this helper I use this method to setup the sprites data object in the create method of the state object, and then call the step method in the update method of the state object.

2.2 - Making a sprite sheet with canvas

For very basic examples like this I just use some very simple solid color box sprite sheet, so a canvas solution like this will work fine.

// make a sprite sheet
var mkSheet = function (game) {
 
    // sprite sheet generated by canvas
    var canvas = document.createElement('canvas'),
    ctx = canvas.getContext('2d');
    canvas.width = 64;
    canvas.height = 32;
 
    // blue frame
    ctx.fillStyle = '#0000ff';
    ctx.fillRect(0, 0, 32, 32);
 
    game.cache.addSpriteSheet('sheet-block', null, canvas, 32, 32, 2, 0, 0);
 
};

This kind of solution can also work for making sprite sheets that are a little more involved as well, for more on that topic you might want to check out my post on making sprite sheets with canvas.

2.3 - The Phaser.Game instance, and single state object.

So now it is time to tie everything together with a Phaser.Game instance and just a single state object for now. After setting up my Phaser.Game instance I create a single state object that I will call ‘basic’ and in the create method of this basic state I create my sprite sheet with the canvas solution helper described above. After I have my sprite sheet in the cache, I use it to create and skin a new sprite, and give it a name. I then of course use my setupDataObject method to append what I need to the sprites data object my passing the Phaser.Game instance and a reference to the sprite as well. Then in the update method of the basic state I call my step method that is attached to Sprite.data to step the movement of the sprite.

var game = new Phaser.Game(320, 240, Phaser.AUTO, 'gamearea');
 
game.state.add('basic', {
 
    create: function () {
 
        // make my sprite sheet
        mkSheet(game);
 
        // make a sprite using my sprite sheet
        var sprite = game.add.sprite(0, 0, 'sheet-block');
        sprite.name = 'bx';
 
        // seup the data object
        setupDataObject(game, sprite);
 
    },
 
    update: function () {
 
        var sprite = game.world.getByName('bx');
 
        // calling my step method
        sprite.data.step();
 
    }
 
});
 
game.state.start('basic');

When this example is up and running the box move back and forth as expected, using properties and a method that are tucked away into its data object.

3 - Conclusion

So the Sprite.data object is the phaser ce standard way of assigning any kind of properties or methods that should be attached to a sprite insistence. One way or another there is often a need to do something like this for just about any phaser ce project, so I might as well stick to the common standard way of doing it via Sprite.data.