Horizon: a map for agents

Minecraft: Java Edition 26.3 rewritten in Rust (wgpu). Vanilla is the specification wherever it has the feature. Read CONTRIBUTING.md once; this page tells you where things are. Feature → files → harness for the most-changed areas: docs/architecture.md.

Rules that bite

• Never commit Mojang's files: game jars, assets, decompiled source, prepared resources (.local/). tools/check_public_tree.py rejects them; git config core.hooksPath .githooks runs it on commit.
• Keep your runs away from real player data. Any game or launcher you start gets fresh mktemp -d folders in HORIZON_HOME (logs, crash reports, telemetry consent, recordings; not saves), HORIZON_LAUNCHER_HOME, XDG_DATA_HOME and XDG_CONFIG_HOME, plus HORIZON_LAUNCHER_NO_SELF_UPDATE=1 and HORIZON_NO_AUDIO=1. Saves, options.txt and caches go in the game folder, by default the working directory: start the game from a scratch folder with --game-dir pointing at it, or they land in the repo root, hidden by .gitignore. For the launcher, HORIZON_LAUNCHER_TRASH, HORIZON_LAUNCHER_CLIPBOARD and HORIZON_LAUNCHER_DESKTOP pointing into the scratch home. Never write to ~/.local/share/{applications,horizon,horizon-launcher} or ~/.local/bin.
• Mark what an agent posts. A PR body starts with a line naming the person whose agent opened it and the tool: > 🤖 Opened by <login>'s AI agent (<tool, model>), not by <login> personally., where <login> is the GitHub account the PR is opened from (gh api user --jq .login). Issues say "Filed by", reviews "Review by". Every comment starts with 🤖 Agent:. Write only as the person you work for: the lines on this page that name Ludovic are for his own agents (account ludovic111), never for anyone else's.
• Attribution. Commits end with a Co-Authored-By: line for the agent that wrote them, and PR bodies with that agent's own "Generated with" line. Example, Ludovic's agents (Claude Code on ludovic111): first line > 🤖 Opened by Ludovic's AI agent (Claude), not by Ludovic himself., commits Co-Authored-By: Claude <model> <noreply@anthropic.com>, last line 🤖 Generated with [Claude Code](https://claude.com/claude-code).
• Everything players run is Rust. Python/Java only for dev tools and harness drivers in tools/.
• Horizon-only features follow docs/design-system.md and are off by default where they would change the vanilla look.
• Small PRs (< ~500 lines). Labels: feature (players get something new), skip-release (they see no change), none for a fix. Agents never add release-now: the maintainer decides it. Merges ship in batches of 5, or after 6 hours (docs/release-flow.md).
• Contributors first: gh pr list --state open --search <area> before you start; never duplicate theirs.
• No hardcoded user-facing strings. Keep UI translation-ready from the start. In the launcher (launcher/), wrap visible text with tr("...") or trf("... {arg} ...", &[("arg", &val)]) from crate::i18n instead of raw string literals or format!. In the game, use translation keys (Text::tr, lang::get), never hardcoded English strings.
• Claim before you start: comment /claim on the issue (no issue yet: open one, then claim it). An assigned issue is taken, and so is one labelled in progress (claimed on Discord): pick another. /unclaim when you stop; a claim with no open PR linking it is released after 5 days. The issues free to claim, without reading threads: gh issue list --search 'is:open no:assignee -label:"in progress" -label:tracker -label:proposal -label:"not claimable" -linked:pr'
• Controllers reach what registers. Draw controls with a registering helper (ui::button, settings_shell::foot_button); graphics_style::button and screen_draw::button only paint, and registering one part of a screen ends its crosshair, so register all of it.

Crates

Game workspace (root Cargo.toml); launcher/ and crates/horizon-telemetry-server are separate workspaces.

