Using event listeners

Making an event callback

An event callback is an instance method annotated with EventCallback. For it to be registered as one, the first parameter must also be of a type extending Event.

Event callbacks are registered by calling the PluginHelper#registerEventClass(instance) method in a plugin's Plugin.Setup annotated method, where instance is an instance of a class containing an event callback.

Let's try this in practice:

@Plugin(
        id = "MyPlugin",
        name = "My Plugin",
        version = "1.0.0",
        description = ""
)
public class MyPlugin {

    @Plugin.Helper
    public PluginHelper helper;

    @Plugin.Setup
    public void setup() {
        helper.registerEventClass(this);
    }

    @EventCallback
    public void messageReceived(MessageReceivedEvent e) {
        System.out.println(e.message.getSender() + ": " + e.message.getMessage());
    }
}

Here we define an event callback for the MessageReceivedEvent, and then register it on plugin setup. When we receive a message in-game, the callback will be triggered and we'll see the message sender and their message separated by a colon in the console output.

Side information

The callback calling process

The callback calling process is handled solely by the client. There are code transformers that inject calls to Event.callEvent(Event) in the OSRS gamepack, so that when that part of the OSRS code is called, a Wingman event is triggered. Rest assured knowing that the event system is quite optimized, so if no callbacks have been registered for an event, it won't try to invoke any.

The callback registering process

As stated above, callbacks need to be registered in the Plugin.Setup annotated method. Why you might ask? It's because event listeners are baked into an array after all of them have been registered. Simply put, the iteration of event callbacks is blazing fast because we don't need to make sure that the array isn't edited while it's being iterated over.