Event System

Introduction

The game has an event system, which allows entities to trigger or listen to events. Every entity has an event system system attached, which you can access with entity.getEvents(). Events are referenced by name, as strings.

Events can be received with entity.getEvents().addListener("event name", function). Whenever that event is triggered on the entity, the function you provide will be called with the event's arguments.

Events can be triggered with entity.getEvents().trigger("event name", args). An event can have 0 or more arguments of any type.

Note: You must ensure that the arguments given to trigger(arg0, arg1, ...) match those in the listeners. If not, this will cause an exception.

Usage

// Listen to a collision event using Java lambda syntax. Whenever a 
// collision happens, the print statement will be called.
player.getEvents().addListener("collisionStart", (Fixture other) -> {
  System.out.println("I just hit something!");
});

// Listen to a health change event using Java's method reference operator to
// call the updateUI() function every time health changes
player.getEvents().addListener("healthChanged", this::updateUI);

// Trigger an attack event with a value of 10
player.getEvents().trigger("attack", 10f);

// Trigger a player death event with two arguments. Any listeners must
// accept these both as parameters!
player.getEvents().trigger("playerDeath", enemy, false);

Behind the Scenes

Common Terminology

You might recognise event systems by one of their other names:

• Publish / subscribe pattern
• Observer pattern

The idea is the same, it just depends who you ask!

What's the point of events?

Events are a widely used technique to keep systems separate and modular. A common example is in UI. Let's say that when the player dies, we want to show a death popup window that lets you choose whether to retry or quit. How does our popup class DeathPopupWindow know about the player's death, which is processed in the Player class?

The obvious solution is to add the code to trigger the window into Player, something like this:

class Player {
  public void processDeath() {
    ...
    deathPopup.activate();
    ...
  }
}

This works, but it should be clear that this violates good code principles. The player class shouldn't need to know anything about the UI. You can also imagine how big this would get when we start to add things like player health UI, or inventory. Events let us decouple this code, by letting the player say "If anyone is listening: I just died". It then becomes the responsibility of DeathPopupWindow to listen to this event and activate itself.

The refactored code would look like this:

class Player {
  public void processDeath() {
    ...
    entity.getEvents().trigger("death");
    ...
  }
}

class DeathPopupWindow {
  public DeathPopupWindow() {
    player.getEvents().addListener("death", this::active);
  }
}