Contribute

Questions and ideas are welcome on Discord. Bugs and feature requests go in GitHub issues. If you want to take something on, say so in its issue so nobody else starts the same work.

The repository

github.com/ludovic111/horizon holds the game, the launcher and this website, plus the tools, tests and docs that build, check and release them.

• crates/ is the game, as Rust crates: the client, the server, the world and protocol code, the mod system, the shader pack reader, the design tokens and more.
• launcher/ is the launcher, a GPUI app with its own Cargo workspace.
• website/ is this site and its documentation, in website/docs/.
• tools/ holds the parity harness drivers, the parity runner, the release tools and the self-check.
• tests/ holds the Python tests, benchmarks/ the published results and packaging/ the installers.
• docs/ holds the developer documentation, indexed here: the native client, the design system, world generation, the parity workflow, the release flow and more.

Build it

You need Rust (stable), Python 3.10 or newer, JDK 25 and, on Linux, the ALSA and udev headers (libasound2-dev libudev-dev). Horizon never downloads the game: it prepares its resources from your own copy of Minecraft 26.3.

git clone https://github.com/ludovic111/horizon.git
cd horizon
cargo run --release -p horizon-prepare -- --prepare --server-jar ~/Downloads/server.jar
cargo run --release -p horizon-client

Everything prepared lands in the git-ignored .local/. It is derived from the game: never commit it or share it. The launcher is its own workspace: cd launcher && cargo run. The website builds with node build.mjs in website/.

Parity harnesses

A harness is a tools/test_*_parity.py script. It drives the same inputs through Horizon and through the vanilla client and server bytecode from your own copy of the game, and checks that the outputs are identical. There are 281 in the audit.

• Read the vanilla code before writing Horizon's. tools/rea_vanilla.py queries the pinned game bytecode, for example python3 tools/rea_vanilla.py method net.minecraft.world.level.block.DispenserBlock dispenseFrom. Say in your pull request which vanilla classes and methods you followed.
• Gameplay changes come with a harness, new or extended, so the next change cannot silently break them. Copy a nearby one.
• python3 tools/parity.py runs the harnesses a change can affect. The parity workflow explains the rest.
• Horizon's own features (the launcher, the new menus) follow the design system and stay off by default wherever they would change the vanilla look.
• Everything players run is Rust. Python and Java are fine for dev tools and harness drivers, never for player-facing code.

How pull requests are checked

1. Self-check first. Run python3 tools/pr_ready.py and paste the block it prints into your pull request. It runs rustfmt, clippy with warnings denied, the tests of the crates you touched, the Python tests, the public-tree check and the harnesses your change can affect.
2. verify runs on every pull request on GitHub's Linux runners: the same checks, without the vanilla harnesses. Docs-only changes finish in seconds.
3. parity runs the affected harnesses on a maintainer's computer, which holds the game files. It never runs a fork's code on its own: a maintainer reads the change, then adds the run-parity label, which runs it once on your current commit.
4. Small pull requests. One change each, under about 500 lines of code where you can. They get reviewed and merged the same day.
5. Labels. feature when players get something new, skip-release when they see no change, nothing for a fix. We set them if you cannot.
6. "Allow edits by maintainers." Tick it. When something small is left, we push the fix ourselves instead of sending you back.

Every merge to main that players can see is released automatically, so main always stays playable. See the release flow.

What never goes in

Never commit game files, decompiled source or prepared resources. tools/check_public_tree.py rejects them, and git config core.hooksPath .githooks runs it before every commit. Tracked Java is allowed only under the project's own dev/horizonlab namespace.

CONTRIBUTING.md is the short version of this page, and the contributors are listed on the home page.