Event Handling

The event system was created to allow the server's code to perform certain tasks when events occur. This allows us to perform tasks that may have nothing at all to do with the event triggerer.

Ex: The PlayerStatsManager can handle an InventoryChangeEvent to update the player stats if the player's equipment inventory changes. Without the event system, such an operation would be much more difficult.

Currently, the event system is only available on the Server with no plans for it being implemented on the Client as it is not required.

This wiki page will explain how the priorities work then demonstrate how to handle events.

Implementing it

Event handling is fairly straight forward but there are a few things to remember to do otherwise it will not work.

First, you need to create an EventHandler object using the EventHandler interface. You can do this by either making the class, in which you would like to handle events, implement the interface, or you can create it on the fly. Both methods are perfectly acceptable, each with pros and cons. Just remember to properly follow the next steps.

"Implements" method:

public class PlayerStatsManager implements EventHandler {

}

On the fly:

public class PlayerStatsManager {

  EventHandler eventHandler;

  public PlayerStatsManager() {
    eventHandler = new EventHandler() {


    };
  }

}

Second, you must add the EventHandler to the EventManager so that when events are triggered, the manager knows it exists so it can send it events to handle. Here is how to do it in both methods.

"Implements" method:

this.addToEventManager();

On the fly:

eventHandler.addToEventManager();

Next, we need to tell the EventManager which events the handler will be handling and with what priority. By default, event handlers have a NONE priority for all event types meaning that the EventManager will simply skip over them. There are 2 methods to doing this, one of which is just a shorthand for faster coding.

Method 1: Specifying EventTypes to handle in the EventHandler.addToEventManager() method. This way will, by default, register the event handler to handle the specified events using the READONLY_NORMAL priority.

  eventHandler.addToEventManager(EventType.PlayerInventoryChange);

Method 2: Specifying EventTypes and their EventHandlerPriorities explicitly. This will allow the EventHandler to using the Editable priorities.

  eventHandler.registerEventPriority(EventType.EntityMove, EventHandlerPriority.EDITABLE_HIGH);

Now, we can finally setup the code to handle events! This is fairly easy to do. You can either for in the EventHandler class and copy the default method for the event you want, but the easiest way is to generate the method. In Eclipse, you can press ctrl-space to open a list of methods that can be generated and inherited from super types. In the end, it should look like this:

"Implements" method:

public class PlayerStatsManager implements EventHandler {

  Player player;

  public PlayerStatsManager(Player player) {
    this.player = player;
    this.addToEventManager();
  }

  public boolean onPlayerInventoryChanged (PlayerInventoryChangeEvent event) {
    if (event.getPlayer() == player) {
      //Handle event here...
      return true
    }
    return false;
  }

}

On the fly:

public class PlayerStatsManager {

  EventHandler eventHandler;
  Player player;

  public PlayerStatsManager(Player player) {
    this.player = player;
    eventHandler = new EventHandler() {

      public boolean onPlayerInventoryChanged (PlayerInventoryChangeEvent event) {
        if (event.getPlayer() == player) {
          //Handle event here...
          return true;
        }
        return false;
      }

    };
    eventHandler.addToEventManager();
  }

}

All EventHandler code blocks return boolean value. This represents whether the event was handled in one way or another. This is currently not used for anything, but it may be in the future so it is good practice to return true or false depending on if the event was handled, as demonstrated above.

At this point the EventHandler should work! But, there is one last important step that is not required to get event handling to work, but should always be done. The EventHandler should be removed from the EventManager to free up memory space, as well as prevent the event handler from continuing to handle the event even when it is no longer needed.

When appropriate, call the EventHandler.removeFromEventManager() method to do this. Make sure to do this when you are sure the event will no longer be used. For example, the PlayerStatsManager removes itself from the EventManager when the player leaves the game.