EventEntry

The EventEntry is used as a starting point for any sequence. It can have external event listeners listening to events and trigger based on that.

Usage

ExampleEventEntry.kt

@Entry("example_event", "An example event entry.", Colors.YELLOW, "material-symbols:bigtop-updates")
class ExampleEventEntry(
    override val id: String = "",
    override val name: String = "",
    override val triggers: List<Ref<TriggerableEntry>> = emptyList(),
) : EventEntry

To listen to an event, you must create a function that is annotated with @EntryListener. The great thing about kotlin, is that this can be done in the same file as the entry.

ExampleEventEntry.kt

@EntryListener(ExampleEventEntry::class)
fun onEvent(event: SomeBukkitEvent, query: Query<ExampleEventEntry>) {
    // Do something
    val entries = query.find() // Find all the entries of this type, for more information see the Query section
    // Do something with the entries, for example trigger them
    entries.triggerAllFor(event.player, context())
}

The function will automatically be registered as a listener for the event by Typewriter and be called when the Bukkit event is trigger. An optional Query parameter can be added to easily fetch all the different event entries.

Entry Context Variables

Sometimes you want to pass some information to the context so that subsequent entries can use it.

InteractionContextExamples.kt

enum class ExampleEntryContextKeys(override val klass: KClass<*>) : EntryContextKey {
    // The two `String::class` have to be the same.
    // The @KeyType is for the panel to know
    @KeyType(String::class)
    // The type here is for casting during runtime
    TEXT(String::class),

    @KeyType(Int::class)
    NUMBER(Int::class),

    // More complex types are also allowed.
    @KeyType(Position::class)
    POSITION(Position::class)
}

InteractionContextExamples.kt

@GlobalKey(Int::class)
object LuckyNumberKey : GlobalContextKey<Int>(Int::class)

InteractionContextExamples.kt

@Entry(
    "example_event_with_context_keys",
    "An example event entry with context keys.",
    Colors.YELLOW,
    "material-symbols:bigtop-updates"
)
// This tells Typewriter that this entry exposes some context
@ContextKeys(ExampleEntryContextKeys::class)
class ExampleEventEntryWithContextKeys(
    override val id: String = "",
    override val name: String = "",
    override val triggers: List<Ref<TriggerableEntry>> = emptyList(),
) : EventEntry

@EntryListener(ExampleEventEntryWithContextKeys::class)
fun onEventAddContext(event: SomeBukkitEvent, query: Query<ExampleEventEntryWithContextKeys>) {
    val entries = query.find()
    entries.triggerAllFor(event.player) {
        // Make sure these values are drawn from the event.
        // You MUST supply all the context keys.
        ExampleEntryContextKeys.TEXT withValue "Hello World"
        ExampleEntryContextKeys.NUMBER withValue 42
        // You can also use += to assign the value to the key
        ExampleEntryContextKeys.POSITION += Position.ORIGIN

        // Or we can assign any global key to it.
        LuckyNumberKey += 69
    }
}

Event entries are often the starting point for interaction context, capturing initial data from player actions and making it available to subsequent entries in the sequence.

For more information about working with interaction context, see the Interaction Context guide.

CancelableEventEntry

Sometimes you may want the underlying Bukkit event to be cancelled after triggering your entries. For this the CancelableEventEntry interface extends EventEntry with a single cancel field.

ExampleEventEntry.kt

@Entry("example_cancelable_event", "An example cancelable event.", Colors.YELLOW, "material-symbols:block")
class ExampleCancelableEventEntry(
    override val id: String = "",
    override val name: String = "",
    override val triggers: List<Ref<TriggerableEntry>> = emptyList(),
    override val cancel: Var<Boolean> = ConstVar(false),
) : CancelableEventEntry

Inside your event listener you can inspect all matching entries and decide whether to cancel the Bukkit event.

ExampleEventEntry.kt

@EntryListener(ExampleCancelableEventEntry::class)
fun onCancelableEvent(event: SomeBukkitEvent, query: Query<ExampleCancelableEventEntry>) {
    val entries = query.find().toList()
    entries.triggerAllFor(event.player, context())

    if (entries.shouldCancel(event.player)) {
        event.isCancelled = true
    }
}