Work In Progress
This documentation is in beta. It's missing lots of content, search is broken, and many links go nowhere. These problems will be fixed before release, but there's plenty of work left!
Skip to main content

Event Handlers

When something happens on Discord, or in your bot's lifecycle, it will fire an event. You can define event handlers in your extensions to react to these events.

event<MessageCreateEvent> {
    action {
        if (event.message.content == "hello") {
            event.message.respond("Hello!")
        }
    }
}

Extension API​

Builders​

event<...>(...) { ... }Receiver: EventHandler<T>Function Returns: EventHandler<T>

Use this builder to register an event handler.

Type Parameters
TType: Event

The event type you'll be handling. You can use a less specific generic if you want to handle multiple event types.

Function Arguments
constructorType: (Extension) -> EventHandler<T>Default: ::EventHandler

If you need to use a custom event handler subtype, you can pass the constructor here.

Note: You shouldn't need to use this in most situations. This is for advanced use-cases that the existing event handler type isn't suitable for.

Usage​

To create an event handler, use the event {} builder detailed above. All event handlers must define an action.

Builders​

action { ... }Receiver: EventContext<T>

Register your event handler's action block, defining what it will do when your bot fires a matching event. See the context API section for more information on what you can do here.

check { ... }Receiver: CheckContext<T>

Register a check, which must pass for the event handler's action block to execute.

Functions​

You can use these utility functions in your action {} block.

Event.getLocale(...)

Retrieve this event's locale, calculated by your bot's locale resolvers.

This function's output is cached.

Event.translate(...)

Quickly translate the given translation key using the event's resolved locale.

Arguments
keyType: Key

Translation key object to translate.

replacementsTypes:Array<Any?>Map<String, Any?>Default: arrayOf()

Optionally, an array or map of placeholders to replace in the translation string.

Context API​

The action { } builder is a receiver against the EventContext type. This type provides a set of APIs, along with those provided by the base TranslatableContext type (TODO), which allow your bot to respond to events.

open class EventContext : KordExKoinComponent, TranslatableContext
Type Parameters
TType: Event

The event type you're handling, provided by your event handler.

Constructor Arguments
open val cacheType: MutableMap<String, Any>

Map representing a data cache shared with the event handler's registered checks.

open val eventType: T

Object representing the event you're currently handling.

open val eventHandlerType: EventHandler<T>

The event handler that was triggered by the event.

val sentryType: SentryContext

A Sentry context (TODO) you can use to keep track of what happens in your event handler.

Extra Data​

All Kord Extensions events extend the Kord Event type, which provides a customContext property. Your bot will store a MutableMap<String, Any> here for all events it processes, which allows you to store extra data on event objects as part of processing.

Kord Extensions provides some extra APIs that make using this more convenient.

Types​

The sections below use the following generic types for brevity.

AType: Map<String, Any?>

Type representing all string-keyed maps.

MType: MutableMap<String, Any>

Type representing only mutable string-keyed maps without nullable values.

Properties​

Event.extraDataType: M

Convenient access to the extra data map stored in customContext.

Functions​

A.getOf<...>(...)Returns:T

Attempt to retrieve a value from the map stored with the specified key, casting it to the given type T and returning it.

This function will throw exceptions:

  • ClassCastException - Thrown when the value stored under the given key can't be cast to T.
  • IllegalArgumentException - Thrown when the map doesn't contain the given key.
Type Parameters
reified TType: Any

Type to cast the value to.

Function Arguments
keyType: String

Key to attempt to retrieve a value for.

A.getOfOrDefault<...>(...)Returns:T

Attempt to retrieve a value from the map stored with the specified key, casting it to the given type T and returning it.

If the map doesn't contain the given key or the value can't be cast to T, this function will return the specified default value.

Type Parameters
reified TType: Any

Type to cast the value to.

Function Arguments
keyType: String

Key to attempt to retrieve a value for.

defaultType: T

Default value to return if the key is missing, or the value is the wrong type.

M.getOfOrDefault<...>(...)Returns:T

Attempt to retrieve a value from the map stored with the specified key, casting it to the given type T and returning it.

If the map doesn't contain the given key or the value can't be cast to T, this function will return the specified default value, optionally storing it under the given key if store is true.

Note: This function variant only supports mutable string-keyed maps with non-nullable values. If your map may contain null values, you can only use the getOfOrDefault function specified above.

Type Parameters
reified TType: Any

Type to cast the value to.

Function Arguments
keyType: String

Key to attempt to retrieve a value for.

defaultType: T

Default value to return if the key is missing, or the value is the wrong type.

storeType: BooleanDefault: false

Set this to true to store the default value in the map under the given key, when the default value would be returned.

A.getOfOrNull<...>(...)Returns:T?

Attempt to retrieve a value from the map stored with the specified key, casting it to the given type T and returning it.

If the map doesn't contain the given key or the value can't be cast to T, this function will return null.

Type Parameters
reified TType: Any?

Type to cast the value to.

Function Arguments
keyType: String

Key to attempt to retrieve a value for.