Commands

Katton ships with a set of built-in commands under /katton to help you manage scripts, inspect state, and toggle debugging — all from in-game chat or server console.

TL;DR

Command	What it does	Who can use
/katton or /katton help	Show all commands	Everyone
/katton status	Katton runtime state	Everyone
/katton registry	Registry health overview	Everyone
/katton registry stale	Show stale retained entries	Everyone
/katton reload	Reload all script packs	OP only
/katton debug registryLogging	Check debug log toggle	OP only
/katton debug registryLogging on/off	Enable/disable debug logs	OP only

NOTE

On Paper, the /katton command is simpler: only /katton help, /katton status, and /katton reload are available. Reload requires the katton.admin permission (not just OP). The registry and debug subcommands are not available on Paper because registry operations are disabled.

Help

Just type /katton or /katton help — Katton will list all available subcommands.

/katton

or

/katton help

Output:

[Katton] /katton help | status | registry | registry stale | reload | itemrender spawn <item> [still|spin|float|pulse|showcase] [scale] [lifetimeTicks] | itemrender clear <radius> | debug registryLogging [on|off] | config ...

Status

Want a quick pulse on Katton? /katton status prints the current load state, whether a server is bound, and if a client reload is in progress.

/katton status

Output:

[Katton] state=SERVER_STARTED, serverBound=true, clientReloadRunning=false

Registry Diagnostics

/katton registry

Shows a per-registry summary: how many entries Katton knows about, how many are actively managed by scripts, and how many are stale (retained in Minecraft's built-in registry but no longer claimed by any script).

/katton registry

Output:

[Katton] items: entries=2, managed=2, stale=0 | effects: entries=1, managed=1, stale=0 | blocks: entries=1, managed=1, stale=0 | ...

/katton registry stale

When no stale entries exist:

[Katton] No stale retained registry entries.

When stale entries exist (e.g. after removing a script that registered items):

[Katton] Stale retained entries: items=1 | entity_types=1

/katton registry stale

Filters to only show registries that have stale entries. Handy after you've removed a script that registered a bunch of stuff — those IDs are still in the game but not tracked by Katton anymore.

NOTE

Stale does not mean broken. Katton intentionally keeps registered objects in Minecraft's built-in registries during reload to avoid holder crashes. Stale just means "left over from a previous script run that didn't re-register them this time."

Reload

/katton reload is your daily driver for hot-reload iteration. It does three things:

1. Re-scans all enabled script packs

2. Re-compiles and executes server scripts

3. On integrated servers (singleplayer), also triggers client script reload asynchronously

   // In a server script:
   // The /katton reload command is built-in — just type it in chat or server console.
   // No code needed! It reloads all script packs and syncs the command tree.
   
   // If an event or custom command needs to request the same reload:
   import net.minecraft.server.MinecraftServer
   import top.katton.engine.ScriptReloadManager
   
   fun requestKattonReload(server: MinecraftServer) {
       ScriptReloadManager.reloadScriptsAsync(server) { success ->
           println("Katton reload finished: $success")
       }
   }

TIP

• F3 + T reloads Minecraft resources only; it does not invoke Katton scripts.
• /reload (vanilla) reloads datapacks; Katton hooks into this for server scripts.
• /katton reload does both in one go.