Events

Overview

The event system allows registering callbacks—aka event listeners—for actions—aka events—triggered by other code. Events are identified by a string name, and event listeners are registered to handle all events of some name. Events often pass arguments to their callbacks in addition to acting as basic execution hooks. To add an event listener, use io.github.sianabeeblebrox.Specter.EVENT_BUS.on(String name, Closure callback).

Built-In Events

• 'premain' - Fired once after loading all scripts right before starting target program
  • Parameters:
    • java.lang.instrument.Instrumentation
  • Expected Return Value: None
• 'main' - Fired at the very start of each public static void main(String args[]) found in target program
  • Parameters:
    • java.lang.Class<?> - The class containing the main method that triggered the event
    • java.lang.String[] - The args from the calling method
  • Expected Return Value: None

Custom Events

Custom events may be dispatched by calling io.github.sianabeeblebrox.Specter.EVENT_BUS.dispatch(String name, Object... args).

Examples

import io.github.sianabeeblebrox.specter.Specter

Specter.EVENT_BUS.on('player_join', { player, world ->
  println "Welcome $player.name"
})

// ...

Specter.EVENT_BUS.dispatch('player_join', player, world)

Notes

• on() has an overload that accepts a priority to determine the order in which event listeners are called (smaller integer is higher priority and run first, listeners of the same priority are called in the order they were added).
• Event listeners can return a value; the first non-null value if any is returned to the calling dispatch() and stops execution of further event listeners for this event.
• Events listeners for an event are run on the thread that called dispatch().
• Adding an event listener using on() returns an event listener handle with a remove() method that can be used to deregister the event listener.
• For more details, see the Javadoc.