mirror of
https://github.com/horizon-rust/horizon.git
synced 2026-11-11 23:55:37 -10:00
Nikita Maximilian GrimmandClaude Fable 5.2
9188926fff
A 0.2 pack can't show a colour outside sRGB today: the contract says every colour is in BT.709 primaries, forever. This adds the key that will let a pack ask for more, before 0.2 is on by default and packs are written against that contract. - `[frame] primaries = "bt709"` (the default) or `"bt2020"`. The check takes `"bt2020"` only with `blend = "linear"`, since a change of primaries is only right in linear light. The game refuses a `"bt2020"` pack for now, as it refuses `blend = "linear"`. - `Frame` gains `primaries` and `luminance` (that space's luminance weights) after `black_level`. The renderer writes 0 and BT.709's weights. The uploaded buffer grows by 16 bytes; 0.1 declares the same prefix as before. - The reference's "Room to grow" says a later release adds a name to a stage's prelude only under a manifest key the pack sets or in a new stage. `tests/names.rs` holds each 0.2 prelude to its list of names (`tests/names-0.2/`), and shows why: a pack's own `fn depth_at` in a post stage is refused as a redefinition, its own `fn to_bt709` passes. No pack's picture changes: a pack without the key, a `"bt709"` pack and 0.1 packs draw as before. Part of #14584 (step 1) and #12989. Co-Authored-By: Claude Fable 5.2 <[email protected]>
Horizon APIs
Horizon has eight surfaces that other programs and people build on. Each one has an API (the contract: what you may call, read or write, and what Horizon promises about it) and an SDK (the tools that help you use it). This section has one page per surface, plus the rules every surface follows: stability and versioning.
| Surface | For | API today | Stability | Reference |
|---|---|---|---|---|
| Mods | mod authors | content mods: manifest api 0.2; native mods: a horizon-mixins bundle (native-mods.md) |
preview (content), experimental (native) | mods.md |
| Shaders | shader authors | API 0.1 (sky, vertex, material, weather and post stages, coloured block light, options, hot reload) | experimental | shaders-reference.md |
| Agent control | agents, scripts, tests | horizon-ctl, its MCP server, the game's control socket |
preview | horizon-ctl-commands.md (generated) |
| Servers | hosts, panels, bots | horizon-server commands, server.toml, control API /api/v1 |
stable | server-reference.md (generated) |
| Launcher | players' agents, pack makers | horizon-launcher commands and its MCP server |
preview | launcher-commands.md (generated) |
| Launch | other launchers | horizon-client's launch options, the session JSON, exit codes; horizon-prepare's output, --check and --progress json |
experimental | launch-reference.md (generated) |
| Content | other launchers | where each kind of content goes, turning it on and off, the checks before installing; content in horizon-client --launch-api |
experimental | mod-index.md |
| Data formats | tools that read Horizon's files | benchmark reports, telemetry, settings files, signed checksums | stable or preview, per format | on that page |
How these APIs are designed
- From the people who use them. Each API starts from what a mod author, a pack author, a server host or an agent needs to do, written down as tasks ("a host backs up the world from a script"), and from how Horizon is built: Rust, wgpu and a server thread that runs every world. A function exists because a task needs it.
- Our own design. Horizon's APIs are not modelled on any other project's. Contributors may know other mod
loaders, renderers and server platforms exist, but their source and API references are never read, copied or
paraphrased here, and our names, shapes and docs are not taken from theirs. Vanilla Minecraft 26.3 is the reference for game
concepts: ids, commands,
server.properties, data packs and resource packs. - Safe by default. A content mod is data and runs no code; a native mod runs with the player's rights, so it is off by default, behind a warning and reviewed before the registry lists it; the control sockets listen on this computer only, behind a token; nothing here is on by default where it would change vanilla's look or behaviour.
- Free when unused. An API nobody uses costs nothing per tick or per frame: no engine, no thread, no allocation.
- One contract for every mode. In-frame single player, the server thread, LAN and the dedicated server run the same gameplay code (AGENTS.md), so a server-side API serves all of them.
References are generated
A reference page is written by code from the source it describes, and a test fails when the two differ:
| Page | Generated from | Update it with |
|---|---|---|
| server-reference.md | horizon-server's help, config::TEMPLATE, api::ROUTES |
HORIZON_WRITE_DOCS=1 cargo test -p horizon-server reference |
| horizon-ctl-commands.md | the command table in crates/horizon-client/src/bin/horizon-ctl/commands.rs |
horizon-ctl help --markdown > docs/horizon-ctl-commands.md |
| launcher-commands.md | launcher/src/cli.rs |
HORIZON_WRITE_DOCS=1 cargo test --manifest-path launcher/Cargo.toml the_launcher_reference |
| launch-reference.md | crates/horizon-client/src/game/launch_api.rs |
HORIZON_WRITE_DOCS=1 cargo test -p horizon-client --lib launch_api |
So a pull request that changes an API also changes its reference, and the reviewer sees the API's diff in the reference's diff. The guides (overview, how-to, examples) are written by hand.
Each surface's page
Every page has the same parts: Overview (what you can build), Guide (where to start), Reference, Examples, Stability (the level of each part, per stability.md), Changelog and Not there yet (what is planned, so nobody builds on a guess).
The website shows these pages at playhorizon.dev/docs/api, built from this folder, and a summary for players and authors at playhorizon.dev/docs/apis (in the website's repository, horizon-rust/horizon-site).