Events

Events form the building blocks for all Void's content, it follows a publish-subscriber model for transmitting information between entities.

Publishing

An event typically follows the following structure

data class TestEvent(val message: String) : Events

Event instances are created for one-time use and can be emitted using any entities Events class. Any type of event can be emitted to any entity.

entity.events.emit(TestEvent("Hello World!"))

Subscribing

Events can be subscribed to at a global level, as shown below, and will be called if an event is emitted from an entity when both types match.

on<Entity, TestEvent> { entity: Entity ->
    val event = this
    println(event.message)
}

Events can also be subscribed at a local level allowing subscription at an individual entity level. Local subscriptions have to be carefully managed and removed when there are no longer needed to prevent leaking memory.

val handler = entity.events.on<Entity, TestEvent> { entity: Entity ->
    val event = this
    println("Only ${entity.name} says ${event.message}")
}

entity.events.remove(handler)

Advanced

Both global and local scope subscriptions can be filtered to further refine when a subscription is activated

on<Entity, TestEvent>(condition = { message.endsWith("bye") }) {
    println("Goodbye!")
}

Subscriptions can also be given a Priority so that they execute in a specified order.

on<Entity, TestEvent>(priority = Priority.HIGHEST) {
    println("First!")
}

Events are a simple yet powerful way of creating content for your server

on<Finished>({ you -> you.understoodWikiPage }, Priority.HIGH) { you: Reader ->
    println("Get creating!")
}