Interfacing with the Terra API is primarily done through events.

The Event Manager#

The base for working with events in Terra is the EventManager. The Event Manager contains methods to:

  • Call events (#callEvent)

  • Register event handlers (#registerHandler)

  • Access event handlers (#getHandler)

Accessing the Event Manager#

The Event Manager is accessed through the Platform instance:



To access the Platform instance in your addon, use Dependency Injection.


You’ll generally want to register event listeners in your addon’s entry point(s).

Event Handlers#

Event handlers provide API to register event listeners. Terra provides a single event handler by default, the FunctionalEventHandler. Addons are able to register custom event handlers if they wish to use different APIs to register events, for example, annotated methods.

Accessing an Event Handler#

To access an event handler, simply pass its Class instance into EventManager#getHandler(Class).

Here’s an example for accessing the default FunctionalEventHandler:


The Functional Event Handler#

The Functional Event Handler is the default Event Handler provided by Terra. Most addons will want to use this event handler. This handler provides a functional-style API for registering events using Java’s lambda expressions.

Registering a Listener#

When registering an event listener with the Functional Event Handler, invoke the FunctionalEventHandler#register(BaseAddon, Class) method. This will return an instance of EventContext which you can use to build your listener.

Adding an Action to the Listener#

To add actions to your event listener, append EventContext#then(Consumer) calls. these operations will execute consecutively, with the consumer accepting the event instance.


platform.getEventManager()                        // Get the event manager.
        .getHandler(FunctionalEventHandler.class) // Get the functional event handler.
        .register(addon, SomeEvent.class)         // Register a listener for SomeEvent, to our addon.
        .then(someEventInstance -> {              // Perform an action when the event is fired.
  "Handling Some Event!");
  "Event says: {}", someEventInstance.getSomething());

This example registers a listener for SomeEvent. When the event is called, the result of the event instance’s #getSomething() is logged.