Ludovic Marie
a13e6b40ce
/docs has a left navigation and eleven pages written for players first, then hosters, then contributors: what Horizon is, install, settings, multiplayer, logs and bug reports, hosting (the launcher's Servers page and the command line), modpacks, mods and data packs, performance, contributing and the FAQ. /server redirects to /docs/hosting. The build checks every link between the pages and every image. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
57 lines
5.0 KiB
Markdown
57 lines
5.0 KiB
Markdown
# Contribute
|
|
|
|
Horizon is open source and takes pull requests. The one rule that shapes everything: **it plays exactly like vanilla.** Wherever vanilla has a feature, vanilla is the specification.
|
|
|
|
Questions and ideas are welcome on [Discord](https://discord.gg/HcTeMZxe5E). Bugs and feature requests go in [GitHub issues](https://github.com/ludovic111/horizon/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](https://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](https://github.com/ludovic111/horizon/blob/main/docs/README.md): 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.
|
|
|
|
```sh
|
|
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 {{HARNESSES}} 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](https://github.com/ludovic111/horizon/blob/main/docs/parity-workflow.md) explains the rest.
|
|
- Horizon's own features (the launcher, the new menus) follow [the design system](https://github.com/ludovic111/horizon/blob/main/docs/design-system.md) 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](https://github.com/ludovic111/horizon/blob/main/docs/release-flow.md).
|
|
|
|
## 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](https://github.com/ludovic111/horizon/blob/main/CONTRIBUTING.md) is the short version of this page, and the [contributors](/#contributors) are listed on the home page.
|