Files
horizon-airdef/docs/horizon-ctl-commands.md
T
Ludovic Marie 4e7c25bb55 Remove shader packs
A developer of Iris showed that Horizon's shader pack code was written from
Iris's source. This removes it: the horizon-shaderpack crate, Java pack
loading and its render stages, Horizon's own WGSL packs and the example
packs, the Shader Packs screen and its option, the launcher's shader pack
browsing and installing, and the docs about them. Shader packs may come
back later as a clean-room rewrite.

The vanilla renderer and its post-processing (resolution scale, FXAA) are
unchanged. Options files that name a pack load and drop the key; the
launcher reads manifests that list a shader pack, and files in
`shaderpacks/` are never deleted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 16:15:39 +02:00

141 lines
19 KiB
Markdown

<!-- Generated by `horizon-ctl help --markdown` from the command table in crates/horizon-client/src/bin/horizon-ctl/commands.rs: edit the table, then regenerate. -->
# horizon-ctl commands
Every command `horizon-ctl` takes, its MCP tool in `horizon-ctl mcp` (the launcher's `horizon-launcher mcp` offers the same tools as `game_<tool>`, all but `launch`) and its arguments. Positional arguments come first, in order; `--flags` after them. `horizon-ctl help --game` lists the game's own commands, test hooks included. Design rules and the full inventory: [agent-control.md](agent-control.md).
## Session
| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `launch [--world NAME] [--seed N] [--creative] [--version TAG] [--game PATH] [--wait] [GAME ARGS...]` | `launch` | Start Horizon with the control socket and wait until it answers | `--world` (string): world folder to open or create<br>`--seed` (string): seed for a new world<br>`--creative` (boolean): creative mode for a new world<br>`--version` (string): an installed launcher version tag such as v2026.10.13<br>`--game` (string): path to a horizon-client binary<br>`--wait` (boolean): also wait until the world is ready (default in MCP)<br>`--offscreen` (boolean): render without showing a window (screenshots still work): locked or headless sessions |
| `wait-for screen NAME\|widget ID\|loaded\|chat TEXT\|event KIND [--timeout S] [--since SEQ]` | `wait_for` | Wait until the game reaches a state, then reply | `--timeout` (number): seconds (default 30)<br>`--since` (integer): chat and event: count from this event seq<br>`condition` (screen, widget, loaded, chat, event, required): what to wait for<br>`value` (text): the screen name, widget id, chat text or event kind |
| `wait-ready [SECONDS]` | `wait_ready` | Wait until the player has spawned and no chunks are pending | `seconds` (number): how long to wait (default 120) |
| `logs [--lines N] [--crash]` | `logs` | The end of the game's log, or its newest crash report | `--lines` (integer): how many lines of latest.log (default 100)<br>`--crash` (boolean): the newest crash report instead |
| `status` | `status` | Game, renderer and streaming state (the scripting socket's original summary) | none |
| `worlds` | `worlds` | The saved worlds, newest first: folder, name, mode, last played, version | none |
| `world-rename FOLDER NAME` | `world_rename` | Rename a world, as Edit World does (its folder stays) | `folder` (string, required): world folder from worlds<br>`name` (text, required): the new name |
| `world-backup FOLDER` | `world_backup` | Zip a world into backups/, as Edit World's Make Backup does | `folder` (string, required): world folder from worlds |
| `world-delete FOLDER --confirm` | `world_delete` (destructive) | Delete a world for good, as Select World's Delete does | `folder` (string, required): world folder from worlds<br>`--confirm` (boolean, required): true once the player agreed: it cannot be undone |
| `open WORLD [SEED] [creative]` | `open` | Open or create a world from the title screen | `world` (string, required): world folder<br>`seed` (integer): seed for a new world<br>`mode` (creative): creative for a creative world |
| `save` | `save` | Save the world | none |
| `quit` | `quit` | Save and exit the game | none |
| `screenshot PATH` | `screenshot` | Write the next rendered frame as a PNG | none |
## Observe (JSON state)
| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `events [--since SEQ]` | `events` | What happened since SEQ, oldest first: screens, chat, deaths, respawns, items gained or lost, dimensions, worlds | `--since` (integer): only events after this seq |
| `state` | `state` | Player, world, screen and crosshair target in one reply | none |
| `looking-at` | `looking_at` | The block or entity under the crosshair | none |
| `entities [RADIUS] [TYPE]` | `entities` | Mobs, dropped items and experience orbs near the player, nearest first | `radius` (number): search radius in blocks (default 32)<br>`type` (string): entity type filter |
| `block X Y Z` | `block` | The block state at a position | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z |
| `light X1 Y1 Z1 X2 Y2 Z2` | `light` | The stored sky and block light of a box | `x1` (integer, required): corner X<br>`y1` (integer, required): corner Y<br>`z1` (integer, required): corner Z<br>`x2` (integer, required): opposite X<br>`y2` (integer, required): opposite Y<br>`z2` (integer, required): opposite Z |
| `blocks X1 Y1 Z1 X2 Y2 Z2` | `blocks` | The non-air blocks of a box, with counts per block | `x1` (integer, required): corner X<br>`y1` (integer, required): corner Y<br>`z1` (integer, required): corner Z<br>`x2` (integer, required): opposite X<br>`y2` (integer, required): opposite Y<br>`z2` (integer, required): opposite Z |
| `find-block BLOCK [RADIUS]` | `find_block` | The nearest loaded blocks of a kind | `block` (string, required): block id such as oak_log<br>`radius` (integer): search radius (default 32) |
| `inventory` | `inventory` | Hotbar, main inventory, armor, offhand, carried stack and item counts | none |
| `screen` | `screen` | The open screen or title menu, its buttons and its slots | none |
| `messages [N]` | `messages` | Recent chat and system messages, the title and the action bar | `n` (integer): how many chat lines (default 20) |
| `menu` | CLI only | The open menu's slots and carried stack, with station details | none |
## Move and look
| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `move forward\|back\|left\|right SECONDS [--sprint] [--sneak] [--jump]` | `move` | Walk in a direction relative to the view for a time | `direction` (forward, back, left, right, required): direction relative to the view<br>`seconds` (number, required): how long to walk<br>`--sprint` (boolean): sprint<br>`--sneak` (boolean): sneak<br>`--jump` (boolean): keep jumping |
| `goto X Y Z [--near R] [--sprint] [--direct] [--timeout S]` | `goto` | Walk to a position, finding a path through loaded terrain | `x` (number, required): X coordinate<br>`y` (number, required): Y coordinate<br>`z` (number, required): Z coordinate<br>`--near` (number): arrive within this many blocks (default 0.6)<br>`--sprint` (boolean): sprint<br>`--direct` (boolean): walk straight when no path is found<br>`--timeout` (number): give up after this many seconds (default 60) |
| `jump` | `jump` | Jump once and reply when landed | none |
| `look YAW PITCH` | `look` | Set the view direction in degrees | `yaw` (number, required): yaw in degrees<br>`pitch` (number, required): pitch in degrees (-90 up .. 90 down) |
| `turn DYAW DPITCH [--over S]` | `turn` | Rotate the view by an amount | `dyaw` (number, required): yaw change in degrees<br>`dpitch` (number, required): pitch change in degrees<br>`--over` (number): turn with mouse motion spread over this many seconds (eased), as a player would |
| `mouse-move DX DY` | `mouse_move` | Move the mouse: relative motion that turns the view like a player's mouse | `dx` (number, required): horizontal motion (positive turns right)<br>`dy` (number, required): vertical motion (positive looks down) |
| `look-at X Y Z \| look-at block X Y Z [FACE] \| look-at entity ID [--over S]` | `look_at` | Turn to face a point, a block (a visible face of it) or an entity | `x` (number, required): X coordinate<br>`y` (number, required): Y coordinate<br>`z` (number, required): Z coordinate<br>`--over` (number): turn with mouse motion spread over this many seconds (eased), as a player would |
| `look-at-block X Y Z [FACE] [--over S]` | `look_at_block` | Aim the crosshair at a block (same as look-at block) | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`face` (down, up, north, south, west, east): which face to aim at<br>`--over` (number): turn with mouse motion spread over this many seconds (eased), as a player would |
| `look-at-entity ID [--over S]` | `look_at_entity` | Face an entity (same as look-at entity) | `id` (integer, required): entity id from entities<br>`--over` (number): turn with mouse motion spread over this many seconds (eased), as a player would |
| `tp X Y Z` | `tp` | Teleport the player | `x` (number, required): X coordinate<br>`y` (number, required): Y coordinate<br>`z` (number, required): Z coordinate |
## Act on the world
| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `break X Y Z [--timeout S]` | `break` | Mine a block, holding the attack button until it breaks | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`--timeout` (number): give up after this many seconds (default 30) |
| `place X Y Z [--item ITEM]` | `place` | Place the held item (or ITEM from the hotbar) at an empty position | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`--item` (string): hotbar item to select first |
| `interact X Y Z [FACE]` | `interact` | Right-click a block: open a chest or crafting table, press a button, open a door | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`face` (down, up, north, south, west, east): which face to click |
| `use-item [--hold SECONDS]` | `use_item` | Right-click with the held item: eat, drink, throw, draw a bow | `--hold` (number): hold the button this long |
| `attack [ID]` | `attack` | Swing at what the crosshair targets (after facing entity ID) | `id` (integer): entity id to face first |
| `select SLOT\|ITEM` | `select` | Select a hotbar slot 1-9, or the hotbar slot holding ITEM | `slot` (string, required): 1-9 or an item id |
| `drop [all]` | `drop` | Drop one of the held item, or the whole stack | `all` (boolean): drop the whole stack |
| `hold KEY SECONDS` | CLI only | Press a key, wait, release it | `key` (string, required): key name<br>`seconds` (number, required): how long |
| `key KEY down\|up\|tap\|repeat` | `key` | Press, release or auto-repeat a key (w a s d space shift ctrl e q esc f3 1-9 arrows ...) | `key` (string, required): key name<br>`action` (down, up, tap, repeat, required): what to do |
| `mouse left\|right\|middle down\|up\|click` | `mouse` | Press or release a mouse button in the world | `button` (left, right, middle, required): button<br>`action` (down, up, click, required): what to do |
| `interact-entity ID` | `interact_entity` | Right-click an entity: trade with a villager, mount a horse, ride a boat, shear a sheep | `id` (integer, required): entity id from entities |
| `pad BUTTON down\|up\|tap \| pad stick left\|right X Y \| pad trigger left\|right V \| pad release \| pad status` | `pad` | A virtual controller: buttons, sticks and triggers as a real pad would send them | `what` (string, required): a button name, stick, trigger, release or status<br>`a` (string): down\|up\|tap, or left\|right<br>`b` (number): stick X or trigger value<br>`c` (number): stick Y |
| `release` | `release` | Release every key and mouse button | none |
| `stop` | `stop` | Cancel the running action (goto, break...) and release every key | none |
## Screens, menus and chat
| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `open-inventory` | `open_inventory` | Open the inventory screen (crafting grid 100-103, result 200) | none |
| `click-slot SLOT [right] [shift]` | `click_slot` | Click a slot of the open inventory or menu | `slot` (integer, required): slot id<br>`right` (boolean): right-click<br>`shift` (boolean): shift-click |
| `close` | `close` | Close the open menu and return to the game | none |
| `ui` | `ui` | Every widget of the open screen: id, kind, label, bounds, value | none |
| `click ID [right\|middle] [shift]` | `click` | Click a widget of ui by its id, as the mouse would | `id` (string, required): widget id from ui<br>`right` (boolean): right-click<br>`middle` (boolean): middle-click<br>`shift` (boolean): shift-click (slots) |
| `set ID VALUE` | `set` | Move a slider of ui to VALUE (0..1), as a click on its track | `id` (string, required): slider id from ui<br>`value` (number, required): 0..1 along the track |
| `options-get [KEY...]` | `options_get` | The game's options (options.txt) by key, with their type and range or choices | `keys` (text): option keys (default: all) |
| `options-set KEY VALUE` | `options_set` | Set one option, apply it at once and save options.txt, as the options screen does | `key` (string, required): option key from options-get<br>`value` (text, required): the new value |
| `click-button LABEL` | `click_button` | Click a button of the open screen or title menu by its label | `label` (text, required): button label |
| `click-at X Y [right]` | `click_at` | Click at GUI pixel X Y of the window (screen gives button rectangles) | `x` (number, required): GUI x<br>`y` (number, required): GUI y<br>`right` (boolean): right-click |
| `drag-at [right] X Y X Y...` | `drag_at` | Press at the first GUI point, move through the others, release at the last | `points` (text, required): right, then GUI x y pairs |
| `scroll-at X Y STEPS` | `scroll_at` | Turn the mouse wheel at GUI pixel X Y (positive scrolls up) | `x` (number, required): GUI x<br>`y` (number, required): GUI y<br>`steps` (number, required): wheel steps |
| `type [--field name\|seed] [--replace] TEXT` | `type` | Type into the focused text field (chat box, world name, anvil, sign...) | `--field` (name, seed): create-world field to type into<br>`--replace` (boolean): clear the field first<br>`text` (text, required): text to type |
| `chat TEXT` | `chat` (network) | Send a chat line (or a /command) as if typed | `text` (text, required): message |
| `command TEXT` | `command` (network) | Run a command (the leading / is optional) | `command` (text, required): command line |
| `respawn` | `respawn` | Respawn from the death screen | none |
| `pause` | `pause` | Open the pause menu | none |
| `resume` | `resume` | Leave the pause menu | none |
| `options [PAGE]` | `options` | Open the options screen, or one of its pages (Horizon's too) | `page` (main, video, sound, controls, keybinds, controller, controller-binds, mouse, chat, accessibility, language, font, packs, mods, graphics, graphics-advanced, extras, horizon, agent): the page (default: the main options) |
| `book [next\|back\|take\|done]` | `book` | The open book or lectern: its page text, or press one of its buttons | `action` (next, back, take, done): a button to press |
| `signedit X Y Z [front\|back]` | `signedit` | Open the sign editor of the sign at X Y Z (then type and close) | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`side` (front, back): which side |
| `mount-menu` | `mount_menu` | Open the inventory of the horse, donkey, mule or llama being ridden | none |
| `chat-log [N]` | CLI only | The newest N chat messages | none |
## Multiplayer, LAN and friends
| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `connect ADDRESS [NAME]` | `connect` (network) | Join a multiplayer server, or a friend's world by its invite code, from the title screen | `address` (string, required): HOST[:PORT] or friend:CODE<br>`name` (string): player name when offline |
| `disconnect` | `disconnect` | Leave the server, back to the server list | none |
| `servers` | `servers` | The Multiplayer screen's server list: name and address | none |
| `lan open [PORT] [commands] [force] \| lan close \| lan status` | `lan` (network) | Open the world to LAN (Open to LAN), stop, or see the guests | `action` (open, close, status, required): what to do<br>`port` (integer): port for open<br>`commands` (boolean): allow cheats<br>`force` (boolean): force the game mode |
| `friends host\|stop\|status` | `friends` (network) | Play with Friends: share the open world behind an invite code, stop, or see who joined | `action` (host, stop, status, required): what to do |
## World and cheats
| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `give ITEM [COUNT]` | `give` | Add items to the inventory | `item` (string, required): item id<br>`count` (integer): how many (default 1) |
| `time TICKS` | `time` | Set the time of day (0 sunrise, 6000 noon, 13000 night) | `ticks` (integer, required): day time |
| `setblock X Y Z BLOCK[props]` | `setblock` (destructive) | Set a block (with neighbour updates) | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`block` (string, required): block state such as oak_stairs[facing=east] |
| `summon KIND [X Y Z] [baby]` | `summon` | Spawn a mob (in front of the player without a position) | `kind` (string, required): mob type<br>`x` (number): X<br>`y` (number): Y<br>`z` (number): Z<br>`baby` (boolean): a baby |
| `effect ID SECONDS [AMPLIFIER] \| effect clear` | `effect` | Give a status effect, or clear them all | `id` (string, required): effect id such as speed, or clear<br>`seconds` (number): duration<br>`amplifier` (integer): level - 1 (default 0) |
| `effects` | `effects` | The player's active status effects | none |
| `xp LEVELS` | `xp` | Add experience levels (negative removes) | `levels` (integer, required): levels to add |
| `enchant ID LEVEL` | `enchant` | Enchant the held item (a book stores it) | `id` (string, required): enchantment id<br>`level` (integer, required): level |
| `potion ITEM POTION` | `potion` | Give a potion item | `item` (potion, splash_potion, lingering_potion, tipped_arrow, required): which item<br>`potion` (string, required): potion id |
| `fill X1 Y1 Z1 X2 Y2 Z2 BLOCK` | `fill` (destructive) | Set a box of loaded blocks | `x1` (integer, required): corner X<br>`y1` (integer, required): corner Y<br>`z1` (integer, required): corner Z<br>`x2` (integer, required): opposite X<br>`y2` (integer, required): opposite Y<br>`z2` (integer, required): opposite Z<br>`block` (string, required): block state |
| `container X Y Z [ITEM COUNT]` | `container` | List a container's items, or add items to it | `x` (integer, required): block X<br>`y` (integer, required): block Y<br>`z` (integer, required): block Z<br>`item` (string): item to add<br>`count` (integer): how many |
| `render-distance N` | CLI only | Chunks, 2..64 | `chunks` (integer, required): render distance |
| `wait TICKS` | `wait` | Wait until TICKS game ticks have passed (20 per second) | `ticks` (integer, required): game ticks |
## Scripting and benchmarks
| Command | MCP tool | What it does | Arguments |
| --- | --- | --- | --- |
| `script [FILE] [--keep-going]` | CLI only | Run commands from FILE (or stdin), one per line | none |
| `sleep SECONDS` | CLI only | Wait (in scripts) | none |
| `mcp` | CLI only | Serve the Model Context Protocol on stdin/stdout, one tool per command | none |
| `bench SECONDS` | `bench` | Reset frame stats, wait, reply with the summary | `seconds` (number, required): how long to measure |
| `stats [reset]` | `stats` | Frame-time summary since the last reset | `reset` (boolean): start counting again |
| `fly X1 Y1 Z1 X2 Y2 Z2 SECONDS [PITCH [raw]]` | CLI only | Fly the camera along a line, then reply with the frame summary | none |