Commands

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

TL;DR

Command	What it does	Who can use
/katton or /katton help	Show the command list	Everyone
/katton status	Katton runtime state	Everyone
/katton errors	Last ten recorded script errors	Everyone
/katton capabilities events [event]	Query partial or unsupported event capabilities	Everyone
/katton capabilities injection	Injection diagnostics	Gamemaster
/katton packs list	List local packs with sync ID, version, kind, enabled state	Everyone
/katton packs enable|disable <syncId>	Toggle a pack, then reload (world packs only)	Gamemaster
/katton registry	Registry health overview	Everyone
/katton registry stale	Show stale retained entries	Everyone
/katton reload	Reload all script packs	Gamemaster
/katton config list [pack]	List pack config values	Everyone
/katton config get <pack> <key>	Read one config value	Everyone
/katton config set <pack> <key> <value>	Write a config value	Gamemaster
/katton config reset <pack> <key>	Remove a config override	Gamemaster
/katton itemrender spawn <item> [preset] [scale] [lifetimeTicks]	Spawn a client item render marker	Gamemaster
/katton itemrender clear <radius>	Clear item render markers in range	Gamemaster
/katton debug registryLogging [on|off]	Read or set verbose registration logging	Gamemaster
/katton debug injection	Injection diagnostics	Gamemaster
/katton dev enable|disable	Start or stop the IDE development bridge	Gamemaster

NOTE

On Paper, /katton is deliberately smaller: help, status, reload, errors, capabilities events|injection, packs list|enable|disable, and dev enable|disable. Reload, pack toggling, and dev require the katton.admin permission or OP. The registry, config, itemrender, and debug registryLogging subcommands are Fabric/NeoForge only, because Paper disables registry mutation and has no client to render item markers.

Help

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

/katton

or

/katton help

Output (Fabric / NeoForge):

[Katton] /katton help | status | errors | capabilities events [event] | capabilities injection | packs list|enable|disable | registry | reload | debug injection | itemrender ... | config ...

Output (Paper):

[Katton] /katton help | status | reload | errors | capabilities events [event] | capabilities injection | packs list|enable|disable

Status

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

/katton status

Output:

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

Errors

/katton errors prints the last ten script errors Katton recorded. Use it after a failed reload or a runtime exception to see the title and detail of each issue without digging through the console log.

Capabilities

Event and injection support varies by platform, version, and target. These subcommands answer "is this actually going to work here?" before you spend time debugging.

/katton capabilities events            # all partial or unsupported events
/katton capabilities events <EventObject.onEvent>
/katton capabilities injection         # Fabric / NeoForge, gamemaster

capabilities events reports a status, execution context, and detail for each queried event. If nothing is reported, every queried capability is fully supported. See the Events guide for the event model and the API reference for the complete capability list.

Packs

List and toggle local packs without opening the UI:

/katton packs list
/katton packs enable world:my_pack
/katton packs disable world:my_pack

packs list shows the scope-qualified sync ID, version, kind (DIRECTORY or ZIP), and enabled state. Toggling a world pack saves its state file and starts a reload immediately. A global pack's state is saved but requires a restart, because global code is not hot-applied.

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."

Config

The manifest's config object provides defaults. Server operators can override primitive values at runtime without editing the pack:

/katton config list
/katton config list my_pack
/katton config get my_pack difficulty
/katton config set my_pack difficulty hard
/katton config reset my_pack difficulty

Overrides are stored under <gameDir>/.katton/config-overrides/ using the scope-qualified sync ID; server-cache packs add a server_cache: prefix so a remote global:x cannot overwrite a local global:x. Katton never rewrites a pack manifest for config changes, so directory, ZIP, and signed packs all persist settings consistently.

Item Render Markers

Spawn a temporary client-side item model for testing, without creating a real entity or item frame:

/katton itemrender spawn minecraft:diamond_sword
/katton itemrender spawn minecraft:diamond_sword showcase 1.5
/katton itemrender spawn minecraft:diamond_sword pulse 1.0 200
/katton itemrender clear 32

Presets are still, spin, float, pulse, and showcase. scale defaults to 1.0 and lifetimeTicks to -1 (no expiry). itemrender clear <radius> removes markers within that radius of the command source. See Item Render Markers.

Debug

/katton debug registryLogging

Output:

[Katton] debugRegistryLogging=false

/katton debug registryLogging on

Output:

[Katton] debugRegistryLogging=true

// You can also toggle this from scripts:
import top.katton.Katton
import top.katton.api.ServerPhase
import top.katton.api.ServerScriptEntrypoint

@ServerScriptEntrypoint(ServerPhase.READY)
fun enableRegistryLogging() {
    Katton.debugRegistryLogging = true
}

/katton debug injection prints the injection capability report: whether ByteBuddy/ASM injection is available and which hooks are supported on this platform. See Code Injection.

IDE Development Bridge

/katton dev enable
/katton dev disable

Enabling starts a loopback HTTP bridge on 127.0.0.1 with a per-session bearer token and prints the port. The Katton IDEA plugin then discovers the instance from ~/.katton/dev/instances, deploys world packs, and streams compiler diagnostics. The bridge is off by default and can also be toggled with the IDE button in the script pack UI.

Reload

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

1. Re-scans all enabled script packs and resolves their dependency graph

2. Re-compiles and executes server scripts for the replaced components

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

4. Publishes a new pack revision to connected Fabric/NeoForge clients

   // 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.