KAL v2 overview

What the Kharat Automation Language is, how scripts compile and run, and the shape every program follows.

KAL (the Kharat Automation Language) is the programming language behind custom commands. Version 2 compiles to bytecode and runs in a sandboxed virtual machine inside the bot — deterministic, resource-capped, and safe to let any administrator run.

A complete program#

kal

KAL VERSION 2.0;
AUTOMATION status_report {

    WHEN COMMAND status {
        REPLY "All systems operational.";
    }
}

That is a working command: run /status (or ,status) and the bot replies. Two structural rules apply to every program:

Line 1 must be exactly KAL VERSION 2.0; — the compiler rejects anything else with E001_MALFORMED_VERSION_HEADER. There is no v1 fallback; v1 was discontinued.
Everything lives inside one AUTOMATION name { … } block.

The mental model#

text

source (.kal text)
   │  compile  → bytecode + validation (static checks, context rules)
   ▼
registered on the bot (per server, per script)
   │  trigger fires (command / event / interaction / schedule)
   ▼
VM runs the bytecode  →  Discord actions  →  state written or rolled back

Compilation happens on save. Runtime errors cannot corrupt your server: each run has a budget (instructions, wall clock, Discord actions), and if a run crashes, its state changes are rolled back.

What a program can contain#

Building block	Statement	Chapter
Server settings	`CONFIG`	Syntax
Data	`DECLARE`, `SET`, `CONSTANT`, `FUNCTION`	Syntax
Decisions	`IF`, `WHILE`, `FOR EACH`, `TRY`	Control flow
Triggers	`WHEN COMMAND`, `WHEN EVENT`, `WHEN INTERACTION`, `SCHEDULE`	Triggers
Effects	`REPLY`, `SEND EMBED`, `TIMEOUT`, `>30 more`	Actions
UI	buttons, select menus, modals	Components
Memory	`STATE GET/PUT/APPEND/…`	State
Libraries	`IMPORT { … } FROM "…";`	Modules

A taste of each trigger#

kal

KAL VERSION 2.0;
AUTOMATION tour {

    WHEN COMMAND greet (name AS STRING) {
        REPLY "Hello, " + name + "!";
    }

    WHEN EVENT member_join {
        LOG "New member: " + member.name;
    }

    WHEN INTERACTION verify_button {
        REPLY "You are verified!" EPHEMERAL;
    }
}

All three triggers can coexist in one program. Scheduled jobs are declared slightly differently (SCHEDULE EVERY … { … }) and get a smaller context — see Triggers.

The sandbox, in one table#

Resource	Cap
Source size	200,000 characters
Instructions per run	50,000
Wall clock per run	5 seconds
Discord actions per run	5
State value size	2,048 bytes (100 keys per script)
Call depth	64

The full limit table and every error code live in Diagnostics & limits.

How this documentation is validated#

Every ```kal example in these guides is compiled against the real compiler as part of the site's test suite. If an example is shown as KAL code, it builds. Syntax fragments that are not complete programs are marked kal (fragment) in the code bar and are intentionally not compiled.