Merge feat/java-gbuffers-terrain into feat/java-terrain-cull

With main's Metal culling: the pack's depth test in OpenGL's layout runs
forced early on Vulkan (fs_box_early_depth) and in the shader on Metal
(fs_box_gl, the pack's depth attached read only and bound), and the flat
path culls too (phase 1 calls, flatten_phase2 after test_gl, then
draw_phase2 with each page's group 3).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-23 17:55:04 +02:00
425 changed files with 43251 additions and 10989 deletions
+2 -1
View File
@@ -4,6 +4,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
## Build and run
- [AGENTS.md](../AGENTS.md) and [Architecture](architecture.md): where each part of the code lives, how `Game` is organised, which harness checks which area.
- [Build from source](../README.md#build-from-source): your own copy of the game, resource preparation, `cargo run`.
- [Native client](native-client.md): options, controls, the dedicated server, `horizon-ctl` scripting, packaging, architecture.
- [Host a server](hosting.md): install `horizon-server`, prepare the game files, first run, `server.toml`, the commands, the web panel, backups, services and Docker; what works today and what doesn't yet.
@@ -20,7 +21,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
- [Resource packs](resource-packs.md): everything a 26.3 resource pack can change, whether Horizon honours it, and the proof.
- [Opt-in data collection](telemetry.md): the consent, exactly what is sent, how it is stored and sent.
- [Benchmark report format](benchmark-report.md): the versioned JSON every benchmark writes (game, launcher, `tools/perf_bench.py`), the local log and, with consent, the upload.
- Menus: the title, world list, create world, multiplayer, options and pause screens share the launcher's design tokens and fonts (`crates/horizon-theme`), drawn by `ui_theme` over a live frozen backdrop (`game/backdrop.rs`, blurred and graded by `post.rs`). Options → Interface → Menu style switches to vanilla's screens (Classic, kept in `horizon.txt`; `HORIZON_MENU_STYLE=horizon|classic` overrides it, and scripted runs default to Classic). [Title](media/menu-title.png) ([webm](media/menu-title.webm)), [worlds](media/menu-worlds.png), [options](media/menu-options.png), [pause](media/menu-pause.png).
- Menus: every screen is vanilla's (title, world list, create world, multiplayer, options, pause). Horizon's own settings hang off vanilla's Options the way mods add theirs: **Horizon Settings...** and **Mods...** in the last two slots of the Options grid (Horizon Settings opens Graphics, Advanced Graphics, Shader Packs, Controller Settings, Extras and Mods, each a vanilla options list), with Horizon Graphics, Advanced Graphics and Shader Packs also at the top of Video Settings and Controller Settings at the bottom of Controls. The title screen's and pause menu's Friends buttons open Join a Friend and Play with Friends ([play-with-friends.md](play-with-friends.md)).
## Parity
+257 -199
View File
@@ -1,239 +1,297 @@
# Agent control: driving the launcher and the game
AI agents and scripts control Horizon through four surfaces:
A player's own AI agent (Claude Code, Codex, Cursor, any MCP client) or a script can do
everything a player does with the mouse and keyboard, in the launcher and in the game. This page
covers developers: the surfaces, the full inventory, and the rules every new command follows.
Players read [Control Horizon with your AI agent](../website/docs/agents.md)
(playhorizon.dev/docs/agents).
The command lists are generated, so they can't drift:
- [launcher-commands.md](launcher-commands.md): every `horizon-launcher` command, its arguments
and its MCP tool. It comes from the CLI's clap definition (`cli_tools::markdown`), and the
launcher test `the_launcher_reference_is_up_to_date` fails when it is stale or a tool is missing.
- [horizon-ctl-commands.md](horizon-ctl-commands.md): every `horizon-ctl` command, its MCP tool
and its arguments. It comes from the command table (`horizon-ctl help --markdown`), and the
test `the_generated_reference_is_up_to_date` fails when it is stale.
## Surfaces
| Surface | Where | Transport |
| --- | --- | --- |
| Game control socket | `horizon-client --control` (`crates/horizon-client/src/control.rs`, commands in `src/game/control.rs`, `agent.rs` and friends) | text line in, one JSON line out; Unix socket, or localhost TCP + token where there is none |
| `horizon-ctl` | `crates/horizon-client/src/bin/horizon-ctl/` | CLI over the socket: one table of commands (`commands.rs`) gives help, argument checks and the MCP tools |
| `horizon-ctl mcp` | same | MCP over stdio, a tool per `horizon-ctl` command |
| Launcher CLI and MCP | `launcher/src/cli.rs`, `launcher/src/mcp.rs` | `horizon-launcher <cmd> [--json]`; `horizon-launcher mcp` (stdio) |
| Game control socket | `horizon-client --control` / `--control-socket PATH`, or Agent Control on in Horizon Settings > AI Agent (`crates/horizon-client/src/control.rs`; commands in `src/game/control.rs`, `agent.rs`, `ui_control.rs`, `saves_control.rs` and friends) | text line in, one JSON line out; Unix socket, or localhost TCP and a token where there is none |
| `horizon-ctl` | `crates/horizon-client/src/bin/horizon-ctl/` | CLI over the socket; one table of commands (`commands.rs`) gives the help, the argument checks, the MCP tools and the reference |
| `horizon-ctl mcp` | same | MCP over stdio, one tool per command of the table |
| Launcher CLI | `launcher/src/cli.rs` | `horizon-launcher <command> [--json]` |
| Launcher MCP | `launcher/src/mcp.rs`, `cli_tools.rs`, `game_tools.rs` | `horizon-launcher mcp` (stdio): every CLI command as a tool, the session tools, and the game's tools as `game_*` |
| Connecting | `launcher/src/agents.rs`, `agents_page.rs`; `src/game/agent_settings.rs` | `horizon-launcher agent-config`; Settings > AI in the launcher; Horizon Settings > AI Agent in the game |
| No AI | `crates/horizon-core/src/no_ai.rs` | `noAi:true` in `<game home>/horizon-extras.txt`, read by every surface |
This page is the inventory of what each surface can do and the design every new command
follows. Quick start for players and scripts: [native-client.md](native-client.md#agent-control-horizon-ctl-and-mcp).
## One MCP server for everything
## What exists today
An agent adds one server, `horizon-launcher mcp`. It holds:
Legend: **yes** complete, **part** partial (see note), **no** missing, **—** not applicable.
"Socket" is the game's own command; `horizon-ctl` and its MCP offer the subset in its table
(`horizon-ctl help --game` lists everything the game takes, test hooks included).
- **The launcher's CLI, generated.** `cli_tools.rs` walks the clap definition. Each command is a
tool named after its words (`mods search` is `mods_search`). Its arguments are the command's,
in snake_case, with clap's help, choices and defaults. A call runs that command with `--json`
as a child process and returns what it printed. A new CLI command is a new tool with no extra
code.
- **Session tools**, which keep something running between calls:
- `play` (the game, under control: `world`, `creative`, `join`, `offscreen`, `arg`);
- `server`, `server_command`, `server_log`, `server_stop`;
- `account_sign_in`, `account_list`.
- **The game's tools.** It runs the selected version's `horizon-ctl mcp` (shipped beside the
game) as a child. It lists that server's tools as `game_<name>`, all but `launch`, and passes
calls and results through, images included. `play` starts the game with a control socket in
the launcher's data folder. While no game answers, `game_*` calls say to call `play`.
Why one server rather than two: the game's tools stay defined once, in horizon-ctl's table. The
agent's client needs one entry and one approval. The version that plays is always the one the
launcher selected, so the game's tools always match the game. `horizon-ctl mcp` stays available
on its own, for a game started by hand or by a script.
## Inventory, before and after
Before is `main` at 2026-10-23, before #1342, #1343, #1344, #1345 and #1353. After is with
them. CLI is `horizon-launcher` for the launcher and `horizon-ctl` for the game. MCP is
`horizon-launcher mcp` (the game's tools as `game_*`) and `horizon-ctl mcp`. **part** means only
through a generic command (`ui` and `click` by widget, or a raw socket line that horizon-ctl
passes on without checking it).
### Launcher
| Capability | Window | CLI | MCP | Notes |
| --- | --- | --- | --- | --- |
| Releases, installed versions, select | yes | yes | yes | `versions`, `list_versions`; selecting happens on install only (no `select` command) |
| Install / remove a version | yes | yes | yes | |
| Prepare resources | yes | yes | yes | |
| Start the client | yes | yes (attached) | yes | MCP starts it detached and cannot reach it afterwards |
| Dedicated server: start, console, log, stop | yes | yes | yes | |
| Accounts (no secrets) | yes | yes | yes | names and UUIDs only; sign-in is a device code the player enters |
| Launcher settings (game folder, auto-install, opening animation, desktop entry) | yes | part | no | CLI has `desktop-entry`; the rest only in the window |
| Game menu style | yes | yes | yes | |
| Logs, crash report | yes | yes | yes | |
| Updates (Horizon and launcher) | yes | yes | yes | MCP only checks |
| Patch notes, links | yes | yes | yes | |
| Benchmark | — | yes | no | |
| Telemetry consent | PR #250 | PR #250 | PR #250 | opt-in, in review |
| Friends: join by invite code | yes | yes (`play --join`) | no | |
| Profiles, packs, mods | no | no | no | the launcher has none yet |
| The running game's controls | — | no | no | an agent needs a second MCP server (`horizon-ctl mcp`) |
| Capability | Window | CLI before | MCP before | CLI after | MCP after | Notes |
| --- | --- | --- | --- | --- | --- | --- |
| Releases and installed versions | Play, version picker | yes | yes | yes | yes | `versions [--installed]` |
| Install, remove a version | Play | yes | yes | yes | yes | `remove` needs `confirm` in MCP |
| Pick the version that plays | Play | no | no | yes | yes | `settings selected-version TAG` |
| Prepare resources | Play | yes | yes | yes | yes | |
| Start the game | Play | yes | yes | yes | yes | `play --world --creative --join --arg`; MCP `play` adds `offscreen` |
| Join a friend by invite code | Play | yes | no | yes | yes | `play --join CODE` |
| Dedicated server here: start, console, log, stop | Servers | yes | yes | yes | yes | `server`; MCP `server`, `server_command`, `server_log`, `server_stop` |
| Hosted servers: list, create, set up, run a command, forget | Servers | yes | no | yes | yes | `servers ...`; `servers_forget` needs `confirm` |
| Accounts: list, sign in, sign out, select, offline | Settings | yes | part | yes | yes | names and UUIDs only; sign-in is a device code; `account_offline` was missing |
| Game folder, server folder, install new versions, opening animation | Settings | no | no | yes | yes | `settings [KEY VALUE]` |
| Extra game arguments | Settings | yes | no | yes | yes | `game-args` |
| Applications menu entry (Linux) | Settings | yes | no | yes | yes | `desktop-entry` |
| Updates: check and install | Settings | yes | part | yes | yes | MCP could only check |
| Patch notes, links | Patch notes, footer | yes | yes | yes | yes | |
| Game log, crash reports | Settings | yes | yes | yes | yes | `logs [--crash]` |
| Data collection: status, allow, deny, show, delete, send, bug, benchmark upload | Settings > Data | yes | part | yes | yes | sending was missing in MCP; `data_delete` needs `confirm` |
| Mod browser: search, check, install, update, remove, list (mods, resource packs, shader packs, modpacks) | Mods | yes | no | yes | yes | `mods ...`; `mods_remove` needs `confirm` |
| Modpacks: import, port, play, remove, list | Modpacks | yes | no | yes | yes | `modpack ...`; `modpack_remove` needs `confirm` |
| Launcher benchmark | (none) | yes | no | yes | yes | |
| The game it started | (the game) | (horizon-ctl) | yes | (horizon-ctl) | yes | `game_*` |
| Connect an AI agent | Settings > AI | no | (none) | yes | (none) | `agent-config [--client] [--test]`; the agent is already connected, so there is no tool |
| No AI | Settings > AI | no | (none) | yes | (none) | `no-ai [on\|off]`; the player's switch, never an agent's |
### Game
| Capability | Socket | horizon-ctl / MCP | Notes |
| --- | --- | --- | --- |
| Session: launch, wait until ready, open/create a world, save, quit, logs | yes | yes | `launch`, `wait-ready`, `open`, `save`, `quit`, `logs` |
| Player and world state | yes | yes | `state`, `status` (renderer, streaming, memory) |
| Crosshair target | yes | yes | `looking-at` |
| Blocks: one, a box, nearest of a kind | yes | yes | `block`, `blocks`, `find-block` |
| Entities near the player | yes | yes | `entities [RADIUS] [TYPE]`; no single-entity detail |
| Inventory, armor, offhand, carried stack | yes | yes | `inventory` |
| Containers and stations: read, click slots | yes | yes | `screen`/`menu`, `click-slot ID`, `container X Y Z` |
| Crafting (grid, result, recipe book) | part | part | grid by `click-slot`; the recipe book only by `click-at` |
| Movement, look, path-finding | yes | yes | `move`, `goto`, `look`, `look-at`, `turn --over`, `mouse-move` |
| Act on the world | yes | yes | `break`, `place`, `interact`, `use-item`, `attack`, `select`, `drop` |
| Raw input: keys, mouse buttons | yes | yes | `key`, `mouse`, `release`; `key w down` stays held through `wait` until `key w up`, `release` or `stop` |
| Controllers | yes | yes | `pad` button/stick/trigger/status (a virtual pad) |
| Chat and commands | yes | yes | `chat`, `command`, `type`, `messages`, `chat-log` |
| Screens: which is open | yes | yes | `screen` gives a label (`title`, `options`, `inventory`...) but not the options page or sub-screen |
| Screens: widgets | part | part | `screen` lists **labelled buttons** only (label, bounds, enabled); sliders, fields, list rows, tabs and switches are invisible |
| Screens: act on a widget | part | part | `click-button LABEL` (buttons only), `click-at X Y`; no slider set, no field focus, no row select by id |
| Options | part | no | `options PAGE` opens a page and `render-distance N` sets one value; no read, no set of the other ~120 options |
| Packs (resource packs) | no | no | only through the Packs screen by pixel |
| F3 debug data | part | part | `status` has the overlay flags and the renderer; not the F3 lines |
| Screenshots | yes | yes | PNG of the next frame (works `--offscreen`) |
| Recording video | no | no | |
| Benchmarks and frame stats | yes | yes | `bench`, `stats`, `fly`, `--benchmark` |
| Multiplayer: connect, disconnect, respawn | yes | part | `connect`/`disconnect` are socket-only |
| LAN and friends hosting | yes | no | `lan open/close/status`, `friends host/stop/status` socket-only |
| Cheats and test hooks | yes | part | `give`, `time`, `setblock`, `summon`, `effect`; `xp`, `enchant`, `potion`, `trade`, `fill`, `particle`, `sculk` socket-only |
| Waits | part | part | `wait TICKS`, `wait-ready`; no "until screen X", "until chunks loaded", "until chat says Y" |
| Events | no | no | everything is polled |
| Errors with reasons | part | part | `{"error": "text"}`; horizon-ctl adds `kind` (`usage`, `connection`) to its own errors only |
| Capability | Screen | CLI before | MCP before | CLI after | MCP after | Notes |
| --- | --- | --- | --- | --- | --- | --- |
| Start, wait until ready, save, quit, log | (all) | yes | yes | yes | yes | `launch`, `wait-ready`, `save`, `quit`, `logs` |
| Every widget of every screen, by id; click, set, type | (all) | yes | yes | yes | yes | `ui`, `click ID`, `set ID VALUE`, `type`; `click-at`, `drag-at`, `scroll-at` by pixel |
| Title menu, pause menu | Title, Pause | yes | yes | yes | yes | `ui`/`click`, `pause`, `resume` |
| Worlds: list | Select World | part | part | yes | yes | `worlds` |
| Worlds: create, open | Create New World | yes | yes | yes | yes | `open WORLD [SEED] [creative]` |
| Worlds: rename, back up | Edit World | part | part | yes | yes | `world-rename`, `world-backup` |
| Worlds: delete | Select World | part | part | yes | yes | `world-delete FOLDER --confirm`; it was possible through `click` without any confirm |
| Servers list | Multiplayer | part | part | yes | yes | `servers` (names and addresses; reads servers.dat) |
| Join a server or an invite code, leave | Multiplayer | part | no | yes | yes | `connect`, `disconnect` |
| Open to LAN | Pause > Open to LAN | part | no | yes | yes | `lan open\|close\|status` |
| Play with Friends: host, stop, status | Pause | part | no | yes | yes | `friends host\|stop\|status` |
| Vanilla options, every page | Options | yes | part | yes | yes | `options-get`, `options-set` (all of options.txt, typed); `options PAGE` was socket-only |
| Horizon Settings: Graphics, Shader Packs, Controller, Extras, Mods, AI Agent | Horizon Settings | part | part | yes | yes | `options horizon\|graphics\|extras\|agent...`, then `ui`/`click`/`set` |
| Agent control on or off, status, connection details | Horizon Settings > AI Agent | no | no | yes | yes | new page (#1353) |
| Key binds | Controls > Key Binds | yes | yes | yes | yes | `options-set key_key.jump key.keyboard.j` |
| Resource packs, shader packs | Options > Resource Packs, Shader Packs | part | part | yes | yes | `options packs`, `options shader-packs`, then `ui` rows and `click`; `options-set resourcePacks` |
| Chat and commands | Chat | yes | yes | yes | yes | `chat`, `command`, `messages`, `chat-log` |
| Inventory, containers, stations | Inventory, Chest... | yes | part | yes | yes | `inventory`, `screen`, `click-slot`; `container X Y Z` was socket-only |
| Crafting, recipe book | Crafting | part | part | yes | yes | the grid by `click-slot`; the recipe book by `ui`/`click` |
| Trading, riding, shearing (right-click an entity) | Merchant, Horse | part | no | yes | yes | `interact-entity ID`; `mouse` was CLI-only |
| Horse, llama inventory | Horse | no | no | yes | yes | `mount-menu` |
| Books, lecterns, signs | Book, Sign | part | part | yes | yes | `book [next\|back\|take\|done]`, `signedit X Y Z` |
| Move, look, find a path | (playing) | yes | yes | yes | yes | `move`, `goto`, `look`, `look-at`, `turn`, `jump` |
| Mine, place, use, attack, hotbar, drop | (playing) | yes | yes | yes | yes | `break`, `place`, `interact`, `use-item`, `attack`, `select`, `drop` |
| Raw keys and mouse buttons | (all) | yes | part | yes | yes | `key`; `mouse`, `release` were CLI-only |
| Controllers | (all) | yes | no | yes | yes | `pad` |
| Respawn | Death | yes | yes | yes | yes | `respawn` |
| Screenshots | (all) | yes | yes | yes | yes | PNG of the next frame, `--offscreen` too |
| F3 data | F3 | yes | part | yes | yes | `key f3`; `status` (renderer, chunks, memory) was CLI-only |
| Waits and events | (all) | yes | yes | yes | yes | `wait`, `wait-for`, `events` |
| Effects, experience, enchantments, potions, fill | (cheats) | part | no | yes | yes | `effect`, `effects`, `xp`, `enchant`, `potion`, `fill` |
| Benchmarks and frame stats | (all) | yes | part | yes | yes | `bench`, `stats` were CLI-only; `fly` |
### After the PRs in [Status](#status)
## No AI
| Capability | Before | After |
| --- | --- | --- |
| Screens: widgets | labelled buttons only | every widget of every screen (`ui`): id, kind, label, bounds, slider value, tab selected, slots with stacks; both menu styles |
| Screens: act on a widget | `click-button LABEL`, `click-at X Y` | `click ID [right\|middle] [shift]`, `set ID VALUE` (sliders), `click` focuses fields |
| Options | open a page; `render-distance` only | `options-get` all 193 `options.txt` options typed with ranges/choices; `options-set` validates, applies, saves |
| Waits | `wait TICKS`, `wait-ready` | `wait-for screen\|widget\|loaded\|chat\|event` with timeout errors |
| Events | none (poll) | `events [--since SEQ]`: screen, chat, death, respawn, item, dimension, world |
| Launch headless | `--offscreen` by hand | `launch --offscreen` in horizon-ctl and its MCP; `launch_client {offscreen}` |
| The running game from the launcher's MCP | no (a second server) | every game tool as `game_*` through `horizon-launcher mcp` |
One switch hides and turns off every AI feature: `noAi:true` in `<game home>/horizon-extras.txt`.
The game home is `HORIZON_HOME`, else the data dir's `horizon`. The game reads its extras from
its working directory, which is that folder. `horizon_core::no_ai` reads and writes the switch:
## Design
- `is_on(home)` and `check(home)` read it;
- `set(home, on)` keeps the file's other lines, and writes no file to turn off a switch that was
never on;
- `REFUSAL` is the one line every surface prints.
### One vocabulary, four surfaces
The switch is in three places: Settings > AI in the launcher, Horizon Settings in the game
(`Item::NoAi`), and `horizon-launcher no-ai on|off`. When it is on:
| Surface | What happens |
| --- | --- |
| Game | opens no control socket, even with `--control` (it logs the refusal); Horizon Settings hides AI Agent...; turning it on in a running game closes the socket at once |
| `horizon-ctl` | every command refuses: exit status 4, `{"error": REFUSAL, "kind": "denied"}` |
| `horizon-ctl mcp` | refuses to start (exit 4, REFUSAL on stderr); a session already running refuses each call |
| `horizon-launcher mcp` | refuses to start; a running session answers each `tools/call` with error -32000 and REFUSAL |
| Launcher CLI | `mcp` and `agent-config` are hidden from the help and refuse |
| Launcher window | Settings > AI shows only the No AI switch, without Connect an AI agent |
| Companion (#1068) | uses the same switch (see horizon-parity companion-notes.md) |
Every other launcher command stays usable: versions, install, remove, prepare, play, server,
notes, links, account, settings, game-args, logs, update, desktop-entry, data,
modpack, mods, servers, no-ai and benchmark. None of them drives the game for an agent. The
launcher itself, packagers, the docs and players' scripts need them, and `no-ai` has to stay to
turn the switch off.
## Connecting
- **Launcher, Settings > AI > Connect an AI agent:**
- a client picker (Claude Code, Codex, Cursor, any MCP client) with its config and a Copy button;
- for clients with a CLI, the add command, shown and run only on **Add to ...**:
`claude mcp add --scope user horizon -- <exe> mcp`, `codex mcp add horizon -- <exe> mcp`;
- **Test the connection** (`agents::self_test`) starts `<exe> mcp`, lists its tools and says
how many answered.
- `horizon-launcher agent-config [--client ID] [--json] [--test]` prints the same thing.
- **Game, Horizon Settings > AI Agent:**
- **Agent Control** (`agentControl` in horizon-extras.txt, off by default) opens the default
endpoint (`$HORIZON_CONTROL`, else `horizon-control.sock` in the runtime directory) in a game
the player started. Turning it off closes the endpoint and stops its listener.
- The page shows whether a client is connected (`Server::clients`), when the last command came,
and the socket's name.
- **Copy Connection Details** copies the socket path, a `horizon-ctl --socket ... state` line
and an `mcpServers` config for this game's `horizon-ctl mcp`.
- **The default:** a game an agent starts (`play` in MCP, `horizon-ctl launch`, `--control`) is
under control. A game the player starts from the window is not, until they turn Agent Control
on. An open socket lets any program of that user drive the game, so it opens only when an agent
asked for the game, or when the player chose it.
## Design rules for a new command
### One vocabulary
- **A command has one name**, kebab-case, the same on the socket, in `horizon-ctl` and in the
launcher CLI. Its MCP tool is the name with `_` for `-` (`click-slot` → `click_slot`).
The launcher's MCP offers the game's tools under a `game_` prefix (`game_click_slot`) so they
never collide with its own (`logs` exists on both sides).
- **Arguments** are positional words then `--flags`; the `horizon-ctl` table (`Param`) is the
source of truth and generates the MCP `inputSchema`. A new game command is not done until it
is in that table.
launcher CLI. Its MCP tool is the name with `_` for `-` (`click-slot` is `click_slot`). In the
launcher, a subcommand's words are joined (`mods search` is `mods_search`). The launcher's MCP
offers every game tool as `game_<name>`, so none collides with its own (`logs` is on both
sides). A launcher tool whose name starts with `game_` (`game_args`) is matched first.
- **Arguments:** positional words, then `--flags`.
- The game: the `horizon-ctl` table (`Param`) is the source of truth. It generates the MCP
`inputSchema` and the reference. A game command is not done until it is in that table.
- The launcher: the clap definition is the source of truth. Give every argument a help line;
it becomes the tool's description.
- **Replies are one JSON object.** A query returns its data; an action returns
`{"ok": true, ...}` plus what changed (`clicked`, `screen`, `drops`...).
- **Errors** are `{"error": "<sentence an agent can act on>", "kind": "<reason>"}`. Kinds:
`usage` (bad or missing argument), `unknown` (no such command, widget, option, entity),
`state` (the game is not in a state that allows it: no world, wrong screen, disabled
widget), `busy` (another action or benchmark runs), `timeout`, `connection` (game not
reachable), `denied` (needs consent, below). The message names what to do next
("no world open; use: open WORLD").
- **Shapes are shared**: a position is `[x, y, z]`; a block is
`{"pos", "block", "state", "loaded"}`; an item stack is `{"item", "count", "damage"?,
"components"?}`; a slot is a stack plus `"slot": ID` (the slot ids of
`click-slot`); bounds are `[x, y, w, h]` in GUI pixels, the coordinates of `click-at`.
- **Errors** are `{"error": "<sentence an agent can act on>", "kind": "<reason>"}`. The kinds:
- `usage`: a bad or missing argument;
- `unknown`: no such command, widget, option or entity;
- `state`: the game is not in a state that allows it (no world, wrong screen, disabled widget);
- `busy`: another action or a benchmark is running;
- `timeout`;
- `connection`: the game can't be reached;
- `denied`: No AI is on (exit status 4).
### Structured UI: the widget tree
The message names what to do next ("no world open; use: open WORLD").
- **Shapes are shared:**
- a position is `[x, y, z]`;
- a block is `{"pos", "block", "state", "loaded"}`;
- an item stack is `{"item", "count", "damage"?, "components"?}`;
- a slot is a stack plus `"slot": ID` (the slot ids of `click-slot`);
- bounds are `[x, y, w, h]` in GUI pixels, the coordinates of `click-at`.
`ui` returns every interactive element the last frame drew, on every screen (title menus,
pause, options pages, inventories and stations, chat, death, Horizon-style menus):
### Safety
- **Local only.** The socket is a Unix socket in the user's runtime directory, or a TCP port on
127.0.0.1 behind a 128-bit token in a file only the user can read. It is never `0.0.0.0` and
never a network listener. Both MCP servers use stdio.
- **Confirm what can't be undone.** A command that deletes the player's things requires
`confirm` and carries the MCP `destructiveHint`. In the game these are `world-delete`, `fill`
and `setblock` (the table's `DESTRUCTIVE`); in the launcher, `remove`, `modpack remove`,
`mods remove`, `servers forget`, `account sign-out` and `data delete` (`cli_tools::DESTRUCTIVE`).
Without `confirm: true` the call is refused and the message says to ask the player. In the game
CLI the flag is `--confirm`. The launcher CLI asks nothing: a person typing `remove` meant it.
- **Ask before reaching out.** A command that sends data or reaches other people carries
`openWorldHint`, and its description says "only when the player asks". In the game these are
`connect`, `lan`, `friends`, `chat` and `command`; in the launcher, `data allow`, `data send`,
`data bug`, `data benchmark` and `servers create`. `play`'s `join` argument says the same.
Telemetry stays opt-in, and only `data allow` turns it on.
- **No secrets.** No surface returns tokens, session files, keychain entries or invite secrets
the player didn't ask to share:
- accounts are names and UUIDs;
- sign-in is a device code the player enters;
- `--session-file` is read once and deleted;
- `servers` reads names and addresses only.
- **Vanilla behaviour untouched.** Control code reads state and synthesizes the input events a
player produces; registering widgets for the tree draws nothing. A change to game files runs
`tools/parity.py --changed origin/main`.
### The widget tree
`ui` returns every interactive element the last frame drew, on every screen:
```json
{"screen": "options", "gui_size": [427, 240], "frame": 3061,
"widgets": [
{"id": "fov", "kind": "slider", "label": "FOV: 70", "bounds": [40, 50, 150, 20], "enabled": true, "value": 0.5},
{"id": "video-settings", "kind": "button", "label": "Video Settings...", "bounds": [...], "enabled": true},
{"id": "row-2", "kind": "row", "bounds": [...], "enabled": true},
{"id": "done", "kind": "button", "label": "Done", "bounds": [...], "enabled": true}]}
```
- **Ids are stable and readable**: the label up to its `:` as a slug (`FOV: 70` → `fov`,
`Video Settings...` → `video-settings`); a repeated slug gets `-2`, `-3` in draw order;
unlabelled elements are `<kind>-<n>` in draw order. The id of a slider does not change
when its value (and so its label) does. World, server and language rows carry their
names; Horizon-style switches, sliders and segments carry their settings row's caption
(`vsync`, `menu-style-horizon`); inventory, creative and menu slots are `slot-<ID>` with
their stack (an item tab's display slots are `slot-900` up).
- **Kinds**: `button`, `slider` (`value` 0..1 as drawn), `field` (text box), `row` (list
entry: world, server, pack, language), `tab` (`selected`), `slot`.
- **Actions by id**: `click ID [right|middle]` (move the pointer there and click, exactly as a
player would; `middle` is the pick block button, which clones a stack in creative), `set ID VALUE` (a slider to a 0..1 position, a click on its track, as vanilla
`AbstractSliderButton.onClick` reads the pointer). `type TEXT` keeps typing into the focused
field; `click` on a field focuses it. After a click or a set, the next `ui`, `click` or
`set` waits for a redrawn frame, so it never reads the screen the click left.
- **No new code paths in screens**: the tree is built from what the draw functions already
register for the controller's focus navigation (`widgets.rs`), so every screen that a
controller can drive is in it, and clicks go through the same window events as the mouse.
- **Ids are stable and readable.** An id is the label up to its `:`, as a slug (`FOV: 70` is
`fov`, `AI Agent...` is `ai-agent`). A repeated slug gets `-2`, `-3`; unlabelled elements are
`<kind>-<n>`. A slider's id doesn't change with its value. Slots are `slot-<ID>` with their
stack.
- **Kinds:** `button`, `slider` (`value` 0..1), `field`, `row` (a world, server, pack or
language), `tab` (`selected`), `slot`.
- **Actions:**
- `click ID [right|middle] [shift]` clicks where the mouse would.
- `set ID VALUE` moves a slider.
- `type` types into the focused field.
### Options
After a click, the next `ui`, `click` or `set` waits for a redrawn frame.
- **No new code paths in screens.** The tree is built from what the draw functions already
register for controller navigation (`widgets.rs`).
- `options-get [KEY...]`: every option of `options.txt` by its vanilla key, with its value
and what it accepts: `{"key": "fov", "value": 70, "type": "int", "min": 30, "max": 110}`,
enums with `choices`, key bindings as `key.keyboard.w`. Next: Horizon's own files
(`horizon-graphics.txt`, `horizon-controller.txt`, extras) under their own keys.
- `options-set KEY VALUE`: validated like vanilla's `OptionInstance.set` (out of range is an
error here, not a silent reset), applied at once as the options screen would apply it, and
saved. Reply: the new value.
- `options [PAGE]` keeps opening a page for screenshots and for `ui`.
### Waits and events
### Inventory, containers, world, entities
- `wait-for screen NAME|widget ID|loaded|chat TEXT|event KIND [--timeout S] [--since SEQ]`
replies when the condition holds, or with `kind: timeout`.
- `events [--since SEQ]` returns what happened since SEQ: screens, chat, deaths, respawns, items,
dimensions and worlds (the newest 256). Take `last` before an action, and wait with `--since`,
so the action's event can't slip in before the wait.
The existing commands stay and keep their shapes: `inventory`, `screen`, `click-slot`,
`block`, `blocks`, `find-block`, `entities`, `looking-at`. Planned additions: `entity ID`
(full detail: equipment, effects, passengers, AI state), `entities` filters by position and
radius around any point (`--at X Y Z`), and `blocks --of BLOCK` to keep a box query small.
## Tests
### Waits
- **Unit tests:**
- horizon-ctl: the table, the schemas, the reference, the No AI refusal, the destructive and
network annotations;
- the launcher: generated tools, `confirm`, the reference, the agent configs;
- `horizon_core::no_ai`;
- `options_ui`: the AI Agent page, and that No AI hides it.
- **`tools/agent_control_e2e.py`** drives a real game, offscreen on macOS and on a virtual screen
on Linux, through the CLI and MCP:
- `survival`, `ui`, `options`, `events`, `consume`, `pick`, `suggestions`;
- `manage`: worlds, servers, effects, books, LAN, the options pages and `confirm`;
- `no-ai`: every surface refuses;
- `setting`: Agent Control on opens the endpoint, the AI Agent page, Copy, and off closes it.
- **`tools/launcher_mcp_e2e.py`** drives `horizon-launcher mcp`: the generated tools, `play` and
the `game_*` tools, `confirm`, `agent-config` and `--test`, and No AI.
`wait-for CONDITION [--timeout S] [--since SEQ]` replies when the condition holds, or with
an error of kind `timeout` saying what screen it ended on (`wait TICKS` waits for ticks):
## Later
- `screen NAME` (the label `state` shows), `widget ID` (a widget is on screen),
- `loaded` (a world is open, the player exists and no chunk is pending),
- `chat TEXT` (a new chat line containing TEXT), `event KIND` (an event of that kind);
both count from `--since SEQ`, else from now: take `last` from `events` before an action
so its event can't slip in before the wait starts.
These are tracked in FEATURES.md (LATER):
### Events
`events [--since SEQ]` returns what happened since SEQ, oldest first, and `last`, the SEQ to
pass next time (the game keeps the newest 256):
```json
{"event": "world", "seq": 1, "tick": 0, "state": "opened", "name": "Survival"}
{"event": "screen", "seq": 2, "tick": 0, "from": "title", "to": "playing"}
{"event": "item", "seq": 3, "tick": 110, "item": "minecraft:oak_log", "delta": 3}
{"event": "chat", "seq": 4, "tick": 140, "text": "[Player] hello"}
{"event": "death", "seq": 7, "tick": 300}
{"event": "respawn", "seq": 9, "tick": 330}
{"event": "dimension", "seq": 12, "tick": 900, "from": "minecraft:overworld", "to": "minecraft:the_nether"}
```
Events are found by comparing state once per event loop turn on the game thread, and only
under `--control` (no hooks inside game logic), so they cannot change what the game does.
Next: `subscribe [KIND...]`, the same events as a stream on one connection, for clients that
keep one open (MCP tools reply once, so `events` is what MCP offers).
### The launcher's MCP proxies the game
An agent configures one MCP server, `horizon-launcher mcp`. It runs the selected version's
`horizon-ctl mcp` (shipped beside the game) as a child and lists every one of its tools as
`game_<name>` (all but `launch`), passing calls and results (images included) through, so
the game's tools are defined once, in horizon-ctl's table. `launch_client` starts the game
with a control socket in the launcher's data folder (`world`, `creative`, `offscreen`
optional) and returns once it answers. While no game listens, `game_*` calls fail with
`kind: "state"` and say to call `launch_client`. A game the player starts from the window
is not under control.
### Safety
- **Local only.** The socket is a Unix socket in the user's runtime directory, or a TCP port
on 127.0.0.1 behind a 128-bit token in a file only the user can read. Never `0.0.0.0`,
never a network listener; the launcher's MCP is stdio.
- **No secrets.** No surface returns tokens, session files or keychain entries: accounts are
names and UUIDs, `--session-file` is read once and deleted, and `options-get` leaves out
nothing secret because `options.txt` holds none (server addresses are in `servers.dat`,
which no command reads).
- **Consent for anything that sends data.** Commands that reach the network (`connect`,
`chat`/`command` on a server, `lan open`, `friends host`, `install_version`,
`check_updates`, telemetry) carry the MCP `openWorldHint` annotation and their description
says "only when the player asks". Telemetry stays opt-in (PR #250); no agent command turns
it on. Destructive ones (`remove_version`, `sign_out`, `fill`, `setblock`) carry
`destructiveHint`.
- **Vanilla behaviour untouched.** Control code reads state and synthesizes the same input
events a player produces; registering widgets for the tree draws nothing. Every PR that
touches game files runs `tools/parity.py --changed origin/main`.
## Status
| Step | PR |
| --- | --- |
| This document | #321 |
| `ui`, `click ID`, `set ID VALUE`: the widget tree of every screen | #349 |
| `options-get` / `options-set` | #350 |
| `wait-for`, `events` | #351 |
| The launcher's MCP proxies the game (`game_*`), `launch_client` under control | #342 |
| Next: `subscribe` (a stream), error `kind` on every game error, MCP annotations (`openWorldHint`, `destructiveHint`) | |
| Next: `entity ID`, `entities --at`, packs (`packs list|enable|disable`), F3 lines, Horizon's own option files, launcher settings over CLI/MCP | |
Each PR adds its tests: unit tests next to the code, and scenarios in
`tools/agent_control_e2e.py` (`survival`, `ui`, `options`, `events`; CLI and MCP) and
`tools/launcher_mcp_e2e.py`, which drive the real game offscreen on macOS or on a virtual
screen on Linux. `tools/lan_e2e.py` runs two games at once, a host that opens its world to LAN
and a guest that joins it, and checks from both sides what a guest sees and can do (player
list, own model, armour, name tags, chest lids, crafting, fall damage).
- Horizon's own option files by key (`horizon-graphics.txt`, controller, extras) next to
`options-get` and `options-set`.
- Adding and removing saved servers by command.
- `subscribe`: events as a stream on one connection.
- Launcher window screenshots in this page's PRs.
- No AI changed in the launcher while a game is open: the game rewrites its extras when it saves.
- A confirmation question in the launcher CLI for destructive commands.
+57
View File
@@ -0,0 +1,57 @@
# Architecture: feature → files → checks
The 40 areas changed most often in the 30 days to 2026-10-23 (commits on main touching the area; `game.rs` is
counted only for the game loop because nearly every gameplay change touches it). The crate map, how `Game` is
organised and how to build and test are in [AGENTS.md](../AGENTS.md).
Paths: `L/` = `crates/horizon-client/src/`, `G/` = `crates/horizon-client/src/game/`, `W/` =
`crates/horizon-world/src/`. Checks: a bare name is a harness (`python3 tools/parity.py <name>`, script
`tools/test_<name>_parity.py`); `lan_e2e <check>` is `python3 tools/lan_e2e.py --check <check>`.
For the full set of harnesses a file can affect, ask the runner:
`printf '%s\n' <paths> > /tmp/p.txt && python3 tools/parity.py --changed-files /tmp/p.txt --list`.
Any file of the game binary (`game.rs`, `game/`) selects the ~25 harnesses that run the binary; a client lib
file selects ~103.
| # | Area (commits) | Files | Checks |
|---|---|---|---|
| 1 | Game loop, tick order, frame pacing (554) | `L/game.rs` (`fn tick`, `fn tick_world`, `fn render`, `about_to_wait`), `L/clock.rs`, `L/window.rs`, `L/spans.rs` | game_loop, frame_limiter, interaction_input, tick |
| 2 | Mobs in the game loop, spawning (166) | `G/creatures.rs`, `G/natural_spawning.rs`, `L/mobs/spawning.rs`, `L/mobs/spawn_rules.rs`, `L/mobs/spawn_selection.rs`, `L/mobs/finalize.rs`, `G/spawner.rs`, `G/trial_spawner.rs` | natural_spawn, spawn_rules, finalize_spawn, spawner, trial_spawner, mob_ai |
| 3 | World save and load (163) | `L/save.rs`, `G/saving.rs`, `G/persist.rs` (entities), `L/entity_nbt.rs`, `L/block_entity_nbt.rs`, `W/region.rs`, `W/nbt.rs` | save_roundtrip, world_reopen, world, datafix |
| 4 | World generation (153) | `W/worldgen.rs`, `W/worldgen/` (`generator*.rs`, `feature_graph.rs`, `structure/`, `placement/`), `L/vanillagen.rs` | chunk_generation, worldgen, server_world_gen, world_spawn, feature_graph, feature_placement, decoration and the other worldgen harnesses |
| 5 | Multiplayer client, packets in (145) | `G/remote.rs` (`fn handle_packet`, `fn tick_remote`), `G/remote_*.rs`, `L/net.rs` | dedicated_server, server_entities, lan_e2e (all) |
| 6 | Agent control, horizon-ctl (145) | `L/control.rs`, `L/bin/horizon-ctl/`, `G/control.rs`, `G/agent.rs`, `G/events.rs`, `G/ui_control.rs` | `python3 tools/agent_control_e2e.py`; `cargo test -p horizon-client --bin horizon-ctl` |
| 7 | CI and release (134) | `.github/workflows/` (`ci.yml`, `parity.yml`, `release.yml`, `launcher.yml`), `tools/ci/`, `tools/parity.py`, `tools/pr_ready.py` | `python3 -m unittest discover -s tests`; actionlint (`.github/actionlint.yaml`) |
| 8 | LAN host: connections, play state, tracking (133) | `L/lan/` (`conn.rs`, `hub.rs` + `hub/`, `chunks.rs`, `entity.rs`, `tracking.rs`, `guest.rs`, `playerdata.rs`), `G/lan.rs` | lan, lan_e2e (all), `cargo test -p horizon-client --test lan_bot` |
| 9 | Renderer core (132) | `L/gfx.rs` (`Renderer::new`, `Renderer::render`), `L/gfx/` (cull, occlusion, translucency, upload, timing, lod) | client_graphics, culling_rays, translucency; `horizon-client --benchmark standard` |
| 10 | Launcher (124) | `launcher/src/` (`main.rs`, `backend.rs`, `cli.rs`, `mcp.rs`, `servers_page.rs`) | `cd launcher && cargo test`; `python3 tools/launcher_mcp_e2e.py` |
| 11 | Mob types and species (117) | `L/mobs.rs`, `L/mobs/species.rs`, `L/mobs/data.rs`, `L/mobs/living.rs`, `L/mobs/drops.rs`, `L/mobs/gear.rs` | mob_attributes, entity_attribute, entity_death_loot, mob_ai |
| 12 | Guests' actions on a server (98) | `G/lan_actions.rs` (`fn as_guest`, `fn tick_guests`), `G/lan_{attributes,pvp,chat,crafting,stations,trading,mount_menu,waypoints}.rs` | server_player_combat, server_player_damage, server_player_targets, lan_e2e (all) |
| 13 | Modpack porting, mod content (97) | `crates/horizon-port-pack/`, `L/mod_content.rs`, `tools/port_*.py`, `packs/` | `cargo test -p horizon-port-pack`; `python3 tools/mod_port_harness.py` |
| 14 | Mob AI (96) | `L/mobs/ai.rs`, `goals.rs`, `brain.rs`, `*_brain.rs`, `nav.rs`, `path.rs`, `control.rs` | mob_ai (probe `examples/mob_ai_probe.rs`; known failure on main: drowned_*, #290) |
| 15 | Items and item use (96) | `L/items.rs`, `L/item_data.rs`, `G/hand.rs`, `G/consume.rs`, `G/potions.rs`, `L/effects.rs`; game.rs `fn use_hand`, `fn use_item` | use_item_on, item_use, item_use_lifecycle, consumable, consume_effect, status_effect |
| 16 | Options and settings screens (93) | `L/options_ui.rs`, `G/options.rs`, `L/settings.rs`, `L/options_file.rs`, `L/graphics_ui.rs`, `L/graphics.rs` | options, toggle_keys |
| 17 | HUD, chat, tab list (93) | `L/hud.rs`, `L/hud_layout.rs`, `L/hud_overlays.rs`, `L/chat.rs`, `G/chat.rs`, `L/tab_list.rs`, `L/locator_bar.rs`, `G/locator_bar.rs` | hud, tab_list, locator_bar, chat_screen, secure_chat |
| 18 | Command execution (88) | `G/commands.rs`, `G/commands/*.rs`, `L/scoreboard_cmd.rs`, `L/data_cmd.rs`, `G/functions.rs` | command_exec (corpus `tools/command_exec_corpus.py`), scoreboard, server_ops_feedback, lan_e2e commands |
| 19 | Chunk streaming, light, tickets (85) | `L/streaming.rs`, `L/world.rs`, `L/chunk.rs`, `L/chunk_map.rs`, `L/light.rs`, `L/ticket_levels.rs`, `L/tick_chunk_membership.rs`, `G/world_loading.rs` | light, chunk_status, random_tick_sections; `cargo test -p horizon-client --test streaming_meshes` |
| 20 | Mob models and animation (78) | `L/mobs/render.rs`, `L/mobs/anim.rs`, `L/mobs/body_anim.rs`, `L/mobs/keyframes.rs`, `L/entity.wgsl` | entity_model |
| 21 | Block behaviour, server side (78) | `W/level/` (`mod.rs`, `tick.rs`, `hooks.rs`, `data.rs`, `redstone.rs`, `place.rs`), `G/block_entity_ticks.rs`, `G/moving_pistons.rs` | block_update, redstone, random_tick, simple_block, piston_movement, block_entity_tickers |
| 22 | Player movement and collision (75) | `L/motion.rs` + `L/motion/`, `L/collisions.rs`, `W/entity_move.rs`, `W/player_travel.rs`, `W/collision.rs` | collision, entity_move, player_travel, living_motion, climbing, swimming; `python3 tools/test_native_scene_motion.py` |
| 23 | Resource packs and models (65) | `L/packs.rs` + `L/packs/`, `L/pack_screen.rs`, `L/atlas_sources.rs`, `L/sprites.rs`, `L/model_library.rs`, `G/packs.rs`, `crates/horizon-assets/` | resource_pack, pack_selection, pack_screen, model_resolution, item_model, mipmap |
| 24 | Container menus and inventory (61) | `L/menu.rs`, `L/container_screen.rs`, `L/containers.rs`, `L/creative.rs`; game.rs `fn menu_ops`, `fn click_inventory` | menu_click, container_screen, creative, lan_e2e containers clicks |
| 25 | Workstations (60) | `L/stations.rs`, `G/stations.rs`, `L/enchant.rs`, `L/brewing.rs` | enchanting, screen_layout, lan_e2e brewing loom stonecutter grindstone anvil smithing |
| 26 | Crafting and the recipe book (59) | `L/crafting.rs`, `L/recipe_book.rs`, `L/recipe_book_screen.rs`, `G/recipe_book.rs`, `G/machines.rs`, `G/machines/crafter.rs` | recipe, recipe_book, recipe_book_view, place_recipe, ghost_recipe, crafter |
| 27 | Vehicles and mounts (54) | `G/boats.rs`, `G/minecarts.rs`, `G/mounts.rs`, `G/mount_menu.rs`, `G/llamas.rs`, `G/passengers.rs` | server_entities, lan_e2e boats minecarts riding mounts |
| 28 | Villagers, trading, raids (50) | `L/mobs/villager*.rs`, `L/merchant.rs`, `G/trading.rs`, `G/villagers.rs`, `L/raid.rs`, `G/raids.rs`, `L/gossip.rs` | trading, raid, mob_ai |
| 29 | Title, worlds, startup (49) | `L/title.rs` + `L/title/`, `G/startup_menu.rs`, `L/title_edition.rs` | world_options; `cargo test -p horizon-client --lib title` |
| 30 | Dedicated server, horizon-server (48) | `G/dedicated.rs`, `G/dedicated/status.rs`, `crates/horizon-server/`, `crates/horizon-server-files/` | dedicated_server, server_files, user_cache, online_mode, server_ops_feedback |
| 31 | Particles and client effects (46) | `L/particles.rs`, `G/render_tick.rs`, `G/level_particles.rs`, `L/animate_tick.rs` | particle_providers, block_particles, entity_particles, emitter_particles, marker_particles |
| 32 | Bosses and the End (45) | `G/dragon.rs`, `G/wither.rs`, `G/end.rs` | server_dragon, end_podium, end_gateway |
| 33 | Protocol and packets (44) | `crates/horizon-protocol/src/` (`packets/play.rs`, `entity_data.rs`, `connection.rs`) | dedicated_server, online_mode, secure_chat; `cargo test -p horizon-protocol` |
| 34 | Multiplayer and LAN screens, friends (44) | `L/multiplayer.rs`, `G/lan_screen.rs`, `G/friends.rs`, `L/friends_screen.rs`, `crates/horizon-friends/`, `crates/horizon-relay/` | lan, world_options; `python3 tools/test_friends.py` |
| 35 | Dispensers (43) | `G/dispenser.rs`, `G/dispense_fixture.rs` (the harness side) | dispenser |
| 36 | Audio and music (38) | `L/audio.rs`, `L/sound_engine.rs`, `L/sound_events.rs`, `L/music.rs`, `G/music.rs`, `L/ambience.rs`, `G/subtitle_hud.rs` | sound_engine, sound_event, music, situational_music, ambient_sound, subtitle |
| 37 | Integrated server and levels (34) | `G/integrated.rs`, `G/levels.rs`, `G/server_travel.rs` | server_dimension_players, `lan_e2e --server-thread` (portals, levels, distance, lava) |
| 38 | Command parsing (34) | `L/command/` (`args.rs`, `selector.rs`, `tree_*.rs`, `vanilla.rs`) | command_parse (corpus `tools/command_parse_corpus.py`) |
| 39 | Benchmarks and telemetry (34) | `L/benchmark.rs`, `tools/perf_bench.py`, `L/telemetry.rs`, `crates/horizon-telemetry*/`, `crates/horizon-bench/` | `python3 -m unittest tests.test_perf_bench`; [benchmark.md](benchmark.md) |
| 40 | Explosions and TNT (31) | `G/explosion.rs`, `G/tnt.rs` | lan_e2e blast; no dedicated harness yet |
+7 -4
View File
@@ -20,7 +20,7 @@ kilobytes whatever the frame rate. Measured numbers are rounded to 3 decimals.
"app": { "name": "horizon-client", "version": "0.21.0", "commit": "e96e1571" },
"hardware": {
"os": "macos", "os_version": "27.0", "arch": "aarch64",
"cpu": "Apple M4 Pro", "cpu_threads": 14, "ram_mb": 65536,
"cpu": "Apple M4 Pro", "cpu_threads": 14, "cpu_cores": 14, "ram_mb": 65536, "storage": "nvme", "form": "desktop",
"gpu": { "name": "Apple M4 Pro", "vendor": "apple", "driver": "", "backend": "metal", "kind": "integrated" },
"display": { "width": 2560, "height": 1440, "scale": 2.0, "refresh_hz": 60 }
},
@@ -58,9 +58,12 @@ one (histogram edges included) makes it 2.
optionally `commit` (Horizon builds) and `mods` (`[{ "name", "version" }]`, vanilla with mods).
**`hardware`.** `os` (`macos`, `linux`, `windows`), `os_version`, `arch`, `cpu` (brand string),
`cpu_threads`, `ram_mb`; `gpu` (`name`, `vendor`, `driver`, `backend`: `metal`, `vulkan`, `dx12`, `gl`;
`kind`: `integrated`, `discrete`, `virtual`, `cpu`, `other`) and `display` (the screen the window was on:
`width`, `height` in physical pixels, `scale`, `refresh_hz`) when known. Any field can be missing.
`cpu_threads`, `cpu_cores` (physical), `cpu_base_mhz` and `cpu_boost_mhz` (where the OS gives them; not on
Apple silicon), `ram_mb`, `storage` (the drive under the game folder: `nvme`, `ssd`, `hdd`), `form` (`laptop`,
`desktop`); `gpu` (`name`, `vendor`, `driver`, `backend`: `metal`, `vulkan`, `dx12`, `gl`;
`kind`: `integrated`, `discrete`, `virtual`, `cpu`, `other`; `vram_mb`, a discrete GPU's own memory) and
`display` (the screen the window was on: `width`, `height` in physical pixels, `scale`, `refresh_hz`) when
known. Any field can be missing. On mains or battery is `conditions.power`.
**`conditions`.** What has to match for two reports to be compared, all optional: `scenario`, `seed`,
`render_distance`, `simulation_distance`, `window` (`[width, height]` actually rendered), `vsync`,
+3 -3
View File
@@ -4,7 +4,7 @@
## What is measured
One game is started per render distance (8, 16 and 32 chunks by default), each from a fresh world, so nothing generated by an earlier run is reused. In each game:
One game is started per window size (1280x720 and 1920x1080 by default) and render distance (8, 16 and 32 chunks by default), each from a fresh world, so nothing generated by an earlier run is reused. In each game:
1. **Start to the title screen.** Wall-clock time from starting the process to the first frame of the title screen with no loading overlay.
2. **Create the world.** A creative world named `PerfBench`, seed 1234, default world type and difficulty, created the way the game's own Create World does. **Start to in-world** is the time from starting the process until the player has spawned and every chunk around the spawn is loaded and drawn.
@@ -16,7 +16,7 @@ One game is started per render distance (8, 16 and 32 chunks by default), each f
- **Same machine, same run conditions.** Games run one at a time; the load average before and after each run and the machine (CPU, RAM, OS) are stored with the results. Runs on a machine doing other work are marked as such and not published.
- **Same settings, one file.** Every game gets the same `options.txt`, written by the driver: render distance, simulation distance 12, unlimited frame rate (`maxFps:260`), VSync off, FOV 70, automatic GUI scale, windowed, no pause on lost focus, and `inactivityFpsLimit:minimized` (both games otherwise drop to 30 FPS after a minute without input). Everything else stays at vanilla's defaults: Horizon reads vanilla's `options.txt` keys and its defaults match vanilla's (the options harness checks it), and Horizon's own settings (`horizon-graphics.txt`) are left at their defaults, which render as vanilla does.
- **Same resolution.** Both windows are 1280x720 (Horizon's default window; vanilla gets `--width 1280 --height 720`). The size each game actually renders at is stored with the results.
- **Same resolution.** Both games get the same window size, `--width` and `--height` (vanilla's own launch arguments, which Horizon takes too): 1280x720, the size results were first published at, then 1920x1080, the commonest screen; `--sizes` picks others. The size each game actually renders at is stored with the results: a compositor or screen smaller than the window can shrink it.
- **Same world and path.** Same seed and world type; same paths, yaw and pitch, same flight speed; the same steps in the same order. Vanilla is driven by a small dev-only Fabric mod (`mods/horizon/src/bench`), which only calls the game's own code: it creates the world with `WorldOpenFlows.createFreshLevel` as the Create World screen does, teleports with `/tp`, sets the time with `/time set`, and places the player on the path each frame as Horizon's `horizon-ctl fly` does.
- **Warm-up excluded.** Each scene's flight starts only after its chunks are loaded and drawn and 2 seconds have passed; the load itself is reported separately. JIT warm-up of the JVM during the first scene is part of vanilla's real behaviour and is not removed.
- **The same statistics code.** Horizon returns its raw frame times (`horizon-ctl fly ... raw`) and the vanilla mod writes its own; `stats()` in the driver computes every figure for both.
@@ -55,7 +55,7 @@ python3 tools/perf_bench.py --game vanilla-mods --label mods-mine
python3 tools/perf_bench.py --table horizon-mine vanilla-mine mods-mine
```
Options: `--distances 8,16`, `--scenes village,ocean`, `--seconds 20`, `--repeats 5`, `--heap 4G` (vanilla), `--offscreen` (Horizon, for locked or headless sessions). Results go to `benchmarks/perf/<label>-rd<N>.json`, one [benchmark report](benchmark-report.md) per render distance (the same format the game's `--benchmark` and the launcher write), with the load average before each game; each game's log, and the vanilla driver's event log, stay in `.local/perf-bench/`. Keep the machine otherwise idle, plugged in, and the window on a screen.
Options: `--distances 8,16`, `--sizes 1920x1080`, `--scenes village,ocean`, `--seconds 20`, `--repeats 5`, `--heap 4G` (vanilla), `--offscreen` (Horizon, for locked or headless sessions). Results go to `benchmarks/perf/<label>-rd<N>.json` at 1280x720 and `<label>-1080p-rd<N>.json` at 1920x1080 (other sizes `<label>-<W>x<H>-rd<N>.json`; `--table` takes those labels), one [benchmark report](benchmark-report.md) per window size and render distance (the same format the game's `--benchmark` and the launcher write), with the load average before each game; each game's log, and the vanilla driver's event log, stay in `.local/perf-bench/`. Keep the machine otherwise idle, plugged in, and the window on a screen.
## Results
+15 -19
View File
@@ -97,9 +97,8 @@ real mouse hands control back at once.
Every interactive rectangle a screen draws registers itself as a focus
target with its kind (`widgets::target_as`): classic buttons, sliders, edit
boxes and list rows (worlds, servers, languages), every Horizon-style widget
(`ui_theme::Ui::interact`: sidebar items, switches, segments, sliders,
fields, buttons), inventory and container slots, creative and recipe-book
boxes and list rows (worlds, servers, languages), icon buttons (the title's
and pause menu's Friends button), inventory and container slots, creative and recipe-book
tabs, and the stations' own buttons (trades, loom patterns, beacon effects,
enchantments, stonecutter recipes, the recipe book's recipes, pages and
filter). A screen that registers nothing falls back to the pointer.
@@ -137,16 +136,11 @@ the crafting result, armour to the player's grid.
- **Where focus lands** when a screen opens: the held hotbar slot in an
inventory, else the first button.
How it looks follows the menu style:
- **Classic screens** look as vanilla's own keyboard focus does: buttons,
sliders and slots show their highlighted sprite (`isHoveredOrFocused`,
drawn because the hidden pointer is over them), and list rows and text
fields get vanilla's white one-pixel outline (`AbstractSelectionList`'s
focused selection, `EditBox`'s highlighted border).
- **Horizon-style screens** get the design system's focus colour: a two-dp
ring in the accent colour around the focused widget, pill-shaped on
buttons, tabs and sliders.
It looks as vanilla's own keyboard focus does: buttons, sliders and slots
show their highlighted sprite (`isHoveredOrFocused`, drawn because the hidden
pointer is over them), and list rows and text fields get vanilla's white
one-pixel outline (`AbstractSelectionList`'s focused selection, `EditBox`'s
highlighted border).
### Pointer
@@ -183,8 +177,8 @@ Steam + X opens it at any time. "On-Screen Keyboard: Auto / Horizon / Steam"
Both modes reach every screen through the pointer events. Focus mode
registers targets on: the title menus (main, world list and its search, create
and edit world, delete, multiplayer list and its edit screens), every options
page (classic pages and the Horizon-style sections, key and controller binds,
language list), pause, death, chat, signs and books (their buttons), the
page (vanilla's and Horizon Settings with the pages it opens, key and
controller binds, language list), pause and Play with Friends, death, chat, signs and books (their buttons), the
survival and creative inventories, every container and station (chests,
furnaces, brewing, crafter, crafting table with its recipe book, anvil,
grindstone, smithing, stonecutter, loom, cartography, enchanting, beacon,
@@ -212,8 +206,10 @@ hints, "Press X to dismount") only while the pad is the last-used input.
## Options and remapping
Controller settings are Horizon's own and live in `horizon-controller.txt`
next to `options.txt`, like `horizon-graphics.txt`: `options.txt` stays
Controller settings are Horizon's own: **Options → Controls → Controller
Settings...** (or **Options → Horizon Settings... → Controller Settings...**),
a vanilla options list with **Controller Binds...** at the top. They live in
`horizon-controller.txt` next to `options.txt`, like `horizon-graphics.txt`: `options.txt` stays
exactly vanilla's, so a vanilla client can share the game folder.
```
@@ -490,8 +486,8 @@ The first round (input layer, menus, glyphs and options, rumble) shipped in
PRs #120, #129, #145 and #149. The second round, each shippable alone:
1. **Focus navigation** (this section above): the menu navigation option,
focus targets and vanilla's arrow-key step, the focus highlight in both
menu styles, the on-screen keyboard.
focus targets and vanilla's arrow-key step, vanilla's focus highlight,
the on-screen keyboard.
2. **Button prompts**: contextual hints with the pad's glyphs in menus and
optionally in game, and rebinding from them.
3. **DualSense output** (above): the HID output layer and rumble through it
+47 -19
View File
@@ -1,8 +1,9 @@
# Horizon's design system
One design language for the launcher, the website and the game's own menus (what "Menu style:
Horizon" draws). Vanilla's classic screens and the HUD are not part of it: they stay exactly
vanilla, because parity is the point of the game.
One design language for the launcher, the website and the few overlays the game draws that
vanilla has no screen for (the on-screen keyboard a controller types with). Every game screen
and the HUD are not part of it: they are vanilla's, because parity is the point of the game, and
Horizon's own settings are pages built from vanilla's widgets, the way mods add theirs.
The tokens live in one place, `crates/horizon-theme`. The launcher (`launcher/src/theme.rs`)
and the game (`crates/horizon-client/src/ui_theme.rs`) read them as Rust constants, and the
@@ -133,22 +134,49 @@ Geist (400, 500, 600) and Geist Mono (400), bundled under the SIL Open Font Lice
## Surfaces
- **Launcher** (`launcher/`): top bar; Play is a page header (version as the title, its notes'
first line under it), the client/server segmented control, the version picker and Play, then
an index list of Resources, Minecraft folder (and the server rows). Versions and Patch notes
are index lists with the release name as the title; Settings is an index list of switches and
values. The opening is the faint wordmark drawn letter by letter, then the interface arrives.
The sunset photograph is gone: the window is the page colour, light or dark with the system.
- **Website** (`website/`): the same page structure as before (what it is, screenshots,
parity, launcher, patch notes, community), each section a `micro` mono label, a `display`
heading and a short paragraph, its content an index list. Screenshots stay as images (radius
12, no frame). Light and dark follow the system, with a toggle. A giant faint wordmark sits
above the footer. No hero photograph: the first screen is the headline, one paragraph, the
download button and the parity score as an index row.
- **Game menus** (Horizon style): the title backdrop under a page-colour veil; text sidebar;
index lists for worlds and servers; options pages as index lists of rows (label left, value
in mono, the control right). The pause menu is a centred column of plain rows over a darker
veil.
- **Launcher** (`launcher/`): drawn in the Blocks look below. A top bar (wordmark, the pages as
tabs, the account chip, Settings), a sidebar (the instances, the hosted servers, the launcher's
own version and channel at its foot), and the page over a stone texture. Home opens on a pixel
landscape banner with the hero, the version picker and Play; Mods holds the resource pack,
shader pack and modpack tabs; Versions and Patch notes are lists of panels; Settings is
grouped panels of rows. Dark by default, Light or System in Settings (Appearance).
- **Website** (`website/`): the Blocks look below. The same page structure as before (what it
is, screenshots, parity, launcher, patch notes, community), headings in Pixelify Sans, lists as
stacks of panels, the stone texture behind the page and Horizon's pixel landscape (a dawn or a
sunset) behind the hero. Light and dark follow the system, with a toggle. A giant wordmark in
pixels sits in the footer.
- **Game**: vanilla's screens. The on-screen keyboard is a rounded plate of keys in the page
colour, the focused key in the accent.
## Blocks
A blocky, Minecraft-like look in Horizon's purple, for the website and the redesigned launcher:
Minecraft's inventory rather than a document. Its colours are `horizon_theme::Blocks`
(`BLOCKS_LIGHT`, `BLOCKS_DARK`), which `tokens.css` carries under the same names as before plus
`--panel`, `--raised`, `--button`, `--well`, `--bevel`, `--lip`, `--outline` and the `--face`
of the main action. The game's menus keep `LIGHT` and `DARK`.
- **Pixel type for what names and what you act on.** Headings, navigation, buttons and the
wordmark use Pixelify Sans (OFL; Medium, SemiBold, Bold); paragraphs and numbers stay in Geist
and Geist Mono so long text reads easily.
- **Blocks, not rounded cards.** Every surface is square: a 2 px dark outline, a 2 px light bevel
along the top and a darker lip along the bottom. The main action is the violet face with its own
bevel and a 4 px lip; it sinks a pixel when pressed. Code and fields are sunk wells.
- **Inventory tabs** switch the kinds in Mods: the open tab joins the panel under it.
- **Slots** hold pictures: a mod's or pack's own icon and gallery images from its source,
downloaded when first shown and kept on disk (`launcher/src/browser/images.rs`); the launcher
ships no third-party pictures. The Horizon instance shows a grass block drawn from the player's
own prepared Minecraft textures. Sources are named in text ("from Modrinth"): Modrinth's logo is
all rights reserved, so it is not shown.
- **Pixel art drawn in code.** The stone behind the pages is close shades of the page colour
(`TILE_SHADES`), never Minecraft's stone; the landscape is a banded sky, a sun cut in slices like
the mark, hills and square trees (a sunset in dark, a dawn in light). The launcher bakes them in
`launcher/src/art.rs` at the window's scale so each texel covers whole device pixels; the website
draws them in `website/scripts/art.mjs`.
- **Icons**: Pixelarticons (MIT), 24 unit pixel SVGs in `crates/horizon-theme/icons/pixel/`, tinted
with the text colour.
- **Contrast**: every text colour meets WCAG AA (4.5:1) on the panels, the page and the lightest
stone shade in both palettes (`blocks_text_meets_wcag_aa_in_both_appearances`).
## The mark
+5 -4
View File
@@ -19,11 +19,12 @@ again restores vanilla's behaviour completely.
| Game glue (input hooks, per-frame update) | `crates/horizon-client/src/game/extras.rs` |
| Mouse Tweaks-style controls, sort buttons | `crates/horizon-client/src/game/tweaks.rs` |
| Sort order and its clicks | `crates/horizon-client/src/inv_sort.rs` (pure, unit tested) |
| The settings page | `options_horizon.rs`: the **Extras** section of Horizon's Options |
| The settings page | `options_ui.rs` (`Page::Extras`): **Options → Horizon Settings... → Extras...** |
The settings are grouped by extra. On Horizon's page an extra's own settings
(its key, corner, size...) show under its switch while it is on (`Item::parent`);
Classic's Horizon Extras screen lists them all, two buttons to a row.
The settings are grouped by extra, under a header each, two buttons to a row as
vanilla's options lists are, and each says what it does in its tooltip. An
extra's own settings (its key, corner, size...) are greyed out while its switch
is off (`Item::parent`).
`game.rs` only gets one-line hooks (key, wheel, mouse, frame, HUD), so the
extras stay out of the way of other input and options work.
+7 -7
View File
@@ -2,17 +2,17 @@
## Settings
In the Horizon menu style, the Options screen's **Video** section holds the graphics settings, with a Simple / Advanced switch at the top (remembered between sessions):
Horizon's graphics settings are two screens built from vanilla's widgets, opened from the top of **Video Settings** (**Horizon Graphics...** and **Advanced Graphics...**, beside **Shader Packs...**, where Sodium and Iris put theirs) or from **Options → Horizon Settings...**:
- **Simple**: a preset (Performance, Balanced, Quality, Ultra or Custom), render distance, LOD distance, FOV, max framerate, VSync and GUI scale.
- **Advanced**: every setting, grouped under Rendering, Quality, Display, Preferences, Performance and Overlay.
- **Graphics** (Simple): a preset (Performance, Balanced, Quality, Ultra or Custom) and LOD distance.
- **Advanced Graphics**: every Horizon setting, grouped under Rendering, Quality, Display, Preferences, Performance and Overlay.
In the Classic style, Video Settings starts with two buttons opening the same settings as vanilla-looking screens.
Vanilla's own settings (render distance, FOV, framerate, VSync, GUI scale, smooth lighting...) stay where vanilla has them, in Video Settings; both screens leave them out.
Every row has a one-line description and its cost in frame time (none, low, medium, high, or saves time for culling that makes frames faster), and applies at once, except worker threads, which apply at the next start. A preset sets the quality settings together; changing one of them turns it into Custom. Display preferences (FOV, framerate, VSync, GUI scale, fullscreen, present mode, pacing) leave the preset as it is.
![Simple](media/settings-simple.png)
![Advanced](media/settings-advanced.png)
![Video Settings, with Horizon's buttons at the top](media/settings-simple.png)
![Advanced Graphics](media/settings-advanced.png)
| Group | Setting | Stored in |
| --- | --- | --- |
@@ -29,7 +29,7 @@ Every row has a one-line description and its cost in frame time (none, low, medi
**Battery mode** (Performance, off by default) is for laptops and handhelds: at most 60 frames per second in a world, 30 in menus without a world or while another window has focus, and half the automatic worker threads (chunks load slower). It changes only when frames are drawn: what they show and the game's 20 ticks per second stay as they are.
Which settings each level shows, their descriptions and costs are in `crates/horizon-client/src/graphics_ui.rs` (`rows`); the Horizon shell draws them in `options_horizon.rs` with `ui_theme::described_row`, and the Classic screens use `graphics_style.rs`.
Which settings each screen shows, their descriptions and costs are in `crates/horizon-client/src/graphics_ui.rs` (`rows`); `graphics_style.rs` draws them.
## Distant terrain
+140
View File
@@ -0,0 +1,140 @@
<!-- 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, shader-packs, 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 |
+3 -1
View File
@@ -240,7 +240,9 @@ If the new game crashes or doesn't come up in time, the server goes back to the
and puts the world back as it was just before the switch (the world the new game left is kept in
`backups/`). `horizon-server rollback` goes back to the release before by hand, keeping the world as it is
(it backs it up first). `--version vX.Y.Z` installs a given release, and `--archive FILE --version NAME` an
archive you have, such as your own build. A stopped server is switched and starts on the new release next
archive you have, such as your own build. A server still on a release from before the last dated one doesn't know
that 0.2 comes after the dated releases and says it is up to date: run `horizon-server update --version v0.2.0`
once ([versioning](versioning.md)). A stopped server is switched and starts on the new release next
time. Set `HORIZON_NO_UPDATE_CHECK=1` in the server's environment to turn the check off.
Coming: `console` (attach to a server running in the background), `ban` and `pardon` as their own
+468
View File
@@ -0,0 +1,468 @@
# Launcher commands
<!-- Generated from launcher/src/cli.rs by cli_tools::markdown(); a test fails when this file is out of date. Update it with: HORIZON_WRITE_DOCS=1 cargo test --manifest-path launcher/Cargo.toml the_launcher_reference -->
Every command of `horizon-launcher`, and the tool `horizon-launcher mcp` offers for it. A tool's arguments are the command's, in snake_case. A tool runs the command with `--json` and returns what it printed. The tools that change the player's things for good need `confirm: true`. The tools that send something or reach other people say "only when the player asks". The game's own tools, `game_*`, are in [horizon-ctl-commands.md](horizon-ctl-commands.md). With No AI on, `mcp` and `agent-config` are hidden and refuse; every other command stays. See [agent-control.md](agent-control.md#no-ai).
## `horizon-launcher versions`
List Horizon releases, or the installed versions.
horizon-launcher versions
- `--installed`: Only the versions installed here (no network)
MCP: `versions`.
## `horizon-launcher install`
Download and install a release (a tag such as v2026.10.13, or "latest").
horizon-launcher install <TAG>
- `TAG`
MCP: `install`.
## `horizon-launcher remove`
Remove an installed version.
horizon-launcher remove <TAG>
- `TAG`
MCP: `remove`, needs `confirm: true`.
## `horizon-launcher prepare`
Prepare a version's resources from your own Minecraft install.
horizon-launcher prepare
- `--minecraft`: The game folder of the official launcher, Prism Launcher, MultiMC, the Modrinth App, ATLauncher or GDLauncher (default: the launcher's, then every launcher's default)
MCP: `prepare`.
## `horizon-launcher play`
Start the client.
horizon-launcher play
- `--world`: Open or create this world (a folder under saves) at once
- `--creative`: Creative mode for a new world
- `--join`: Join a friend's world with its invite code
- `--arg`: An extra argument for the game, passed through as-is (repeatable), for example --server-thread
MCP: `play`, then the `game_*` tools.
## `horizon-launcher server`
Run a dedicated server here; type commands into its console.
horizon-launcher server
- `--dir`: The server's folder (default: the one the launcher uses)
- `--accept-eula`: Agree to the Minecraft EULA (https://aka.ms/MinecraftEULA)
MCP: `server`, `server_command`, `server_log`, `server_stop`.
## `horizon-launcher notes`
Show a release's patch notes (default: the newest).
horizon-launcher notes [TAG]
- `TAG`
MCP: `notes`.
## `horizon-launcher links`
Show the Discord, sponsor and website links.
horizon-launcher links
MCP: `links`.
## `horizon-launcher account list`
The signed-in accounts and which one plays.
horizon-launcher account list
MCP: `account_list`.
## `horizon-launcher account sign-in`
Sign in with a Microsoft account in your browser (device code).
horizon-launcher account sign-in
MCP: `account_sign_in`.
## `horizon-launcher account sign-out`
Sign out: the account's tokens leave the keychain.
horizon-launcher account sign-out <WHO>
- `WHO`: Its name or UUID
MCP: `account_sign_out`, needs `confirm: true`.
## `horizon-launcher account select`
Play as this account.
horizon-launcher account select <WHO>
- `WHO`
MCP: `account_select`.
## `horizon-launcher account offline`
Play offline, without an account.
horizon-launcher account offline
MCP: `account_offline`.
## `horizon-launcher settings`
Show the launcher's settings, or set one (the Settings page): selected-version TAG, minecraft-dir PATH, server-dir PATH ("default" resets a folder), install-new-versions on|off, opening-animation on|off.
horizon-launcher settings [KEY] [VALUE]
- `KEY` (selected-version, minecraft-dir, server-dir, install-new-versions, opening-animation)
- `VALUE`: The new value (with KEY)
MCP: `settings`.
## `horizon-launcher game-args`
Show or set the extra arguments the game starts with (for example --server-thread); quotes group a word with spaces in it.
horizon-launcher game-args [ARGS]
- `ARGS`: Omit to show the current arguments
MCP: `game_args`.
## `horizon-launcher logs`
Print the end of the game's log (logs/latest.log in the game folder), or its newest crash report.
horizon-launcher logs
- `--lines`: How many lines of latest.log
- `--crash`: The newest crash report instead
MCP: `logs`.
## `horizon-launcher update`
Look for a newer Horizon release and launcher, and install them.
horizon-launcher update
- `--check`: Only report what is available
MCP: `update`.
## `horizon-launcher desktop-entry`
Linux: put Horizon in the applications menu (an entry and the icon, under $XDG_DATA_HOME), or take it out with --remove.
horizon-launcher desktop-entry
- `--remove`: Remove the entry and the icon, and stop adding them back
MCP: `desktop_entry`.
## `horizon-launcher data status`
What is allowed, the install ID and how many items wait (the default).
horizon-launcher data status
MCP: `data_status`.
## `horizon-launcher data allow`
Turn kinds on: performance, crashes, bugs, benchmarks, or all.
horizon-launcher data allow <KINDS>...
- `KINDS`
MCP: `data_allow`, only when the player asks.
## `horizon-launcher data deny`
Turn kinds off: performance, crashes, bugs, benchmarks, or all.
horizon-launcher data deny <KINDS>...
- `KINDS`
MCP: `data_deny`.
## `horizon-launcher data show`
Print exactly what would be sent.
horizon-launcher data show
MCP: `data_show`.
## `horizon-launcher data delete`
Delete everything sent from here, and what waits, and take a new install ID.
horizon-launcher data delete
MCP: `data_delete`, needs `confirm: true`.
## `horizon-launcher data send`
Send what is waiting now.
horizon-launcher data send
MCP: `data_send`, only when the player asks.
## `horizon-launcher data bug`
Send a bug report you write; it is printed first, as it would leave.
horizon-launcher data bug <TEXT>
- `TEXT`
- `--log`: Add the end of the game's log (scrubbed, without chat)
- `--yes`: Send without asking
MCP: `data_bug`, only when the player asks.
## `horizon-launcher data benchmark`
Upload a benchmark report (docs/benchmark-report.md); it is printed first.
horizon-launcher data benchmark <FILE>
- `FILE`
- `--yes`
MCP: `data_benchmark`, only when the player asks.
## `horizon-launcher modpack list`
The imported packs and their coverage (the default).
horizon-launcher modpack list
MCP: `modpack_list`.
## `horizon-launcher modpack import`
Import a .mrpack, a CurseForge zip or an instance folder, and write its coverage report.
horizon-launcher modpack import <PATH>
- `PATH`
MCP: `modpack_import`.
## `horizon-launcher modpack port`
Get the jars of what this computer can port and carry them over.
horizon-launcher modpack port <PACK>
- `PACK`: The pack's folder name, as list shows it
- `--from`: A folder with your own jars (an installed instance, a downloads folder)
MCP: `modpack_port`.
## `horizon-launcher modpack play`
Play a ported pack as its own profile.
horizon-launcher modpack play <PACK>
- `PACK`
MCP: `modpack_play`.
## `horizon-launcher modpack remove`
Remove an imported pack: its jars, ports and the profile's saves.
horizon-launcher modpack remove <PACK>
- `PACK`
MCP: `modpack_remove`, needs `confirm: true`.
## `horizon-launcher mods list`
What the browser installed (the default).
horizon-launcher mods list
MCP: `mods_list`.
## `horizon-launcher mods search`
Search for packs Horizon loads.
horizon-launcher mods search [TEXT]...
- `TEXT`
- `--kind` (mod, resource, shader, modpack)
- `--everything`: Also what was made for other versions or runs only partly, each marked
- `--source` (modrinth, curseforge)
MCP: `mods_search`.
## `horizon-launcher mods check`
Say how well a Java mod runs in Horizon: its jar is downloaded (checksum checked), carried over and read; the answer is kept.
horizon-launcher mods check <PROJECT>
- `PROJECT`
- `--everything`: Allow a version made for another Minecraft version (1.21 and later)
- `--source` (modrinth, curseforge)
MCP: `mods_check`.
## `horizon-launcher mods install`
Install a pack and what it needs, by its id or slug (checksums checked); a Java mod is ported into horizon-mods and turned on; a modpack is imported.
horizon-launcher mods install <PROJECT>
- `PROJECT`
- `--everything`: Allow a version made for another Minecraft version
- `--source` (modrinth, curseforge)
MCP: `mods_install`.
## `horizon-launcher mods update`
Update what the browser installed (or one pack).
horizon-launcher mods update [PROJECT]
- `PROJECT`
- `--check`: Only say what is newer
MCP: `mods_update`.
## `horizon-launcher mods remove`
Remove a pack the browser installed.
horizon-launcher mods remove <PROJECT>
- `PROJECT`
MCP: `mods_remove`, needs `confirm: true`.
## `horizon-launcher servers list`
The servers, their folder and whether they run.
horizon-launcher servers list
MCP: `servers_list`.
## `horizon-launcher servers create`
Create a server; with no options it is a new world, survival, normal, 10 players, friends only.
horizon-launcher servers create
- `--name`
- `--seed`: The new world's seed (default: random)
- `--copy-world`: Start from a copy of this world folder (one of your saves)
- `--mode` (survival, creative, adventure, spectator)
- `--difficulty` (peaceful, easy, normal, hard)
- `--max-players`
- `--open`: Let anyone in (no whitelist)
- `--check-accounts`: Check players' Minecraft accounts (they must sign in with Microsoft)
- `--player`: Who may join (repeatable); the first becomes an operator
- `--accept-eula`: Agree to the Minecraft EULA (https://aka.ms/MinecraftEULA)
MCP: `servers_create`, only when the player asks.
## `horizon-launcher servers set-up`
Copy an installed, prepared version's programs and game files for the servers (again).
horizon-launcher servers set-up
MCP: `servers_set_up`.
## `horizon-launcher servers run`
Run a horizon-server command on a server, for example: servers run "My server" -- status.
horizon-launcher servers run <SERVER> -- <ARGS>...
- `SERVER`: The server's name or folder
- `ARGS`
MCP: `servers_run`.
## `horizon-launcher servers forget`
Take a server off the list (its folder stays).
horizon-launcher servers forget <SERVER>
- `SERVER`
MCP: `servers_forget`, needs `confirm: true`.
## `horizon-launcher mcp`
Serve the Model Context Protocol on stdin and stdout, for AI agents (refused while No AI is on).
horizon-launcher mcp
MCP: none: this command is the MCP server.
## `horizon-launcher agent-config`
How to connect an AI agent (Claude Code, Codex, Cursor, any MCP client) to `mcp`: the config to paste and the command that adds it (refused while No AI is on).
horizon-launcher agent-config
- `--client` (claude-code, codex, cursor, generic): Only this client
- `--test`: Start the MCP server as a client would and say whether it answered
MCP: none: it prints how to connect a client to `mcp`.
## `horizon-launcher no-ai`
Show or set No AI: on hides and turns off every AI feature (the companion, agent control, horizon-ctl and both MCP servers); off, the default, makes them available.
horizon-launcher no-ai [STATE]
- `STATE` (on, off): Omit to show the current state
MCP: none: the player's switch.
## `horizon-launcher benchmark`
Measure the launcher: starts (the first is the cold one), page switching, idle CPU and memory, the release list fetch; writes a benchmark report to benchmarks/ in its data folder.
horizon-launcher benchmark
- `--repeats`: How many times to start it
MCP: `benchmark`.
Binary file not shown.

Before

Width:  |  Height:  |  Size: 95 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 276 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 148 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 569 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 194 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 376 KiB

Binary file not shown.
Binary file not shown.

Before

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 191 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.0 MiB

After

Width:  |  Height:  |  Size: 289 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 569 KiB

After

Width:  |  Height:  |  Size: 218 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 76 KiB

+108 -30
View File
@@ -1,25 +1,69 @@
# The launcher's mod browser
Search Modrinth (and CurseForge, once the launcher has a key) for packs Horizon loads, see how well each one runs,
and install it with its checksum checked. This is item 16 of the roadmap and issue #577. The code is in
Search Modrinth (CurseForge support is coming soon) for Java mods, modpacks, resource packs and shader
packs, see how well each one runs before installing it, and install it with its checksum checked. This is item 16 of the roadmap and issue #577. The code is in
`launcher/src/browser.rs` and `launcher/src/browser/`.
## What it offers
Only what Horizon actually loads is offered. Java mod jars (Fabric, NeoForge, Forge) don't run in Horizon
([mods.md](mods.md), [research/java-mod-compat.md](research/java-mod-compat.md)), so they are never searched.
Horizon `.hmod` mods aren't on Modrinth or CurseForge yet (Modrinth has no `horizon` loader).
Horizon doesn't run Java code ([research/java-mod-compat.md](research/java-mod-compat.md)). It ports what a Java mod
carries as data (blocks, items, recipes, loot tables, tags, worldgen, textures, names) with `horizon-port-pack`, and
says before install which of the mod's features that leaves out. Horizon `.hmod` mods aren't on Modrinth or CurseForge
yet (Modrinth has no `horizon` loader).
| Kind | Goes to | How well it runs |
|---|---|---|
| Java mods (Fabric, NeoForge, Forge, Quilt) | ported into `horizon-mods/<mod id>/` and turned on | Checked from its jar before install: **Works**, **Partly** or **Doesn't run** ([below](#java-mods)) |
| Resource packs | `resourcepacks/` beside `options.txt` | **Works** when made for 26.3 ([resource-packs.md](resource-packs.md) lists what Horizon reads). Older packs are **Partly**: they load with vanilla's compatibility warning |
| Shader packs (Iris, OptiFine) | `shaderpacks/` | **Partly**: translated to WGSL, the full-screen passes draw and the world and shadow passes don't yet ([shader-packs.md](shader-packs.md)). Packs for other loaders (Canvas, core-shader packs) **don't run** and can't be installed |
| Modpacks (`.mrpack`, CurseForge zip) | the Modpacks page's import | **Partly**: Horizon runs the mods it can port, from the player's own downloads ([modpacks.md](modpacks.md)) |
By default a search shows only what runs: resource packs made for 26.3, shader packs for Iris or OptiFine, and every
modpack. **Show everything** lists the rest of the kind too, each marked with how well it runs; what doesn't run is
By default a search shows only what runs: Java mods made for 26.3, resource packs made for 26.3, shader packs for Iris
or OptiFine, and every modpack. **Show everything** lists the rest of the kind too, each marked with how well it runs; what doesn't run is
never offered for install.
## Java mods
Before a mod is offered for install, the launcher reads its jar. For each result it picks the version it would
install (the newest for 26.3; with **Show everything**, else the newest for 1.21 or later, the versions port-pack
upgrades from), downloads that file with the checks below, and runs `horizon-port-pack check` on it
([modpacks.md](modpacks.md#the-pipeline-horizon-port-pack)): the jar is carried over into a folder content mod and its
class files are read, not run, for what the carry can't take. Two checks run at once; the row says **Checking** until
its answer comes.
- **Works**: content only. Its blocks, items, recipes, loot, tags and worldgen port, and its code only registers
them. Blocks take the closest vanilla block's shape, hardness and sounds (a block's numbers live in Java code; the
NeoForge oracle that reads them for modpacks is a developer tool).
- **Partly**: the content ports; the row lists what doesn't: blocks with no vanilla block to copy, recipes of the
mod's own types, block entities (machines, containers), menus, mobs and entities, blocks and items with behaviour
of their own, worldgen written in Java, Mixins, the game events it reacts to.
- **Doesn't run**: nothing to port (performance mods, libraries, everything in code), a jar made for 1.20 or older,
or a mod id with characters Horizon mods can't use (`fabric-api`). Never offered for install.
The answer is kept in `mod-browser/checks-1/<checksum>/` under the game folder, with the carry when something
ports; the jar itself isn't kept. A file is checked once. On ten 26.3 jars a check took 0.2 to 3 s (24 s for an
18 MB jar with 9,360 recipes).
**Install** copies the carry into `horizon-mods/<mod id>/`, turns it on in `horizon-mods.txt` (the game's Options >
Mods lists it) and records it in `mod-browser.json` with its verdict and what didn't port, which the Installed list
shows. Its required mods that port are installed with it; one with nothing to port (a library such as Cloth Config
or GeckoLib) is listed as not ported. A mod that shares its id or a namespace with an installed one is refused. The
game reads mod content when it starts: start it again after installing. **Remove** deletes the folder and turns it
off.
### End-to-end check
`tools/mod_browser_harness.py [--mod SLUG] [--query TEXT] [--keep]` runs the whole path a player takes, in a scratch
game folder: the launcher's `mods search --kind mod`, `mods check` and `mods install` (Modrinth), then the game
opens a survival world with the mod offscreen (horizon-ctl), places one of its blocks, and crafts one of its recipes
from vanilla ingredients on a crafting table and takes the result. It times the world's load with and without the
mod and prints a JSON summary; it exits 1 when a step fails. It needs the launcher, the game and horizon-ctl built
and the prepared 26.3 resources in `.local`.
On the Mac mini (M4 Pro, offscreen) with Macaw's Fences and Walls (the default): check 4.0 s, install 3.1 s, world
load 5.4 s without mods and 7.3 s with it (resources 1.1 s and 2.6 s: the mod content folder is built on the first
start); the hedge places and its recipe crafts 4.
## Checks on every download
- The file must come from Modrinth's or CurseForge's file servers (`cdn.modrinth.com`, `edge.forgecdn.net`,
@@ -32,13 +76,49 @@ never offered for install.
## The Mods page
The launcher's **Mods** page has the three kinds as tabs, a search field (Enter searches), **Show everything** and,
once CurseForge is set up, a Modrinth / CurseForge switch. Each result is an index row: its summary, author,
The launcher's **Mods** page has the four kinds as tabs (Mods, Modpacks, Resource packs, Shader packs), a search field (Enter searches), **Show everything** and
the source: Modrinth, with **CurseForge (coming soon)** beside it, disabled. Each result is an index row: its summary, author,
downloads, source and licence, how well it runs (and why), **Page** (the project's page on its source) and
**Install** (**Import** for a modpack). Installed packs are listed above the results with their version, source,
**Install** (**Import** for a modpack). The Modpacks tab lists the imported packs first, with their coverage
report, **Port** and **Play** ([modpacks.md](modpacks.md)). Installed packs are listed above the results with their version, source,
file and the checksum they were checked against, with **Update to …** when a newer version runs and **Remove**
(asked twice).
### Project pages, filters and icons
A result's title opens its page inside the launcher, not in a web browser: its icon, authors, downloads, followers,
last update, licence and source, how well it runs (for a Java mod, what ports and what doesn't, from its check) with
**Install** or **Import**, the project's links (its page on the source, source code, issues, wiki, Discord,
donations; `https://` only, opened in the system browser), then three tabs: **Description** (the project's Markdown,
drawn by the launcher's renderer), **Gallery** and **Versions** (each version's date, loaders, game versions, file
and size, and the verdict of any version already checked). The data is `browser::details` (`Source::details`; on
Modrinth `GET /project/{id}` and `/project/{id}/members`, then `/project/{id}/version`).
**Filters** sit above the results: the order (best match, relevance, downloads, follows, newest, updated) and, under
**Filters**, the loader, game version, environment (client, server) and categories, with the values the source lists
for the kind (Modrinth's `/tag/category`, `/tag/loader`, `/tag/game_version`, asked once per run). A loader or version
picked replaces the default (Java mod loaders and 26.3 for mods); a version other than 26.3 checks and installs the
newest file for 1.21 or later, as **Show everything** does. Changing tabs clears the filters. CurseForge support
is coming soon; its source already maps the order and the game version.
**Icons and gallery images** are the projects' own, fetched at run time from the source's image server
(`browser::images`): HTTPS from `cdn.modrinth.com` (or CurseForge's `media.forgecdn.net` / `edge.forgecdn.net`) only,
at most 8 MB each, decoded (PNG, JPEG, WebP, GIF, at most 8192 pixels a side), scaled (icons 128 px, gallery 960 px)
and kept as PNGs in `mod-browser/images/` under the game folder, which is kept under 128 MB by dropping the oldest
files. A plate with the project's initial stands in until the icon arrives. Nothing of a project's art is in the
launcher or the repository.
**Vanilla Minecraft** is marked with a grass block drawn at run time from the player's own prepared game files
(`assets/minecraft/textures/block/grass_block_*.png`, tinted with the plains grass colour): the game-version filter
shows it. No Mojang file or logo is in the launcher or the repository.
**Source logos.** Modrinth's logo is not shown: Modrinth's own repository says its branding is all rights reserved and
"the use of Modrinth branding elements, including but not limited to the wrench-in-labyrinth logo, ... is strictly
prohibited without explicit written permission from Rinth, Inc." (`packages/assets/COPYING.md` in
[modrinth/code](https://github.com/modrinth/code/blob/main/packages/assets/COPYING.md)), and its
[terms](https://modrinth.com/legal/terms) ask for prior written permission to use its marks. Results name their source
in text ("from Modrinth") until Rinth, Inc. agrees. CurseForge support, and so its logo, is coming soon.
## Installing, updating, removing
`mod-browser.json` beside `options.txt` lists every file the browser installed: its source, project, version, file
@@ -51,14 +131,20 @@ same name the player put there is never overwritten.
Packs, as in vanilla and Iris.
- **Update** installs the newer version and removes the old file.
- **Remove** deletes the file and its entry. Packs installed as dependencies stay.
- **A modpack** is downloaded (checked the same way) into `ports/downloads/` and imported on the Modpacks page,
which says what of it Horizon runs and ports it.
- **A modpack** is downloaded (checked the same way) into `ports/downloads/`, imported, and ported straight away
for the selected version when it is prepared (`modpacks::import_and_port`): the jars of the mods Horizon can carry
over come from the pack's links or Modrinth, and the message says how many of its files play. **Play** on the
Modpacks tab starts it with every ported mod on together. A ported mod that owns a namespace an earlier one owns
(the game would refuse it) is left off before the game starts and listed under the pack ("Left off: ..."); the
coverage list says why each mod that didn't port didn't. A port that fails leaves the pack imported, with **Port**
to try again. Measured on three packs in [modpacks.md](modpacks.md#three-packs-through-the-mod-browser-measured).
From a terminal (or an agent):
```sh
horizon-launcher mods search faithful # --kind resource|shader|modpack, --everything, --source
horizon-launcher mods install faithful-32x # id or slug; a modpack is imported
horizon-launcher mods search faithful # --kind mod|modpack|resource|shader, --everything, --source
horizon-launcher mods check macaws-fences-and-walls # a Java mod's verdict, what ports and what doesn't (--json)
horizon-launcher mods install faithful-32x # id or slug; a Java mod is ported, a modpack imported and ported
horizon-launcher mods list # --json
horizon-launcher mods update [faithful-32x] [--check]
horizon-launcher mods remove faithful-32x
@@ -69,21 +155,13 @@ horizon-launcher mods remove faithful-32x
**Modrinth.** The public API (`api.modrinth.com/v2`) needs no key. The launcher names itself in its user agent, as
Modrinth asks.
### CurseForge
### CurseForge (coming soon)
CurseForge's API (`api.curseforge.com/v1`) needs an API key from its developer console. Ludovic approved CurseForge
for the browser on 2026-10-21; the key is his (agents never sign up for him). Until a key exists the CurseForge source
is off and the browser searches Modrinth only.
CurseForge support is coming soon. Its API (`api.curseforge.com/v1`) needs a paid key, so for now the launcher
doesn't use it: the Mods page shows **CurseForge (coming soon)** beside the Modrinth switch, disabled, and no search
or install goes to CurseForge (`browser::sources()` is Modrinth only; `horizon-launcher mods ... --source curseforge`
says it is coming soon). The CurseForge source (`browser/curseforge.rs`) is kept for when it comes.
To turn it on:
1. Ludovic gets a key at <https://console.curseforge.com/> (sign in, API keys). CurseForge's terms for a launcher
that ships the key apply: the key is built into the binary, so anyone with the binary can read it.
2. He stores it in the 1Password **Agents** vault as an item `CurseForge API`, field `credential`.
3. It goes into the repository secret `HORIZON_CURSEFORGE_API_KEY`
(`~/fleet/op read "op://Agents/CurseForge API/credential" | gh secret set HORIZON_CURSEFORGE_API_KEY`).
The launcher workflow passes it to the build, which builds it in (`option_env!`).
At run time `HORIZON_CURSEFORGE_API_KEY` in the environment overrides the built-in key; empty means none. A file
whose author allows downloads from CurseForge's own site only (no `downloadUrl` in the API) is shown but can't be
installed.
A CurseForge modpack zip or instance the player already has still imports, since that needs no key: its jars come
from the player's installed instance or, when Modrinth has the same file, from Modrinth. A jar only CurseForge serves
is listed under the pack as "CurseForge downloads coming soon".
+49 -4
View File
@@ -240,6 +240,10 @@ How the game loads them, without touching vanilla's path:
when its Java original ships them so (`namespaces = ["kaisyn", "towns_and_towers"]` for Towns
and Towers, mod id `t_and_t`; docs/mods.md). No namespace has two owners: a mod whose id or
listed namespace another mod that is on already owns is left out, with both named in the log.
`horizon-port-pack` avoids that inside a pack: a namespace two carried mods both claim (YUNG's
structure mods all ship files under `yungsapi`, the namespace of YUNG's API, whose own jar isn't
carried) is left to none of them, and its files stay outside. The launcher applies the game's
rule before it starts a pack (`pipeline::loadable`) and lists what it left off.
- The overlay is built on the first start with a set of mods and kept for later starts. A stamp
(`horizon-mod-content.stamp`) hashes the game executable, the base tables and every mod file's
size and mtime. Adding, removing or editing a mod, or a new build of Horizon, rebuilds it. For
@@ -302,12 +306,28 @@ cargo run -p horizon-port-pack -- report ~/.horizon/ports/pack # coverage
cargo run -p horizon-port-pack -- port ~/Downloads/pack.zip ~/.horizon/ports/pack [--from <folder>] [--resources <root>]
```
`check <jar> <out>` takes one mod jar on its own, as the launcher's mod browser installs it
([mod-browser.md](mod-browser.md)): it carries the jar into `<out>/carry/` and reads its class
files (constant pool, superclass, declared methods; no decompiling) for what the carry can't
take, then writes the verdict to `<out>/check.json`. **Works**: content only, and the code just
registers it. **Partly**: the content ports, and the code features listed don't (block entities,
menus, entities, blocks and items with behaviour of their own, recipe types, Mixins, game events).
**Doesn't run**: nothing to port, or a jar made for 1.20 or older. Each mod class is followed up to
the first game class it extends; a block subclass that only overrides how it looks or is placed
(`getStateForPlacement`, `rotate`...) is registration. Game classes are read by Mojang's names
(26.1 and later, and NeoForge since 1.20.5); older Fabric jars name them in intermediary, so a
class extending one counts as code that can't be read. On ten 26.3 jars (2026-10-22): Macaw's
Fences, Windows and Furniture, Ecologics, Compressed Blocks, More Decorative Blocks and Moog's
Nether Structures are Partly; Sodium and GeckoLib don't run (Mixins, renderers, nothing to port);
Fabric API doesn't run (its id has a dash, which content mods can't use). A check takes 0.2 s to
3 s, and 24 s for Compressed Blocks (18 MB, 9,360 recipes, writing the carry dominates).
`fetch` gets each jar the player's way, never from us: copied from a folder they have (matched
by SHA-1, or through a CurseForge app instance's `minecraftinstance.json`), else downloaded from
the link the pack itself gives (a `.mrpack`'s, on the format's hosts only) or, for a CurseForge
pack, the same file on Modrinth's public CDN, found by its SHA-1. A jar is kept only when its
hash matches. A file only CurseForge has is listed as needing a CurseForge API key (Ludovic's
decision; open question below), with the player's installed instance as the way round it.
hash matches. A file only CurseForge has is listed as "CurseForge downloads coming soon" (its API
needs a paid key; Ludovic, 2026-10-22), with the player's installed instance as the way round it.
`<work>/fetch.json` says what happened to each file. On All the Mods 10 8.3's CurseForge zip
(2026-10-17): of the 54 data-tier content mods, 42 come from Modrinth's CDN (84 MB) and 12 need
the key or the instance; `port` then carries the 42 over (0 ported, 42 partial: the harness is a
@@ -1031,10 +1051,35 @@ What is missing, ranked by how much a player notices:
6. **Smaller gaps:** Mo' Structures' mixin that keeps lakes out of its structures and its two
block-ageing processors, and the 5 missing block models.
### Three packs through the mod browser, measured
2026-10-22, Mac mini M4 Pro (offscreen, a debug launcher, release-profile `horizon-port-pack` and game), while
other sessions kept the CPU at 85 to 93 %, so times are upper bounds. The two Modrinth packs were imported with
`horizon-launcher mods install <slug>` (the browser's Import), ATM10 from its CurseForge zip with `modpack import`
(CurseForge support is coming soon), then each ported with `--resources` for 26.3 and opened as a survival
world with every ported mod on (horizon-ctl `launch --dev-mod ...`, from a scratch script).
| Pack | Files | Import | Port | Ported mods | Coverage | Declared | World load (resources) | Crashes |
|---|---|---|---|---|---|---|---|---|
| Vanilla Perfected 26.3 (Fabric, small) | 108 | 30.4 s | 1.0 s | 2 | 2 partial, 79 not yet, 27 not needed | 0 blocks (a trail effect, a torch-flower texture) | 5.2 s (2.1 s) | none |
| Slimes Adventure 1.13.4 (Fabric 1.21.1, medium) | 105 | 18.8 s | 22.8 s | 20 | 20 partial, 46 not yet, 39 not needed | 8,208 blocks, 41 items, 1,376 recipes | 23.0 s (15.0 s) | none |
| All the Mods 10 8.3 (NeoForge 1.21.1, CurseForge zip) | 496 | 3.1 s | 29.4 s | 42 | 42 partial, 333 not yet, 121 not needed | 10,000 blocks, 1,273 items, 4,178 recipes | 38.3 s (28.7 s) | none |
The same world with no mods loads in 5.4 s (resources 1.1 s). Import is the pack download and Modrinth's answers by
file hash; Vanilla Perfected's 30 s is mostly its 108 lookups and its download. Port is the jars (downloaded for the
two Modrinth packs; ATM10's 42 copied from a folder, 12 more are on CurseForge only: CurseForge downloads coming soon) and the carry,
which writes tens of thousands of small files. World load grows with the blocks the pack declares: ATM10 adds
about 155,000 block states, and loading their models and textures is most of its 28.7 s.
Every world loaded and stayed up, with no panic and no error in the log. Before the namespace fix above, Slimes
Adventure lost three of YUNG's mods at start ("both use the namespace yungsapi"); after it all 20 load. As a share of
the mods that need porting (not counting performance mods and libraries), 2 of 81 ported partly, 20 of 66 and 42 of
375. Every ported mod is Partial: their Java code (block entities, entities, Mixins) doesn't come along.
## Open questions for Ludovic
- Contacting authors of permissively licensed mods to publish ports (none contacted).
- Whether players should run code-port agents themselves (their own Claude Code or Codex
login, as Zenith does) or only download published ports.
- A CurseForge API key for the launcher (CurseForge grants them to launchers on request). Until
then, CurseForge packs import from an installed instance.
- CurseForge: dropped for now (its API needs a paid key; Ludovic, 2026-10-22), shown as coming
soon. CurseForge packs import from their zip or an installed instance.
+1 -1
View File
@@ -110,7 +110,7 @@ loading. Ordered by what the first native ports need ([research](research/java-m
| `target` | the crosshair's block or entity, with its state and NBT summary | Jade/WTHIT-style tooltips |
| `inventory-read` | the player's inventory, held item, open container | AppleSkin, recipe viewers |
| `recipes` | the recipe registry and lookups | JEI/EMI-style viewers |
| `ui` | widgets: text, item icons, lists, a screen the mod owns, a settings page in Options > Mods | built on `ui_theme` so it matches the menus |
| `ui` | widgets: text, item icons, lists, a screen the mod owns, a settings page in Options > Mods | built from vanilla's widgets (`ui`) so it matches the menus |
| `world-read` | blocks and biomes around the player, within the render distance | minimaps, schematics |
| `render` | world-space lines, boxes and ghost blocks in a per-frame budget | Litematica-style placement, waypoints |
| `registries` | new blocks, items, entities and recipes, mostly data: JSON models, textures, loot and recipes in the `.hmod`'s `assets/` and `data/` | server side; see [Multiplayer](#multiplayer) |
+2 -2
View File
@@ -119,7 +119,7 @@ game accepts, test hooks included.
`place X Y Z [--item ITEM]`, `interact X Y Z` (doors, chests, crafting
tables), `use-item [--hold S]` (eat, drink, throw), `select SLOT|ITEM`, `drop`.
- **Widgets:** `ui` lists every widget of the open screen (title menus, pause,
options pages in both menu styles, inventories and menus): an id, its kind
options pages, inventories and menus): an id, its kind
(`button`, `slider` with its 0..1 `value`, `field`, `row`, `tab` with
`selected`, `slot` with its stack), the label and its bounds. Ids come from
labels (`FOV: 70` is `fov`, `Video Settings...` is `video-settings`, a
@@ -144,7 +144,7 @@ game accepts, test hooks included.
- **Screens:** `open-inventory`, `click-slot SLOT [right] [shift]` (0-8 hotbar,
9-35 inventory, 100+ crafting grid, 200 result, 300+ containers, 500-503
armor, 504 offhand, 600+ stations), `close`, `click-button LABEL` (any
button of any screen or title menu, classic or Horizon style, by its label),
button of any screen or title menu, by its label),
`click-at X Y`, `type TEXT` (on the create-world screen `--field name|seed
--replace`), `chat`, `command`, `respawn`, `pause`, `resume`.
- **World:** `tp`, `give`, `time`, `setblock`, `summon`, `wait TICKS`, and the
+6 -3
View File
@@ -1,7 +1,8 @@
# Play with friends
A player opens their single-player world to friends with one click and gets an **invite code**.
Friends paste the code (on the multiplayer screen in game, or on the launcher's Play page) and join.
Friends paste the code (in game: the title screen's Friends button opens Join a Friend, and Direct
Connection takes a full code too; or on the launcher's Play page) and join.
There is no Horizon server in the middle and no account: the code itself says where the host is and
holds the key that encrypts the game between them.
@@ -22,7 +23,8 @@ bytes vanilla's protocol would send, between a loopback port on each side.
## How it works
**Hosting.** "Invite friends" (in Horizon's pause menu) opens the world to LAN if it isn't (Open to
**Hosting.** The pause menu's Friends button (vanilla's icon, beside Player Reporting) opens **Play
with Friends** (`friends_screen.rs`); its **Start Sharing** opens the world to LAN if it isn't (Open to
LAN's defaults), then the host's game, on its own:
1. listens on its **direct port**, TCP 25580 by default (the same port every time, so a port forwarded
@@ -59,7 +61,8 @@ port closes, the router mapping is deleted). Sharing again makes a new secret.
## When friends can't reach the host
The host's panel says what to expect, from what the game found:
Play with Friends says what to expect, from what the game found; when friends on the internet can't
reach the host, its **Troubleshooting...** button (beside Done) opens this section in the browser:
| What the game found | What the host reads |
| --- | --- |
+41 -66
View File
@@ -2,9 +2,8 @@
How a change gets from a pull request to players: the checks a pull request passes, how it merges, and the
automatic releases that follow. Releases are automatic and frequent so the latest Horizon is always playable.
Each one goes out as an **alpha** build, which launchers on the **Alpha** channel install at once, and becomes **stable** in
the next daily promotion unless something holds it back ([Channels](#channels)): launchers and servers install
stable builds unless their owner picks Alpha.
There is one channel ([One channel](#one-channel)): each release is published as the release and GitHub's *latest*
once its smoke test passed and no `release-blocker` is open, and launchers and servers install it at once.
## Pull request checks
@@ -101,12 +100,11 @@ flowchart LR
windows["Windows x64<br/>GitHub windows-latest"]
mac["macOS arm64<br/>Mac mini runner<br/>+ offscreen game run"]
end
build --> publish["publish vX.Y.Z as an alpha<br/>notes from the merged PRs"]
publish --> alpha(["launchers on Alpha install it"])
publish --> promote{"promote.yml, daily at 20:00 UTC:<br/>6 h old by then, smoke test, no release-blocker"}
promote --> stable["stable and latest<br/>notes since the last stable"]
stable --> launcher(["every launcher and server installs it"])
stable --> kira(["Kira posts it;<br/>pings only with ### New"])
build --> gate{"gate: the smoke test drew a world,<br/>no release-blocker is open"}
gate -- no --> nothing(["nothing is published"])
gate -- yes --> publish["publish vX.Y.Z as the release and latest<br/>notes from the merged PRs"]
publish --> launcher(["every launcher and server installs it"])
publish --> kira(["Kira posts it; the first release<br/>after 20:00 UTC pings, once a day"])
```
### When it releases
@@ -121,9 +119,10 @@ commits) since the last **published** game release:
- It releases when at least one pull request counts and the newest of them merged at least 5 minutes ago, so a wave
of merges becomes one release; if merges never pause, it releases once the oldest has waited 20 minutes. There is
no minimum time between releases: every settled player-facing change ships, limited only by the release already
building. That is the Alpha channel, many releases a day.
building: many releases a day.
- A pull request labelled `release-now` (a crash or a blocker) releases at once.
- A pull request labelled `skip-release` (work players don't see) doesn't count and isn't listed in the notes.
- An open issue labelled `release-blocker` holds every game release, forced ones too (`held by release-blocker #N`).
- One release at a time (concurrency group `game-release`); a run that finds nothing new does nothing.
- A scheduled or hand-started run releases main's newest commit whose `checks` passed; after `checks`, the commit
they passed on.
@@ -137,7 +136,7 @@ How releases are numbered, and how installs from before 0.2 reach it: [versionin
the patch after the newest release tagged on that line (`v0.2.0` first). A `feature` label doesn't change the line:
only that file does, by pull request.
- Without the file (every release before 0.2), `vYYYY.MM.DD`, then `.01`, `.02`… the same UTC day.
- Every reader (`release_train.py`, `release_channels.py`, the launcher, `horizon-server update`, the website) ranks
- Every reader (`release_train.py`, the launcher, `horizon-server update`, the website) ranks
every `vX.Y.Z` tag above every dated one.
### Labels
@@ -149,7 +148,7 @@ How releases are numbered, and how installs from before 0.2 reach it: [versionin
| `skip-release` | Doesn't trigger a release and isn't listed in the notes |
| `run-parity` | Runs the parity job once on a fork's pull request |
| `parity-regression` | Opened by the nightly audit for a harness that fails on main |
| `release-blocker` | On an issue: holds every beta back from stable while it is open ([Channels](#channels)) |
| `release-blocker` | On an issue: no game release is published while it is open ([One channel](#one-channel)) |
Pull requests without `feature` are listed under **Fixed**. Titles are written for players, since they become
the notes.
@@ -180,63 +179,38 @@ runs the game: GitHub's runners have neither a GPU worth the name nor the game f
- `### Known issues`: the bullets of [docs/known-issues.md](known-issues.md);
- thanks to outside contributors, how to install, the disclaimer.
Kira posts every release in Discord's #releases. An Alpha build (a game pre-release) is posted silently: no ping and
Discord's @silent flag, so nobody gets a notification. When the same release becomes Stable it is posted again, and
that post pings the releases role when the notes have a `### New` section (at most once every 6 hours). Launcher
releases post without a ping.
Kira posts every release once in Discord's #releases. It pings the releases role at most once a day: the first game
release published after 20:00 UTC, with a short list of what came out since its last ping. Every other post is
silent (no ping and Discord's @silent flag). Launcher releases post without a ping.
### Channels
### One channel
Every game release is published as an **alpha** build, a GitHub pre-release (the workflows, tools and labels
call it a *beta*: `release-blocker` holds every beta), so GitHub's *latest* release stays the last
**stable** one. The launcher's Settings has an **Updates** choice of two channels (`update_channel` in its
`settings.json`, `horizon-launcher update-channel`):
Since 2026-10-23 there is one channel. Every game release is published as the release, never a pre-release, and
marked GitHub's *latest*: the launcher, `horizon-server update` and `install.sh` take it at once. Because nothing
promotes it later, the checks that used to gate a promotion run in the release itself, and the publish job
(`tools/release_train.py gate`) publishes nothing unless both pass:
- **Stable**, the default: a tested build about once a day, the alpha builds promoted below.
- **Alpha**: every alpha build as soon as it is built, many times a day; it can break. "Alpha" is the project's
word for builds that are still being tested (the whole of Horizon is in beta); Stable is the tested ones. An open
launcher looks for releases every 30 minutes on Alpha (4 hours on Stable). Launchers from before 0.2 had a "Beta
builds" switch instead; on, it reads as Alpha.
- the release smoke test: the macOS build runs the game offscreen on the Mac mini and keeps its report,
`smoke-test.json`, only when the game drew a world. The gate reads the report again before publishing, and the
release carries it. A run whose macOS build went to GitHub (`MAC_RUNNER=macos-latest`) has no report, so it
publishes nothing;
- no open issue labelled `release-blocker`. `decide` checks first, so a blocked train builds nothing; the gate checks
again right before publishing, so an issue labelled while the builds ran still holds the release. Only the label
and the issue's state count, never its text: whoever opened the issue can edit the text after a maintainer
labels it. Close the issue (or remove the label) and the next run releases everything waiting, with notes
covering all of it.
`horizon-server update` installs stable builds (`--version <tag>` takes an alpha build by name). In Discord's #releases every
Alpha is posted silently and only Stable posts notify (above).
A failed gate fails the run; the next run (10 minutes later) decides again. Nothing older than the latest release is
ever published: tags only count up.
`.github/workflows/promote.yml` runs `tools/release_channels.py promote` once a day at 20:00 UTC (21:00 in Paris in
winter time, 22:00 in summer), with retries until 21:37 for a run GitHub starts late or skips. It promotes the newest
beta that
The launcher has no channel setting any more and looks for releases every 30 minutes. The game pre-releases of the
old Alpha channel (v0.2.1 on, published before this change) stay listed for anyone who wants one by hand, but no
launcher installs them as an update, and `release_train.py` ignores them: the first release of the single channel
lists everything since the last release that was not a pre-release (v0.2.0). Launchers from before this change keep
updating either way: with Alpha (or 0.17's "Beta builds") on they take every release, pre-release or not; with it
off, every release that is not a pre-release, which is now every new one.
- is newer than the stable release,
- had been out 6 hours at 20:00 UTC (published by 14:00 UTC that day; one published later waits for the next day),
so every run of the evening picks the same beta and stable moves once a day,
- passed its release smoke test: the macOS build attaches `smoke-test.json` (the offscreen game run's report) only
when the game drew a world on the Mac mini, so a release built while `MAC_RUNNER` sends macOS to GitHub waits
for a hand,
- and isn't covered by an issue labelled `release-blocker`. An open blocker holds every beta; closed as completed
it still holds the betas published before it closed (they have the bug); closed as not planned it holds
nothing. Only the label and the issue's state count, never its text: whoever opened the issue can edit the
text after a maintainer labels it, so it can't pick which betas go out.
Nothing older than the stable release is ever promoted, not even with `force`: GitHub's latest release is what
`horizon-server update` and `install.sh` download, so it only moves forward.
When the oldest beta newer than the stable release has waited 30 hours (it missed a daily promotion it was due for;
on a normal day a beta waits at most that long and is promoted), promote.yml opens an issue titled
"Promotion to stable has stalled" with the reason from the last check (a blocker left open, smoke tests not
running). It closes itself after the next promotion.
Promoting marks the beta stable and latest and rewrites its notes to list everything since the previous stable
release (`release_train.py notes --stable`), so players who skipped the betas see all of it. Older betas stay
betas. By hand, from a phone too (GitHub app: Actions, promote, Run workflow):
```sh
gh workflow run promote -f tag=v0.2.3 # that beta now: no wait for 20:00, still no blocker
gh workflow run promote -f tag=v0.2.3 -f force=true # even blocked or without a smoke test
gh workflow run promote -f dry_run=true # what would be promoted now
```
An alpha build's notes cover only what changed since the release before it (alpha or stable), and say it is an alpha build.
`release_train.py decide` counts pull requests from the newest release of either channel, so betas don't
release the same changes again.
`promote.yml` and `tools/release_channels.py` (the daily promotion at 20:00 UTC) are gone.
### Signed checksums
@@ -298,7 +272,8 @@ gh variable set RELEASES_PAUSED --body 1 # no automatic game or launcher rel
gh variable delete RELEASES_PAUSED # back on; the next hourly run catches up
```
While paused, runs still decide and say why in their summary; `force=true` still releases.
While paused, runs still decide and say why in their summary; `force=true` still releases, but never past an open
`release-blocker`.
### Rolling back
@@ -308,8 +283,8 @@ A bad release is withdrawn by turning it back into a draft:
gh release edit v0.2.3 --draft
```
A beta that is not promoted yet needs no rollback: label an issue about it `release-blocker`. For a stable
release: launchers list only published releases, so the previous version becomes the newest one again, launchers that
To stop the next releases while a problem is fixed, label an issue about it `release-blocker`. For the bad
release itself: launchers list only published releases, so the previous version becomes the newest one again, launchers that
didn't install the bad one won't, and players who did can pick the previous version in the launcher's version
list (`launcher/src/backend.rs` tests `withdrawn_release_is_never_offered`). The tag stays, so the next release
that day takes the next number, and its notes start from the last *published* release, so they list the
+10 -11
View File
@@ -38,7 +38,7 @@ and some are waiting for Ludovic:
| Private vulnerability reporting | **Live** (see the end of this page). |
| Signed checksums on releases | **Live** for new releases (#1011): the `release` environment holds the key, and its public half is in `release-keys.txt` (#1023). Releases from before then are unsigned. |
| Launchers and servers checking signatures | **Not yet**: #1014 waits as a draft until a signed stable game release and a signed launcher release exist. Until then they trust GitHub's checksum, as before. |
| Alpha, then stable | **Live** (#1012): every release is first an alpha build. The launcher's Updates setting picks Stable (the default) or Alpha (the pre-releases). |
| Smoke test and release-blocker before publishing | **Live**: since 2026-10-23 every release is the latest at once (one channel, Ludovic's decision), so it is published only after its smoke test passed and while no `release-blocker` is open. The 6-hour beta of the old Alpha, then stable flow (#1012) is gone. |
| Reports marked suspicious | **Partly**: the scan of Discord for agents does it. Kira's issues do it once its pull request merges. |
| Code owners' review of the pipeline | **Not yet**: `.github/CODEOWNERS` and its protection (#1015) wait for the App, below. Until then pipeline changes merge like any other once `verify` passes. |
| Agents on their own GitHub App | **Not yet**: prepared, waiting for Ludovic to create it. Agents still use his account. |
@@ -53,11 +53,10 @@ and some are waiting for Ludovic:
- **`verify` always runs.** Labels no longer start the checks, and the required `verify` job has no condition, so
the only `verify` a change can have is one that ran. Main requires it, from GitHub Actions only, for everyone,
admins included.
- **Alpha, then stable.** Every release is first an **alpha** build (a GitHub pre-release). It becomes **stable**, the version launchers and
servers install by themselves, in the daily promotion (20:00 UTC), only after it has been out 6 hours and passed its
smoke test (the game started and drew a world on the Mac mini), and only while no issue labelled `release-blocker`
is open. If a beta misses a promotion it was due for, an issue says so. Players who want the newest builds at once
pick **Alpha** under Updates in the launcher's Settings. Discord announces stable releases only.
- **Checked before it is published.** Every release is published as the latest, which launchers and servers
install by themselves, so the release run publishes it only after its smoke test passed (the game started and
drew a world on the Mac mini) and only while no issue labelled `release-blocker` is open; otherwise nothing is
published.
- **Signed updates.** Each release carries a list of its files' checksums, signed with Horizon's release key. The
launcher (for the game and for itself) and `horizon-server update` check that signature against the public key
built into them, then check the download against the list. Anything unsigned, signed with another key, signed
@@ -78,9 +77,8 @@ and some are waiting for Ludovic:
## What still needs Ludovic
- **Approving pipeline changes** (rare): a pull request touching a file in `.github/CODEOWNERS`.
- **Holding a release back or speeding one up**, from his phone if he likes. Label an issue `release-blocker` to
hold every beta until it is closed. Run the `promote` workflow (GitHub app: Actions,
promote, Run workflow) to make a beta stable at once.
- **Holding releases back or speeding one up**, from his phone if he likes. Label an issue `release-blocker` to
hold every release until it is closed; label a pull request `release-now` to release it as soon as it merges.
- **Creating the GitHub App**: one link, "Create GitHub App", then "Install". His login, his clicks.
- **Fork pull requests**: their checks run only after a maintainer approves them, and they run on the Mac mini only
after a maintainer has read them and added `run-parity`.
@@ -90,8 +88,9 @@ and some are waiting for Ludovic:
## What this doesn't solve
- **Code that merges is code that ships.** Signing proves a build came from Horizon's pipeline, not that the code
is good. Against a bad change, the safety nets are the checks and harnesses, review, the 6-hour beta and the
release-blocker label.
is good. Against a bad change, the safety nets are the checks and harnesses, review, the release smoke test and
the release-blocker label. Since the single channel there is no 6-hour beta: a change reaches every player
within minutes of merging.
- **Until agents switch to the App**, they still work with Ludovic's own account, so nothing technical tells his
actions from theirs. Code owners' reviews are switched on together with the App.
- **The Mac mini** builds the macOS release and also runs pull requests' parity checks: a pull request from this
+94
View File
@@ -0,0 +1,94 @@
# A server's levels: one per dimension
Vanilla's `MinecraftServer` holds a `ServerLevel` per dimension, and each player is in one of them.
Horizon's server does the same. That covers the dedicated server and single player's server thread
(`Game::serving`, the default since #1114). So a LAN world's host and each guest can be in different
dimensions at the same time.
## How the single-level `Game` maps onto vanilla's levels
The game's tick code reads one level: the one held in `Game`'s own fields (the world, its streaming
and save, block ticks, entities, block entities and their per-level queues). `game/levels.rs` keeps
the other dimensions' levels as `Parked` values and swaps one into place (`enter_level`). The swap is
`mem::swap` of each per-level field, so the tick code runs unchanged, one level at a time.
| Vanilla | Horizon |
| --- | --- |
| `MinecraftServer.levels` | the level in place plus `Levels::parked` |
| `MinecraftServer.tickChildren`, every level | `tick_server`: each level with a player in it, in Overworld, Nether, End order. The first pass reads the network and runs the shared parts (clock, weather, functions, autosave). |
| `ServerLevel.players` | `Hub::here`: the guests whose `dimension` is the level in place |
| `ServerPlayer.teleport` into another level | `server_travel.rs`: a Respawn packet, then the teleport once the destination has loaded (portals and `execute in … tp`). An End gateway teleports within the End. |
| `PlayerList.respawn` | `guest_respawn`: into the respawn point's level, the Overworld unless the player has an anchor or a `spawnpoint` elsewhere (`Guest::respawn_elsewhere`), resolved through its block once that level has loaded |
| `ServerLevel.noPlayersEmptyTime`, chunk unloading | `close_idle_levels`: a level other than the Overworld with nobody in it for 300 ticks is saved and closed |
| `CommandSourceStack.getLevel` | `with_source` puts the source's level in place for a command (`execute in`, `execute at` a player in another level) |
| the levels' shared `LevelData` | not swapped: game time, day time, weather, game rules, scoreboard, maps, entity ids (`next_entity`, unique across levels) |
The packets of a guest are read in its own level's pass (`Hub::tick_level`), so its actions and
commands run with its level in place.
The window's own game (single player's default, `--no-server-thread`, `HORIZON_SERVER_THREAD=0`, and the
command harness) keeps one level, which follows its player (`enter_dimension`). LAN guests of a world run
that way stay in the host's dimension. It is the default again only until the server thread reaches parity
(`--server-thread` or `HORIZON_SERVER_THREAD=1` opts in), so it gets no multi-level work.
## One code path for both
The dedicated server and the server thread are the same code. The server thread runs a `Game` with
`options.dedicated` set and a hub without a host player. The window joins it through memory as one
more player. Everything above serves both, and `server_dimension_players` (vanilla clients on Horizon's
dedicated server) and `lan_e2e --server-thread` (Horizon clients on the server thread) check it from
the two sides.
## Cost of an extra level
Measured on the Mac mini (M4 Pro) at render distance 12, on 2026-10-22. The host and a guest each
played a fresh world on the server thread. RSS is the host's whole process, window included. Tick time
is `/tick query`'s average over 100 ticks.
| Where the players are | Average tick | P95 | Host RSS |
| --- | --- | --- | --- |
| both in the Overworld | 1.0 ms | 1.3 ms | 1194 MB |
| guest in the Nether (two levels tick) | 2.2 ms | 2.9 ms | 1238 MB |
| guest in the End (the Nether still parked) | 0.9 ms | 1.1 ms | 1324 MB |
| both back, the Nether and End closed after 300 idle ticks | 0.8 ms | 0.9 ms | 1335 MB |
- A level costs only while a player is in it: its chunks around that player, their entities, and the
tick. With nobody outside the Overworld, `tick_server` runs one pass, as before.
- A closed level's memory goes back to the allocator, not always to the system.
- Entering a level the first time opens its region files and streaming (`open_level`). That cost
comes once, before the player's chunks load.
## Saving
`save_game` saves the level in place, then every parked level (`save_parked_levels`). Each level has
its own region folder, as in vanilla (`DIM-1`, `DIM1`). A level closed for being idle is saved first.
Each player's saved data holds its dimension (`Dimension`). A guest who leaves in
the Nether, or whose host saves and quits, joins again in the Nether where it was.
## What's checked
`python3 tools/lan_e2e.py --server-thread --check portals --check levels`:
- `portals`: the guest goes to the Nether through a portal while the host stays. The host then goes
to the End while the guest is in the Nether, so three levels run at once, and both come back.
- `levels`, with the host and the guest each in a level of its own:
- `execute in the_nether run tp` moves the guest alone. From the Nether, `execute in overworld` and
`execute at` the host change and test blocks in the host's level.
- Mobs and armour stands fall in two levels at once, and every entity id is unique across the
levels.
- The guest leaves in the Nether and joins again there.
- The guest dies in the Nether and respawns in the Overworld. With a `spawnpoint` and then a
respawn anchor set in the Nether, it respawns there, and the anchor loses a charge.
- The host takes a Nether portal alone.
- The guest takes an End portal, an End gateway and then the exit portal alone.
- The host saves, quits and opens the world again with the guest in the Nether, and the guest
joins again there.
## Not done yet
- **End credits for server players.** The first exit from the End should show a player the credits
(`EndPortalBlock.entityInside`, `seenCredits`). The client's WinScreen is #338.
- **Entities through portals between levels.** Mobs, items and minecarts that enter a portal on a
server, and portal tickets (`TeleportTransition.PLACE_PORTAL_TICKET`), are not handled.
- **Unlimited selectors.** `@e` without a distance or volume reads only the source's level. Vanilla's
reads every level.
+1 -1
View File
@@ -90,7 +90,7 @@ not tick cost, so it is in scope here (see section 9).
|---|---|
| `online-mode=true` | **Works** (ServerLoginPacketListenerImpl): a 1024-bit RSA key pair at start ("Generating keypair"), the encryption request, the shared secret and challenge, AES/CFB8, and the session service's `hasJoined` check (with the address when `prevent-proxy-connections` is on), with vanilla's log lines and messages. `test_online_mode_parity.py` runs the same logins against vanilla's server and Horizon's with a mock session service. |
| Secure chat | **Works** (`SignedMessageChain`, `LastSeenMessagesValidator`, `MessageSignatureCache`): the chat session update and its profile key, checked against the services' `playerCertificateKeys`; signed chat, `say`, `me` and `msg`, relayed with their signatures and last-seen lists; `enforce-secure-profile` (with `online-mode`) refuses unsigned chat; and vanilla's log lines (`[Not Secure]`, the decoder's warnings, the kicks). Offline servers and players without a chat session chat unsigned, as on vanilla. `test_secure_chat_parity.py` runs the same signed and unsigned players against vanilla's server and Horizon's, with test keys and a mock services server. |
| Nether and End | **Players can't change dimension.** The engine keeps one dimension loaded (`Game::enter_dimension` moves only the local single-player player), and the hub serves one `dimension` to everyone. |
| Nether and End | **Works**: the server holds a level per dimension, and each player is in its own (portals, `execute in … tp`, respawn). `test_server_dimension_players_parity.py` checks it against vanilla. How it works, its cost and what's left: [server-levels.md](server-levels.md). |
| Refused logins | Logged as vanilla does: `Disconnecting <name> (/address): <reason>`, then `<name> (/address) lost connection: <reason>`, and the session errors (`Username '<name>' tried to join with an invalid session`, `Couldn't verify username because servers are unavailable`). |
| Gameplay for remote players | Checked against vanilla's server with a vanilla-codec client (#484, `tools/test_dedicated_server_parity.py`): a right click with an item on a block uses it once, a dead player's commands run, players on a team without friendly fire don't hurt each other, and a player's projectiles are theirs (their ender pearl takes them). The recipe book, status effects and block sync while digging (#500) work. Left: a player's projectiles don't hit other players (no bow PvP between guests), and a mob a guest kills counts in the host's statistics and advancements, not the guest's (`mob_died` runs as the host). |
| Defaults that surprise owners | `white-list=true` is vanilla 26.3's default, so a fresh server refuses everyone until they are added. That matches vanilla, so the first-run flow (section 3) asks about the whitelist up front. |
+73 -22
View File
@@ -13,17 +13,19 @@ Both are off by default. With no pack selected the renderer draws exactly what i
| Part | State |
| --- | --- |
| Renderer layout (below) | today's code |
| Horizon shader packs: `composite` stage, uniforms, hot reload, Shader Packs page | done (the page: list, pick, open the folder) |
| Horizon shader packs: `deferred`, `gbuffer`, `shadow` stages, custom textures | planned |
| Horizon shader packs: `composite` stage, uniforms, hot reload, Shader Packs page | done (the page: list, pick, open the folder, drop a pack on it) |
| Horizon shader packs, api 2: stage `format`s, `[profiles]`, option descriptions, a `noise` texture, the opaque depth, a G-buffer reconstructed from depth, a sun/moon shadow map (Stages, below) | first slice: `examples/shaderpacks/horizon-ultra` |
| Horizon shader packs: `deferred`, `gbuffer`, `shadow` stages (the pack's own code in the world pass) | planned |
| Shader Pack Settings page: a pack's options, sub-screens, sliders, profiles and Reset, Horizon and Java packs alike; applied once on Done, as Iris does | done |
| Java shader packs: preprocessing + GLSL parse coverage | spike done: 450 of 470 programs reach valid WGSL (below) |
| Java shader packs: preprocessor (`crates/horizon-shaderpack`: includes, options, Iris's macros, JCPP's `#if` and `#define` rules) | done: every program of the three test packs preprocesses; ten packs tested (Compatibility, below) |
| Java shader packs: GLSL → WGSL (`horizon_shaderpack::translate`: syntax-tree legaliser, naga) | done: the 464 programs the three test packs enable by default translate (below) |
| Java shader packs: `shaders.properties` (`horizon_shaderpack::properties`: screens, sliders, profiles, `program.*.enabled`, image formats, blend modes) | done, no screen yet: read like Iris for the three test packs |
| Java shader packs: full-screen pass plan (`horizon_shaderpack::pipeline`: `DRAWBUFFERS`/`RENDERTARGETS`, `colortexN` formats and clearing, buffer flips) | done: planned for the three test packs |
| Java shader packs: full-screen passes drawn (`java_pack.rs`, `gfx/java_stages.rs`: `begin`, `prepare`, `deferred*`, `composite*`, `final` over Horizon's world) | first slice: BSL and Complementary run (below) |
| Java shader packs: custom uniforms (`horizon_shaderpack::uniforms`), `sunPathRotation`, `clouds`/`sun`/`moon`, eye light | done for the full-screen passes (below) |
| Java shader packs: preprocessor (`crates/horizon-shaderpack`: includes, options, Iris's macros, JCPP's `#if` and `#define` rules, `.lang` files) | done: every program of the three test packs preprocesses; ten packs tested (Compatibility, below) |
| Java shader packs: GLSL → WGSL (`horizon_shaderpack::translate`: syntax-tree legaliser, naga; struct and nested-array varyings, vertex `texture`, `mat2(vec4)`, `1 << 31`) | done: the 464 programs the three test packs enable by default translate (below) |
| Java shader packs: `shaders.properties` (`horizon_shaderpack::properties`: screens, sliders, profiles, `program.*.enabled`, image formats, blend modes, `texture.*`) | done: read like Iris for the three test packs |
| Java shader packs: full-screen pass plan (`horizon_shaderpack::pipeline`: `DRAWBUFFERS`/`RENDERTARGETS`, `colortexN` formats and clearing, buffer flips, `blend.*`) | done: planned for the three test packs |
| Java shader packs: full-screen passes drawn (`java_pack.rs`, `gfx/java_stages.rs`: `begin`, `prepare`, `deferred*`, `composite*`, `final` over Horizon's world) | first slice: BSL and Complementary run (below); `depthtex1`/`depthtex2` before translucent geometry, `blend.*`, PNG `texture.<stage>.*` and `texture.noise` |
| Java shader packs: custom uniforms (`horizon_shaderpack::uniforms`), `sunPathRotation`, `clouds`/`sun`/`moon`, eye light, `wetness` | done for the full-screen passes (below) |
| Java shader packs: `gbuffers_terrain`, `gbuffers_water` (`gfx/java_terrain.rs`: Horizon's terrain fed to the pack's programs) | first slice: MakeUp Ultra Fast, Chocapic13' and BSL draw their own terrain and water (below) |
| Java shader packs: other `gbuffers_*`, `shadow`, custom textures, images, compute, option screen | planned |
| Java shader packs: other `gbuffers_*`, `shadow`, `.dat` and resource-location textures, images, compute | planned |
## How the renderer draws a frame today
@@ -45,8 +47,7 @@ Everything is in `crates/horizon-client/src/gfx.rs`, `Renderer::render`, one com
4. **Screen effects** (`screen_effects.rs`): pumpkin blur, portal, powder snow, vignette, nausea, as
full-screen quads.
5. **Menu blur** (`menu_blur.rs`, `menu_blur.wgsl`): vanilla's `menuBackgroundBlurriness` behind screens.
6. **Menu grade** (`post.rs`, `post.wgsl`): the Horizon menus' frosted backdrop.
7. **HUD** (`hud.rs`, `hud.wgsl`): GUI, text, items in slots.
6. **HUD** (`hud.rs`, `hud.wgsl`): GUI, text, items in slots.
All world shaders share one uniform block, `Globals` in `gfx.rs` (`struct Globals` in `terrain.wgsl`):
view-projection, inverse view, fog colour and distances, sky colour, sun direction, sunrise colour, game time.
@@ -61,11 +62,18 @@ The lightmap, fog and sky colours are computed on the CPU (`environment.rs`, `fo
`~/Library/Application Support/horizon` on macOS, `~/.local/share/horizon` on Linux), not the launcher's version
folder. A pack with a `pack.toml` at its root is a Horizon pack; a folder with `shaders/`, or a `.zip`, is a Java
pack.
- The **Shader Packs** page lists them: a sidebar section in the Horizon menus, **Video Settings → Shader Packs...**
in the Classic ones, and the Shader Pack row of the graphics settings leads to it. It shows the folder's full path
- The **Shader Packs** page lists them: **Video Settings → Shader Packs...** (where Iris puts its button), **Options →
Horizon Settings... → Shader Packs...**, and the Shader Pack row of the graphics settings lead to it. It shows the folder's full path
and an *Open Folder* button (the folder is made if it is missing), then one switch per pack: turning one on picks
it, turning it off is the vanilla picture. With no pack, it says so under the path. The list is read again every
second while the page is open, so a pack dropped into the folder shows up.
second while the page is open, so a pack dropped into the folder shows up. A `.zip` or pack folder dropped on the
window while the page shows is copied into the folder and picked (Iris's `ShaderPackScreen.onFilesDrop`); one of
that name already there is left alone.
- With a pack on that has options, **Shader Pack Settings...** opens them: Horizon packs' `[options]` and
`[profiles]`, Java packs' `#define`/`const` options laid out by `shaders.properties` (`screen`, `screen.<name>`,
`sliders`, `profile.*`) and named by `lang/en_us.lang` (`option.*`, `value.*`, `screen.*`, `profile.*`, as Iris;
without one, the option's own name). The values are saved and the pack built again once, when the page closes
(Iris applies on Done), not on every click or slider step. A saved value an option doesn't list is ignored.
- The choice is kept in `horizon-graphics.txt` (`shaderPack:<folder or zip name>`, empty = off). A pack's option
values are kept in `shaderpacks/<pack>.txt`, as Iris does.
- A pack that fails to load or compile leaves the vanilla picture (or the last pack that worked) on and says why on
@@ -81,7 +89,7 @@ my-pack/
composite.wgsl
bloom.wgsl
textures/
noise.png # planned
noise.png # api 2: [textures] noise
LICENSE
```
@@ -114,6 +122,24 @@ step = 0.05
[options.vignette]
label = "Vignette"
default = true
description = "Darkens the corners." # optional: the button's tooltip
```
Api 2 (`api = 2`) adds:
```toml
[[stage]]
kind = "composite"
shader = "shaders/lighting.wgsl"
format = "rgba16float" # this stage's target: rgba8unorm, rgba16float or rgb10a2unorm; the last stage
# always writes the screen's format, so earlier ones can keep HDR colour
[profiles.low] # the Profile button cycles these; "Custom" when the values match none
vignette = false
saturation = 1.0
[textures]
noise = "textures/noise.png" # replaces the prelude's noise_texture (256x256 random RGB without it)
```
Options become WGSL [pipeline-overridable constants](https://www.w3.org/TR/WGSL/#override-decls): the shader
@@ -178,6 +204,29 @@ Prelude helpers: `linear_depth(depth) -> f32` (blocks from the eye), `view_posit
The uniform layout only grows: a new field goes at the end and the `api` number goes up; a pack that declares an
older `api` still loads.
An `api = 2` pack's stages get a second prelude after the first (`shader_pack_prelude_api2.wgsl`; api 1 packs don't,
so names they declare themselves can't clash):
| Binding | WGSL | What |
| --- | --- | --- |
| 6 | `frame_ext: FrameExt` (uniform) | last frame's view and projection and camera, the shadow map's matrices, resolution and distance, eye light, smoothed rain |
| 7, 8 | `scene_normal`, `scene_material: texture_2d<f32>` | the G-buffer (below) |
| 9 | `opaque_depth: texture_depth_2d` | the world's depth before translucent geometry (water, glass, ice) |
| 10, 11 | `shadow_depth: texture_depth_2d`, `shadow_sampler: sampler_comparison` | the sun's (the moon's at night) shadow map |
| 12, 13 | `noise_texture: texture_2d<f32>`, `repeat_sampler: sampler` | `[textures] noise`, linear, repeat |
Helpers: `opaque_depth_at(uv)`, `world_normal_at(uv)`, `material_at(uv)` (block light, sky light, translucent mask,
roughness), `reproject_uv(world_offset)` (last frame's uv and depth), `sample_shadow(world_offset, normal)` (5-tap
PCF, 1 lit .. 0 shadowed), `aces_tonemap(rgb)`.
What each costs, only while a stage reads it (naga reports the bindings each entry point uses): the opaque depth, a
depth copy between the opaque and translucent halves of the world pass; the G-buffer, one full-screen pass after
the world; the shadow map, a depth pass of the terrain and entities from the light. Limits of this first slice: the
G-buffer is reconstructed from depth and colour (normals from neighbouring depths, block light estimated from
brightness, sky light the camera's), not written by the world's shaders; the shadow map holds the sections the
camera draws, so casters outside the view throw no shadow, and none of the terrain where Metal draws sections as one
list (`gfx/flat.rs`, more than 4096 of them). The `deferred`, `gbuffer` and `shadow` stages above replace these.
### How it renders
With a pack on, the world pass draws into the world target of `gfx/world_post.rs` (it exists already for resolution
@@ -369,7 +418,8 @@ render them (Chocapic13' packs its G-buffer into them; half floats broke it).
Occlusion culling works as in Horizon's world pass where the GPU has it: the pack's terrain program draws the
sections the last test saw, the boxes of the others are tested against that depth (in OpenGL's layout, in a pass of
their own since the pack's targets vary), and the pack's program then draws the ones in sight.
their own since the pack's targets vary; on Metal the test reads the depth in the shader, as Horizon's does), and the
pack's program then draws the ones in sight, flat draws included.
What makes Horizon look like OpenGL to the pack:
@@ -402,12 +452,13 @@ What makes Horizon look like OpenGL to the pack:
Measured on the Mac mini (M4 Pro) with the packs' default options: BSL v10.1.8 and Complementary Reimagined r5.9.3
grade and light Horizon's world as their post-processing would. Sildur's Vibrant v2.02 draws only its sky: its
`deferred` reads the albedo `gbuffers_*` write to `colortex4` (not checked again since the terrain programs run).
Without the other `gbuffers_*` and `shadow`, no pack has its shadows or sky look yet; Distant Horizons' and Voxy's depth read as far. Not supported yet: images and
compute (`.csh`; a pack that needs them doesn't load), mipmapped targets (`colortexNMipmapEnabled` is read but
ignored), custom textures, the option screen; shadow matrices are identity. With the pack's terrain: entities, the
sky, the hand, weather and clouds are still Horizon's (in `colortex0` only), block ids
come from sprite names rather than block states, distant (LOD) terrain doesn't repeat its textures, and only the
overworld has been checked.
Without the other `gbuffers_*` and `shadow`, no pack has its shadows or sky look yet; Distant Horizons' and Voxy's
depth read as far. Horizon's world goes into the target the pack's `gbuffers_terrain` (or the program Iris falls back
to) draws to first: `colortex0` for most packs, `colortex1` for MakeUp. Not supported yet: images and compute (`.csh`;
a pack that needs them doesn't load), mipmapped targets (`colortexNMipmapEnabled` is read but ignored), `.dat` and
resource-location custom textures (PNG files in the pack only); shadow matrices are identity. With the pack's terrain:
entities, the sky, the hand, weather and clouds are still Horizon's (in that first target only), block ids come from sprite names rather than block states, distant (LOD) terrain doesn't repeat its textures,
and only the overworld has been checked.
### Compatibility
+37 -6
View File
@@ -9,7 +9,7 @@ The one exception is the anonymous ["I'm playing" ping](#the-im-playing-ping) be
`telemetry/consent.json` in the game folder (`HORIZON_HOME`, else `horizon` in the platform data folder):
```json
{ "version": 1, "answered": 1792060800, "choices": { "performance": true, "crashes": true, "bugs": false, "benchmarks": false }, "install_id": "3f2c…" }
{ "version": 2, "answered": 1792060800, "choices": { "performance": true, "crashes": true, "bugs": false, "benchmarks": false }, "install_id": "3f2c…" }
```
- `version` is the consent version the player answered (`CONSENT_VERSION`). It goes up when what is collected changes. The launcher then asks again, and until the player answers nothing new is kept or sent.
@@ -34,7 +34,24 @@ Every item has `day` (days since 1970, UTC: no finer time), `source` (`launcher`
| `bug` | bug reports | `system`, the player's `text` (up to 4000 characters), and the `log` only if they add it after reading it | 80 KiB | 5 |
| `benchmark` | benchmark uploads | the benchmark report as `docs/benchmark-report.md` defines it, as it is, with its own schema field | 128 KiB | 10 |
`system` is the OS and its version, the architecture, the CPU model and thread count, installed memory rounded to the GiB, and the GPU, driver and graphics backend.
`system` describes the machine, with what can explain its performance. A field the OS doesn't give is empty or 0:
| Field | What | Example |
|---|---|---|
| `os`, `os_version`, `arch` | the OS, its version, the CPU architecture | `linux`, `Fedora Linux 43`, `x86_64` |
| `cpu`, `threads`, `cores` | the CPU model, its threads and physical cores | `13th Gen Intel(R) Core(TM) i7-13700KF`, 24, 16 |
| `cpu_base_mhz`, `cpu_boost_mhz` | base and boost clock, where the OS gives them (not on Apple silicon) | 3400, 5400 |
| `ram_gb` | installed memory, rounded to the GiB | 32 |
| `gpu`, `gpu_vendor`, `gpu_kind` | the GPU the game draws with, its maker, `integrated` or `discrete` | `NVIDIA GeForce RTX 4080`, `nvidia`, `discrete` |
| `vram_mb` | a discrete GPU's own memory, rounded up to 256 MiB | 16384 |
| `driver`, `backend` | the driver version and the graphics API (`Vulkan`, `Metal`, `Dx12`) | `580.95.05`, `Vulkan` |
| `storage` | the drive under the game folder: `nvme`, `ssd` or `hdd` | `nvme` |
| `display` | the screen the window opened on: `width`, `height` (physical pixels), `refresh_hz`, `scale` | 2560, 1440, 165, 1.0 |
| `power`, `form` | on mains or battery (`ac`, `battery`), `laptop` or `desktop` | `ac`, `desktop` |
The launcher's own items (bug reports sent from it) have no GPU or screen: only the game knows them. The memory given to the game is not a setting in Horizon (no Java heap): `peak_ram_mb` is what it used. Benchmark reports carry the same facts in their `hardware` (`docs/benchmark-report.md`).
No serial number, host name, user name, MAC address or path is read. Settings → Data collection → "View what would be sent" and `horizon-launcher data show` print every field as it would leave this machine.
A summary (`frames`, `ticks`) is the count, the 50th, 95th and 99th percentile and the maximum in milliseconds (to the tenth), and 14 bucket counts: under 4 ms, 4–6, 6–8, 8–10, 10–12, 12–14, 14–16.7, 16.7–20, 20–25, 25–33.3, 33.3–50, 50–100, 100–250, and 250 ms and more. Raw frame times never leave: `Timings` records them in tenths of a millisecond (20 KB however long the session) and only its summary is kept. A perf item is under 1 KiB.
@@ -45,7 +62,8 @@ Never sent: account names or UUIDs, world names, server or LAN addresses, chat,
- `telemetry/outbox/` holds one JSON file per item, `<day>-<kind>-<random>.json`. It never holds more than 200 items or 2 MiB, and the oldest go first. `kept.json` counts today's items per kind against the caps above.
- The launcher sends the outbox when it starts and when it closes. Items go as one JSON batch (`{"schema":1,"install_id":…,"items":[…]}`, up to 64 items and 1 MiB), compressed with zstd: `POST /v1/batch` with `Content-Encoding: zstd`. A day's perf summaries are under 2 KB on the wire.
- After a failure the launcher waits a minute, doubling up to a day, and sends at most 8 batches a day. A batch the server refuses with a 4xx (not 429) is dropped.
- `HORIZON_TELEMETRY_URL` sets the server. There is none by default: until there is, nothing is sent and the outbox stays within its caps.
- The server is `https://telemetry.playhorizon.dev` (`DEFAULT_ENDPOINT`), on Railway in the EU (`europe-west4`, Amsterdam). `HORIZON_TELEMETRY_URL` names another one (a local server); `HORIZON_TELEMETRY_URL=off` sends nothing at all, no ping either. Tests, CI and the benchmark and test harnesses set `off`.
- What is sent still depends on the switches: with every switch off nothing but the ping leaves, and the outbox stays empty.
- `SCHEMA` versions the format. New optional fields keep it. A field that changes meaning or goes bumps it, and the server keeps reading the older ones.
## The "I'm playing" ping
@@ -68,13 +86,26 @@ The server keeps sessions in memory only, never on disk, and never with the send
{ "playing": 1240, "lan": 85, "versions": { "v2026.10.22": 1100, "other": 140 }, "platforms": { "linux": 300, "macos": 240, "windows": 700 } }
```
The launcher reads it when it opens and every minute after, and shows "N playing now" on the Play page. It shows nothing when the server can't be reached. Like the rest, there is no server by default (`HORIZON_TELEMETRY_URL`): until there is one, the game sends no ping and the launcher shows no count. `HORIZON_NO_HEARTBEAT=1` keeps automated runs out of the count.
The launcher reads it when it opens and every minute after, and shows "N playing now" on the Play page. It shows nothing when the server can't be reached. `HORIZON_TELEMETRY_URL=off` turns both off; `HORIZON_NO_HEARTBEAT=1` keeps a single automated run out of the count.
## Server
- `POST /v1/batch`
- `DELETE /v1/installs/<install_id>`: deletes everything sent under that ID.
- `GET /v1/aggregate`: the anonymous totals the website's results page reads.
- `GET /v1/aggregate`: the anonymous totals the website's results page reads. Its `breakdowns` split the play sessions of the period by hardware class (below), each class with its installs, sessions, hours and mean p50 and p99 frame times.
- `GET /v1/benchmarks/summary`: players' benchmark uploads grouped by GPU, CPU, render distance and game for playhorizon.dev/benchmarks. A group shows only with at least 3 different installs, and only its medians and counts: no install ID, day, OS version, driver, exact memory or screen. Uploads are never published one by one. Each group's `breakdowns` count its installs per hardware class.
- `POST /v1/live` and `GET /v1/live`: the "I'm playing" ping and the live count.
`crates/horizon-telemetry-server` is the server. Its [README](../crates/horizon-telemetry-server/README.md) covers storage (about 190 bytes per play session), retention (180 days of raw rows, anonymous daily totals kept), rate limits and hosting.
Public output never holds a raw hardware value, only these classes (`src/classes.rs`, the same in `website/scripts/benchmarks.mjs`), and a class is published only with at least 3 different installs:
| Breakdown | Classes |
|---|---|
| `ram` | 4 GB or less, 8 GB, 16 GB, 32 GB, 64 GB or more |
| `vram` | shared (integrated GPU), 2 GB or less, 4, 6, 8, 12, 16 GB, more than 16 GB |
| `storage` | nvme, ssd, hdd |
| `os` | linux, macos, windows |
| `gpu_kind` | integrated, discrete |
The driver, OS version, clocks, screen and power are kept raw for the 180 days of retention, to explain a slow group, and never published.
`crates/horizon-telemetry-server` is the server, at `https://telemetry.playhorizon.dev` on Railway (one SQLite file on a volume, region `europe-west4`). Its [README](../crates/horizon-telemetry-server/README.md) covers storage (about 190 bytes per play session), retention (180 days of raw rows, anonymous daily totals kept), rate limits and hosting.
+8 -8
View File
@@ -22,10 +22,10 @@ game and the launcher of the 0.2 line.
0.2. A `feature` label no longer bumps anything: it only lists the change under **New**.
- **Patch releases** are every release the train makes: the patch after the newest release tagged on the line, game
and launcher counted separately (the game releases more often, so `v0.2.14` can go with `launcher@0.2.3`).
- **Alpha builds** are not separate tags. As before, every game release is published as a GitHub pre-release (an alpha build, what
the launcher's Alpha channel installs) under its final tag and promoted in place to stable in the daily
promotion at 20:00 UTC, once it has been out 6 hours ([Channels](release-flow.md#channels)). `v0.2.4` is the same
build whether it is still a beta or already stable.
- **One channel** (since 2026-10-23): every game release is published under its final tag as the release and
GitHub's latest, once its smoke test passed and no `release-blocker` is open
([One channel](release-flow.md#one-channel)). The game pre-releases from before (v0.2.1 on, the old Alpha
channel) keep their tags and stay pre-releases.
- **Pre-release tags** (`v0.3.0-rc.1`, `v0.3.0-beta.2`) are semver's and are reserved for a hand-made preview of a
new line; the train never makes them. Every reader orders them before their release and after the release
before (`v0.2.9` < `v0.3.0-beta.1` < `v0.3.0-rc.1` < `v0.3.0`).
@@ -43,7 +43,7 @@ Every 0.2 tag is newer than every tag from before 0.2. Within each:
A tag is a 0.2 tag when it is `v` or `launcher@` followed by exactly three numbers (and an optional `-PRE`) with a
major below 1000; a date's first number is a year, so `v2026.10.21` never is. The rule is written once per
language, with the same tests: `crates/horizon-server/src/update.rs` (`newer`), `launcher/src/backend.rs`
(`release_order`), `tools/release_train.py` (`tag_key`, also used by `tools/release_channels.py`) and
(`release_order`), `tools/release_train.py` (`tag_key`) and
`website/src/versions.js`.
## The workflows
@@ -55,9 +55,6 @@ language, with the same tests: `crates/horizon-server/src/update.rs` (`newer`),
- **`launcher.yml`**: `decide --kind launcher` picks `launcher@0.2.N`; the build gets `HORIZON_LAUNCHER_VERSION`
(`0.2.N`) and `HORIZON_LAUNCHER_TAG` (`launcher@0.2.N`). The tag tells the launcher which line it is on: a release
built with only the version (every launcher before 0.2) is a `launcher-v` one.
- **`promote.yml`**: `tools/release_channels.py` promotes the newest due beta, never one older than the stable
release; with the shared order, `v0.2.0` follows the last dated stable release and no dated beta can follow
`v0.2.0`.
- **Notes**: a line's first release (`X.Y.0`) opens with a paragraph saying so; `v0.2.0`'s and `launcher@0.2.0`'s say
that releases are numbered from now on, and tell server owners to run `horizon-server update` (or, if their server
says it is up to date, `horizon-server update --version v0.2.0`).
@@ -98,6 +95,9 @@ the fleet's `release-kick` and the orchestrator's heartbeat prompts.
## The day Ludovic says go
Done on 2026-10-22; kept as the record of how 0.2 went out. `promote.yml` and `tools/release_channels.py`, which
it uses, are gone since the single channel (2026-10-23, [One channel](release-flow.md#one-channel)).
Run by the orchestrator, in this order. Until step 3, nothing is published.
1. Merge, in order: this page, the `horizon-server update` order, the launcher order, the release line (train,