Using Phaser.Signal to use and create events in phaser

Events are a big part of phaser ce game development, and the Phaser.Signal class is the phaser ce standard way of creating, and making use of events in phaser ce. There are many instances of Phaser.Signal to begin with in phaser that can be used to define some handers for when those events occur, but the class can also be used to define events as well. In this post I will be giving some use case examples of Phaser.Signal, including how to make one of my own, but I will not be covering all the different events that are built in.

1 - What to know

This is a post on using Phaser.Signal to create, and use events in phaser ce. Instances of this class pop up now and then whenever I want to do something that involves attaching an event handler for something like user input, or if a player sprite goes out of bounds for example. A Signal in phaser ce works very much like addEventListener in client side javaScript, allowing for me to attach many event handers to the same event.

1.1 - This is a phaser ce 2.x post

In this post I am using phaser Community Edition 2.11.0 of phaser.

2 - Example using some Signals

For this example I will be creating my own instance of Phaser.Signal to define my own event, as well as making use of a phaser ce built in event as well. This example will just be a sprite that falls down off screen, and when doing so will fire the phaser built in signal onOutOfBounds, doing so will result in the sprite taking damage, and will then start over at its starting location. Once the sprite looses all its health I will then use Signal.dispatch to fire mu own onGameOver event.

2.1 - The createOnGameOver helper

This helper when called will create my onGameOver event by calling Phaser.Signal with the new keyword. I can then save a reference to that signal somewhere such as to a game.data object. In this method I also add and event handler to the Signal with Signal.add

var createOnGameOver = function (game) {
 
    // create an signal
    var onGameOver = game.data.onGameOver = new Phaser.Signal();
 
    // append a handler
    onGameOver.add(function () {
 
        // display game over
        game.data.disp.text = 'Game Over';
 
        console.log('game over');
 
    });
 
};

2.2 - The onPlayerOutBounds helper

This helper will add an event handler to the onOutOfBounds event. The event will fire each time the sprite goes out of bounds, resulting in the sprite loosing health. I also check to see if the sprites health is completely gone, and if so fire my onGameOver event by calling the Signal.dispatch method that can be used to fire all handlers for the event.

var onPlayerOutBounds = function (game) {
 
    var player = game.data.player;
 
    // out of bounds signal
    player.checkWorldBounds = true;
    player.events.onOutOfBounds.add(function () {
 
        player.body.velocity.set(0, 0);
        player.x = 0;
        player.y = 0;
        player.damage(50);
 
        game.data.disp.text = 'health: ' + player.health;
 
        if (player.health <= 0) {
 
            player.health = 0;
 
            // call Signal.dispatch to fire the event
            game.data.onGameOver.dispatch(player);
 
        }
 
    });
 
};

2.3 - A helper for making a player sprite

Here I have a simple helper that will create the player sprite that will be used for this example. I set the health property here that will later be used with the damage method in my events above. For more information on why it might be a good idea to handle sprite health this way you can check out my post on sprite health and the damage method.

// make the player sprite
var mkPlayerSprite = function (game) {
 
    var player = game.data.player = game.add.sprite(0, 0, 'sheet-block', 0);
 
    player.health = 100;
 
    game.data.disp.text = 'health: ' + player.health;
 
    game.physics.enable(player);
    player.body.gravity.set(0, 100);
 
};

2.4 - Make a sprite sheet helper

For this simple example I just quickly made a sprite sheet with canvas. If interested in reading more on how to go about making sprite sheets this way there is my post on making sprite sheets with canvas.

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

2.5 - Tie everything together

Now it is time to tie everything together with a Phaser.Game instance and a single state object.

var game = new Phaser.Game(320, 240, Phaser.AUTO, 'gamearea');
 
game.state.add('game', {
 
    create: function () {
 
        // game data object to store game variables
        game.data = {};
 
        // text display object
        var disp = game.data.disp = game.add.text(10, 10, '', {
                fill: 'white',
                font: '15px courier'
            });
 
        // will be using physics
        game.physics.startSystem(Phaser.Physics.ARCADE);
 
        // make a sprite sheet
        mkSheet(game);
 
        // create on game over signal
        createOnGameOver(game);
 
        // make player sprite
        mkPlayerSprite(game);
 
        // on player out of bounds
        onPlayerOutBounds(game);
 
    }
 
});
 
game.state.start('game');

3 - Conclusion

So the Phaser.Signal class is what is used with many built in events in phaser ce, and can also be used to create and trigger your own custom events as well. Next you might want to read more about the events component that contains many built in events for display objects such as sprites, and text.