Other top-level folders: tools/ (harnesses and dev scripts), tests/ (Python unit tests: python3 -m unittest discover -s tests), mods/horizon/src/test/java/dev/horizonlab/parity/ (Java oracles), docs/, .github/workflows/. The website (playhorizon.dev) is the private horizon-rust/horizon-site: its build reads README.md, launcher/links.json, docs/api/, roadmap/roadmap.json and crates/horizon-theme/tokens.css from main.

Write tests with signal

• Test observable behavior, not words in docs, comments or source. Keep checks for machine-consumed contracts.
• Use independent expected values or a vanilla oracle; do not derive the answer from the code under test.
• Test outcomes, not only calls to stubs. Use mocks to isolate behavior, not as the behavior itself.
• Skip tests of trivial constants, derives and getters, or behavior already covered by another test.
• Avoid pinning implementation details; a harmless refactor should not break a behavior test.
• Make slow tests faster without removing cases or weakening their coverage.
• Never delete parity harnesses or tests that pin vanilla behaviour: they are the spec.

Build and test fast

python3 tools/pr_ready.py                  # the self-check: fmt, clippy -D warnings, touched crates' tests, harnesses; paste its block in the PR
python3 tools/pr_ready.py --quick          # same without harnesses
cargo test -p horizon-client -p horizon-client-lib --lib --bins --tests   # skips the examples (pr_ready does this); `--doc` separately
cargo test -p horizon-client-lib --lib mod_content::tests:: -- --ignored   # the slow content-root tests, #[ignore]d; pr_ready runs them when mod content, assets, blocks or items change
cargo build --profile fast -p horizon-client        # optimized, quick to link: use it to play or run lan_e2e
python3 tools/parity.py --changed origin/main       # the harnesses your branch can affect (CI's parity job)
python3 tools/parity.py --changed-files paths.txt --list   # which harnesses cover these files, without running them
python3 tools/parity.py mob_ai sculk       # named harnesses
python3 tools/lan_e2e.py --check chest     # two real games over LAN (server-thread host)
python3 tools/agent_control_e2e.py         # horizon-ctl / MCP end to end

• Harnesses and the game need the vanilla data in .local/ (minecraft/, horizon-client/26.3, datagen/, tools/): see docs/parity-workflow.md. Without it, pr_ready lists the harnesses for CI.
• A harness = tools/test_<name>_parity.py + a Java oracle (mods/horizon/src/test/java/dev/horizonlab/parity/Vanilla*Oracle.java)
  • a Rust probe: crates/<crate>/examples/<name>_{probe,fixture}.rs (mostly horizon-world and horizon-client), or the game binary with a fixture env var (game/dispense_fixture.rs, game/sculk_fixture.rs, game/command_harness.rs, game/net_harness.rs). Copy a nearby harness for a new one.
• Developing a native mod? Run horizon-launcher settings native-profile dev once. dev builds the game crate unoptimized: a mod edit rebuilds about 6× faster than with performance, while game logic runs up to about twice as slow. Use it while developing, not for playing; performance stays the default for players and releases (docs/native-mods.md).
• Probes build into .local/parity-target/; harnesses find binaries via lab.cargo_target(), never target/.
• Harness selection uses Cargo dep-info and reachable-code narrowing (tools/parity_reach.py). horizon-client-lib builds the control tool and client probes without gameplay; their dep-info excludes game.rs and game/, so gameplay edits do not rebuild or select those probes. Source paths remain in crates/horizon-client/. Measure actual harness selection on refreshed records with tools/parity.py --changed-files paths.txt --list; historical counts are not a guarantee.
• Rust integration tests: crates/horizon-client/tests/ (lan_bot.rs, generation_saves.rs, streaming_meshes.rs).
• Linux needs libasound2-dev libudev-dev; --no-default-features drops audio, controllers, discord, friends and heartbeat (the server build).
• Run and drive the game (starts the horizon-client beside horizon-ctl; other arguments go to the game): target/fast/horizon-ctl --socket $PWD/ctl.sock launch --world W --creative --offscreen --wait --resources $PWD/.local/horizon-client/26.3, then horizon-ctl --socket … state|keys|turn|command|screenshot|quit (docs/horizon-ctl-commands.md).

