Custom commands
What custom commands are, how they are stored and executed, and the hard limits that apply to every script.
A custom command is a KAL v2 program owned by one server. It is compiled to bytecode, registered with the bot, and then behaves like any built-in feature: it answers commands, reacts to events, handles button clicks and runs on schedules.
Two kinds of ownership#
| Per-server script | Creator definition | |
|---|---|---|
| Where it lives | Installed on one server | Your creator workspace (Studio) |
| Visible to | That server's dashboard | You, across servers |
| Install from | Builder on the server | "Install to server" from Studio |
| Publishable | Yes, via its definition | Yes, to the Marketplace |
The builder works on the server's own scripts; Command Studio (what's the difference?) manages your reusable definitions. Scripts installed from the marketplace carry the package they came from and can be updated when the package moves forward — see Marketplace overview.
What a script can do#
Everything the KAL v2 language allows (all documented in the KAL category):
- respond to slash and prefix commands with permission clauses,
- react to 22 gateway event types (joins, message edits, reactions, …),
- handle button clicks and select menus and show modals,
- run on schedules (repeating or one-shot),
- keep durable state per server and per script,
- send embeds with buttons and select menus,
- take CONFIG settings that appear as a per-server configuration form.
Hard limits#
| Limit | Value |
|---|---|
| Source size | 200,000 characters |
| Instructions per run | 50,000 |
| Wall-clock per run | 5 seconds |
| Discord actions per run | 5 (replies, embeds, roles, bans, …) |
| State values | ≤ 2,048 bytes each; 100 keys per script; 512 KiB total |
| Timeout duration | ≤ 28 days |
| Purge range | 1–100 messages |
| Components | 5 rows × 5 buttons; select menus ≤ 25 options |
The runtime enforces all of these in the sandbox; a script that exceeds its budget is stopped and its state changes are rolled back rather than half-applied.
Lifecycle#
- Draft — stored, not registered, may contain compile errors.
- Published (private) — compiled and registered on the server.
- Disabled / enabled — a toggle unregisters and re-registers the script.
- Deleted / uninstalled — removed along with its durable state.
Every transition goes through the bot; the dashboard cannot apply any of them while the bot is offline.