This specification aims to describe the behaviour of the PocketMine-MP event handling system.

Basics

In Minecraft gameplay it’s desirable to be able to react to things taking place (events). PocketMine-MP has a built-in events system which allows third party code to react to, modify the outcome of, and prevent the result of events.

To do this, the following procedure is followed:

  1. Something registers a handler for a given event.
  2. Just before the event takes place, the handler is called and passed an object containing information about the event. This allows handlers to react to, modify (and in some cases prevent) an event from taking place.
  3. The event takes place (or does not take place if cancelled) as defined by the object which contains the event information.

Limitations

Event handlers

As of 3.3.0, PocketMine-MP implements an architecture whereby a class implementing the pocketmine\event\Listener interface can have matching methods installed as handlers using reflection and annotations.

It is currently difficult and not worthwhile to install arbitrary callback handlers for events without a Listener object due to internal overcomplexity within PocketMine-MP. Because of this, this document will focus on event handlers defined by Listeners, and will not cover alternative ways of registering handlers.

Definitions

The pocketmine\event\Listener interface

This interface is implemented by classes which want to have matching methods within themselves (and their child classes) to be treated as event handlers on registration. Every method in a Listener-implementing class is checked as a candidate event handler.

Handler function names

Handler function names are completely ignored. Therefore, it doesn’t matter whether your handler is called onPlayerJoin() or iEatEnglishForBreakfast(); as long as the function meets the required criteria described below, it will be registered.

Handler registration criteria

To be considered as an event handler candidate, a Listener method MUST meet the below criteria:

The following are not mandatory but recommended:

Annotations controlling a handler function’s behaviour

Event handlers within a Listener can have their behaviour altered using doc-comment tags (otherwise known as “annotations”) as per the PhpDoc standard. The following annotations are respected for candidate handlers:

Event handler priority

Event “priority” is used to control the order in which multiple handlers of the same event will execute. This is mainly used for plugin interoperability. The pocketmine\event\EventPriority class declares a series of hardcoded priorities which handlers can use.

Note

Priority is a misleading name, because higher “priority” means that the handler should execute later in the sequence and not earlier. The reasoning for this is that higher order handlers “get the last word” over lower order handlers. This naming may be changed in future PocketMine-MP versions.

List of priorities

At the time of writing, the following priorities exist:

Caveats