Events

This page covers the shape of a DiSky event handler: the on ...: line and its seen by filter, the event- values and named expressions every handler can read, how values fetched from Discord reach your code, and why Discord events cannot be cancelled. You're assumed to have a bot logged in as "my-bot" (see Starting a bot).

How an event handler works

A DiSky event is a regular Skript event: on <event>: followed by a trigger. Every event pattern accepts an optional seen by "<bot name>" suffix, so on message received seen by "my-bot": only fires for the bot logged in under that name (see multiple bots); without it, the handler fires for every bot. Whatever the event, the bot that saw it is event-bot.

on message received seen by "my-bot":
    if discord content of event-message is "!ping":
        reply with "Pong from %event-bot% in %event-channel%!"

DiSky receives the event on Discord's own thread, filters it by bot, builds the event values, then hands the trigger to the main server thread: your handler runs on the main thread, like any Bukkit event, so it can touch players, blocks and variables freely. Effects such as reply with block the trigger until Discord confirms, which is covered in cache and await.

Event values

The entities involved in an event are exposed the Skript way, as event-<type>. Which ones exist depends on the event; the generated events reference lists them per event. A value that does not apply is none, not an error: event-guild and event-member are none when a message or reaction comes from a private channel.

A channel is registered once per channel type, so the same event also answers to event-textchannel, event-voicechannel, event-threadchannel, event-forumchannel, event-category and the other channel types: the typed form is set when the channel really is of that type and none otherwise. Use event-channel when the type does not matter.

on message received seen by "my-bot":
    if event-threadchannel is set:
        reply with "This message was sent in a thread"

Named event expressions

Some event data has no event-<type> form, because it is plain text, a list, or would clash with another value of the same type. Those are exposed as expressions with their own name, valid only inside their event: using one anywhere else is a parse error saying the expression can only be used in that event.

on button clicked seen by "my-bot":
    if click id is "confirm":
        reply with "Confirmed by %event-user%"

Old and new values

Update events fire after the change and expose both sides of it: the current value under a plain name, the previous one under the same name prefixed with old (past and previous are accepted too). The entity itself is already updated, so nickname of event-member reads the new value; only the old expression still knows the previous one.

on guild member nickname change seen by "my-bot":
    send "%event-member%: '%old member nickname%' -> '%member nickname%'" to console

Values fetched from Discord

A few values are not part of what Discord sends with the event: the message behind a reaction, or the user and member behind a poll vote. DiSky fetches them from Discord on a background thread before the trigger starts and stores them on the event, so inside the handler they are ordinary values.

on reaction add seen by "my-bot":
    send "%event-user% reacted to '%discord content of reaction message%'" to console

The await rules apply to what you do inside the handler, never to the event's own values: an event value never needs await.

Events are not cancellable

An event that comes from Discord cannot be cancelled: Discord has already applied the change by the time your handler runs. Writing cancel event in such a handler does not load; Skript reports at parse time that the event cannot be cancelled. React instead of cancelling: delete the message, remove the role, kick the member.

on message received seen by "my-bot":
    if discord content of event-message contains "spam":
        destroy event-message

The exceptions are the events DiSky fires itself, before running a command it declared: on discord command used, where cancelling stops the command (see listing and events), and on slash command cooldown, where cancelling lets the command run despite its cooldown (see command settings).

Event families

DiSky fires 123 events, generated from the same descriptors as the events reference, which stays the complete list. They fall into a dozen families; the values named below are the ones most of the family shares.

function writeDebug(event: text, data: text):
    send "[DiSky-evt] %{_event}% -> %{_data}%" to console

on member joined guild seen by "my-bot":
    writeDebug("member join", "member=%event-member% guild=%event-guild%")