Vanilla reference

• Start parity work from the port ledger, not grep: python3 tools/port_ledger.py issue N (or where Class.method, what file:line), and check --base origin/main before the PR. How: .claude/skills/vanilla-parity/SKILL.md, docs/port-ledger.md.
• Decompiled sources: .local/minecraft/26.3/sources/{client,server}/ (python3 tools/lab.py decompile).
• Bytecode queries (callers through lambdas, every overload): python3 tools/rea_vanilla.py method net.minecraft.world.level.block.DispenserBlock dispenseFrom (docs/decompilation-status.md).
• A harness runs the oracle against the real 26.3 jars and the Rust probe on the same inputs, then compares their JSON. Oracle runs are cached by tools/parity_shim.py; --fresh reruns them.
• Mirror vanilla's Math calls with horizon_core::jmath, and vanilla's RNG with horizon_core::random: random draws must happen in vanilla's order.

horizon-client: where things live

L: = lib (crates/horizon-client/src/, or crates/horizon-client-render/src/ for the modules that crate holds, under the same horizon_client::<module> paths), G: = gameplay (crates/horizon-client/src/game/), also in the lib in normal builds. Gameplay keeps its horizon_client::<module> imports through a self-crate alias. The executable contains only the allocator, mod API marker and a call to entry::main. For unit tests, the lib excludes entry and game, and the executable test target owns game so its process-wide test state stays separate from the library tests. This compiles gameplay twice for executable tests.

How Game is organised

• struct Game (game.rs) holds everything. Its methods are spread over many files: game.rs keeps the core (tick, render, input, inventory, world open/close) and each game/<feature>.rs adds an impl Game<'_> block for one feature, with its own state types. Fields stay private to the gameplay module and its descendants. Gameplay tests run in the gameplay library, separate from reusable-library tests.
• Find a feature's code: grep -rn "fn tick_<thing>\|fn <verb>_<thing>" crates/horizon-client/src/game*; the file is usually game/<thing>s.rs. Who calls it: grep the name in game.rs's fn tick / fn tick_world.
• Fields that say which mode runs: remote (this window is a client of a server: multiplayer, LAN guest, or single player on its server thread), lan (LanHost: this world is open to the network), integrated (the window's own server thread), serving (this Game is that server thread), options.dedicated. fn tick returns tick_remote() when remote is set; a server ticks its levels (fn tick_world).
• A server's players run through the shared gameplay code: as_guest swaps the guest's state (position, inventory, mode, mining, item use) into Game for one call (game/lan_actions.rs), and levels.rs swaps whole dimensions in the same way. Changes reach clients through the block log, level events and the entity tracker (lan/tracking.rs, game/lan_entities.rs).
• Shared read-only data: Resources (res: blocks, items, recipes, mob types, biomes) and PackResources (pack), both in game.rs, their methods in game/resource_tables.rs.

Single player runs on a server thread

game/integrated.rs runs a second Game (serving) on a "Server thread" with one level per dimension; the window joins it as a client through memory (remote), exactly as a LAN guest or a dedicated server's player does (#1514). A window's Game never ticks a world itself: the old in-frame path is gone (--in-frame and --no-server-thread only print a notice; HORIZON_SERVER_THREAD is ignored). Open [server-thread] issues list the gaps left.

Single player, LAN guests and dedicated servers all run the server code, so a fix there serves all three. Test the server thread when you touch player-facing gameplay:

cargo run --profile fast -p horizon-client -- --resources .local/horizon-client/26.3 --world T               # server thread
python3 tools/lan_e2e.py --check <name>                  # host on its server thread, guest is a server client
python3 tools/parity.py dedicated_server server_entities server_player_damage

Docs worth knowing

docs/parity-workflow.md (runner, gate, shards, scopes) · docs/native-client.md (options, controls, horizon-ctl) · docs/server-levels.md (levels per dimension) · docs/rust-parity.md (what is ported) · docs/known-issues.md · docs/release-flow.md · docs/README.md (index).