DiSky

DiSky is a Skript addon for writing Discord bots in Skript, on your Minecraft server. It is built on JDA: anything a JDA bot can do, DiSky aims to expose as Skript syntax.

This branch is DiSky 5, a rewrite of DiSky 4. It is in public beta: most of DiSky 4 is covered, the syntax is close but not identical, and V4 scripts need a few changes (see the migration guide).

• Syntax reference: atlas.disky.me
• Porting DiSky 4 scripts: migration guide
• Download: Modrinth
• Bugs and requests: GitHub issues

Requirements

• A Paper server, 1.21.5 or newer (or a Paper fork such as Purpur)
• Java 21 or newer
• Skript 2.16.1 or newer, with use type properties: true in its config.sk (the default)
• A bot token from the Discord Developer Portal

Installation

1. Put DiSky-<version>.jar in your server's plugins/ folder, next to Skript.
2. Restart the server.

DiSky has no config file. At each boot it writes plugins/DiSky/disky-syntax.json, a list of every syntax it registered; you don't need to touch it.

Anonymous statistics (FastStats)

DiSky reports anonymous usage statistics and errors to FastStats. Nothing is sent during the first start: submission begins after the next restart, so you can opt out beforehand.

What is sent:

• Usage: a random server id (regenerated if you delete it), the DiSky version, the Minecraft version, the server software and its version, online mode, the player count, the Java vendor and version, the OS name, version and architecture, and the CPU core count.
• Errors: errors raised by DiSky syntaxes at runtime (the exception type, its message truncated to 500 characters and a shortened stack trace).

No IP address, player data, bot token, Discord content or script source is collected.

To opt out, edit plugins/faststats/config.properties (shared by every plugin that uses FastStats) and restart:

• enabled=false turns FastStats off entirely;
• submitMetrics=false stops usage statistics only;
• submitErrors=false stops error reports only.

The JVM flag -Dfaststats.enabled=false also turns it off.

A first bot

Save this as plugins/Skript/scripts/bot.sk, put your token in it, and run /sk reload bot:

options:
    token: "YOUR-BOT-TOKEN"

on load:
    set {_bot} to a new discord bot
    set token of {_bot} to {@token}
    login {_bot} as "my-bot"

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

# Slash commands are declared in the script, then sent to Discord explicitly.
on guild ready:
    update the discord commands (all structured application commands) in event-guild

slash command ping:
    description: Check that the bot is alive
    trigger:
        reply with hidden "Pong!"

slash command ban <target: member> [<reason: string>]:
    description: Ban a member
    enabled for: ban members
    trigger:
        try:
            ban {_target} because of {_reason}
        catch {_errors::*} and stop:
            reply with hidden "Could not ban %{_target}%: %error meaning of {_errors::1}%"
        reply with hidden "%{_target}% was banned."

on message received seen by "my-bot":
    discord content of event-message is "!about"
    set {_e} to a new discord embed
    set title of {_e} to name of event-guild
    set description of {_e} to "%member count of event-guild% members"
    set color of {_e} to orange
    reply with {_e}

hidden makes a reply visible only to the user who ran the command. If the ban fails (missing permission, member above the bot), the catch block gets a readable error instead of a stack trace in the console.

What you can do

• Bots: several bots at once, intents, cache settings, sharding, presence.
• Messages: send, reply, edit, delete, pin, react, read history; embeds, file uploads and downloads, polls.
• Commands: slash commands with typed options, autocomplete, subcommands, cooldowns and translations; user and message (right-click) commands; classic text commands with a prefix.
• Components: buttons, select menus, modals, and the newer layout components (containers, sections, galleries).
• Server management: members, roles and their order, channels and threads, permissions and channel overrides, emotes and stickers, invites, scheduled events, welcome screen, AutoMod rules, webhooks.
• Moderation: ban, kick, timeout, purge, audit log reasons.
• Events: about 130 Discord events, from messages and reactions to voice, roles and AutoMod.

The Atlas lists every syntax with its patterns and examples.

Three things that differ from plain Skript

Talking to Discord takes time. Anything that sends something to Discord (posting a message, banning a member) runs off the server thread, so your server never lags waiting for Discord. Values DiSky has in memory are read directly; values it has to ask Discord for are read with await, which waits for the answer:

await set {_bans::*} to bans of event-guild

Reading such a value without await is an error when the script loads, not a silent <none>.

Builders. To create something on Discord (a role, a channel, a message with several parts), you fill a builder first, then send it:

set {_b} to a new role builder named "Helpers" in event-guild
set color of {_b} to light blue
await set {_role} to the build result of {_b}

Errors. A failed Discord action prints a readable message to the console. Put it in a try block to handle it yourself, as in the ban command above, or listen to on discord error to catch the ones no try handled.

Coming from DiSky 4

DiSky 5 replaces DiSky 4: same plugin name, same Modrinth page, and addons that depend on DiSky keep working by name. V4 scripts do not run as-is.

Read the migration guide on the Atlas before switching a bot over. It gives the order to port a script in, before/after examples for every change (retrieve becoming await, builders, the discord prefix, commands, components, events), and the list of what DiSky 5 does not have yet.

Building from source

./gradlew build

Needs JDK 21. The plugin is build/libs/DiSky-<version>.jar (the -thin jar next to it does not contain JDA and will not load).

License

Apache License 2.0