dispatching events

Phaser 3 Dispatching Custom Events

One of the most useful features of Flash/Actionscript was the ability to dispatch custom events. Phaser does have an event class built-in and with a little ES5 magic, we can easily create a global messaging system.

This post is part of a series of building a platform game in Phaser 3. You can find the start of the posts here. It also uses the Utility template that helps in scaling and positioning in Phaser.

Events vs Callbacks

A callback is where you inject a function into a class to be called when the class has finished doing something.

myClass.onDone=this.setUpTanks();

I’m sure you’ve used a lot of callbacks in your Phaser games already. Because you have declared the instance of the class in the same class or scene as your callback function, all the code is child-parent dependent on each other. You couldn’t for example, set up the callback in one class, and have the callback function exists on another. It is also a one-to-one communication. You can’t call 2 different functions in 2 different classes.

With events, however, you can have a global messaging system. It works by setting up listeners and then broadcasting those messages when something happens

Making the Event Dispatcher class

Phaser 3 has a built event system called the EventEmitter. We are going to use that EventEmitter to make our own class that extends it. We will then use that class as a singleton. Make a file called EventDispatcher.js

class EventDispatcher extends Phaser.Events.EventEmitter {

}

What is a singleton?

A singleton is a special type of class that only has one instance. This allows the class to be used in a game-wide manner without using global variables.

Instead of declaring a new instance, we use a static function called getInstance();

Making the singleton

First, we declare a variable called instance in the file, but outside of the class. This is a module-level variable that will be accessible anywhere inside the class.

What is a Module level variable?

Each module has its own top-level scope. In other words, top-level variables and functions from a module are not seen in other scripts.

source: https://javascript.info/modules-intro
let instance = null;
class EventDispatcher extends Phaser.Events.EventEmitter {

}

Next, we add the constructor and call the super, that will call the constructor in the EventEmitter

let instance = null;
class EventDispatcher extends Phaser.Events.EventEmitter {
    constructor() {
        super();       
    }

Here is where the magic happens in a singleton. We make a static function. A static function can only be called on the class itself, not the instance(copy) of the class.

We call the getInstance function, and if the instance does not exist (null) then we create a new copy of the EventDispatcher. This is the only time a new EventDispatcher will be made.

If the function is called a second time, the instance will not be null, and we will return the copy of the class we have already made.

static getInstance() {
        if (instance == null) {
            instance = new EventDispatcher();
        }
        return instance;
    }

Usage

To make an emitter we use this code

this.emitter=EventDispatcher.getInstance();

Dispatching Events

Events in Phaser 3 take two parameters.

  • Event Name – A string that is a name of the event
  • Event Parameters (optional) – any string, number, or object
this.emitter=EventDispatcher.getInstance();
this.emitter.emit("MY_EVENT","String_Data")
this.emitter.emit("ATTACK",{weapon:'sword',strength:5,monster:'dragon'})

Listen for Events

To listen for events, you just need to get the instance of the emitter and listen for the same string being emitted and link that to a function

this.emmiter.on(Event_NAME,function_name);

Here is how we could listen for the Attack event example above.

this.emitter = EventDispatcher.getInstance();
this.emitter.on('ATTACK',this.doAttack.bind(this));

doAttack(parameter)
{
  console.log('you attacked the '+parameter.monster+' with a '+parameter.weapon);
}

Leave a Comment