Starting a bot

This page covers creating a bot, logging it in under a name, the events that fire once it connects, and shutting it down. You're assumed to have DiSky v5 installed (see the installation guide) and a bot token from the Discord Developer Portal.

How logging in works

A bot starts as an empty, unconnected object. You configure it, give it a token, then log it in under a name; that name is how the rest of your scripts retrieve it later.

options:
    token: "YOUR-TOKEN"

command /startbot:
    trigger:
        set {_bot} to a new discord bot
        set token of {_bot} to {@token}
        login {_bot} as "my-bot"
        send "&7Logging in 'my-bot'..."

on unload:
    shutdown the bot named "my-bot"

Login runs in the background: the command returns immediately, and Discord validation happens off the main thread. If the token is empty or missing, or the bot fails to connect, DiSky prints a readable error to the console instead of the raw exception; nothing crashes. Once the connection succeeds, the bot is registered under its name and the bot named "my-bot" starts resolving to it anywhere in your scripts.

Lifecycle events

Three global events cover a bot's life. They fire for every bot that logs in, so filter with on ready seen by "my-bot": when you run more than one bot.

• on guild ready fires once per guild the bot is connected to, as each guild's data finishes loading.
• on ready fires once, after every guild has fired its own on guild ready, when the bot is fully connected.
• on bot shutdown fires once the bot's connection to Discord closes.

on guild ready:
    send "[DiSky] guild ready: %name of event-guild% on %event-bot%" to console

on ready:
    send "[DiSky] %event-bot% READY (%guild count of event-bot% guilds)" to console

on bot shutdown:
    send "[DiSky] %event-bot% SHUTDOWN" to console

Shutting down

shutdown the bot named "..." disconnects the bot and unregisters its name; it can be logged in again afterwards. Always pair a login with a shutdown, typically in an on unload: block so the bot disconnects cleanly when the plugin reloads or the server stops.

on unload:
    shutdown the bot named "my-bot"

Logging in a second, separate bot under a name that's already running does not raise an error: the new bot takes over that name in the registry, and the previous one keeps running in the background, no longer reachable by name. Always shut a bot down before logging in a replacement under the same name. Calling login again on the exact same bot variable while it's already connected is what actually fails, with a readable error in the console.

Errors you may see

Connection options such as intents, member cache policy and sharding are covered on the bot options page.