Ludovic Marie
0a1d3a7534
docs/api/ gets one page per surface other programs build on (mods, shaders, agent control, servers, the launcher, data formats), each with an overview measured from the source, the guide, the generated reference, examples, its stability, what is not there yet and a changelog, plus the policy every API follows (docs/api/stability.md): a version per API, semver lines, experimental / preview / stable, deprecation windows, compatibility tests and the level of every part today. The website gets a "Build on Horizon" page (website/docs/apis.md) that summarises them and links the repository's pages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
56 lines
4.3 KiB
Markdown
56 lines
4.3 KiB
Markdown
# Horizon APIs
|
|
|
|
Horizon has six 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](stability.md).
|
|
|
|
| Surface | For | API today | Stability | Reference |
|
|
| --- | --- | --- | --- | --- |
|
|
| [Mods](mods.md) | mod authors | WIT `horizon:mods@0.1.0`, manifest `api` 0.1 (code) and 0.2 (content) | preview | [mods-reference.md](mods-reference.md) (generated) |
|
|
| [Shaders](shaders.md) | shader authors | none yet: packs were removed on 2026-10-24 | planned | none |
|
|
| [Agent control](agent-control.md) | agents, scripts, tests | `horizon-ctl`, its MCP server, the game's control socket | preview | [horizon-ctl-commands.md](../horizon-ctl-commands.md) (generated) |
|
|
| [Servers](server.md) | hosts, panels, bots | `horizon-server` commands, `server.toml`, control API `/api/v1` | stable | [server-reference.md](server-reference.md) (generated) |
|
|
| [Launcher](launcher.md) | players' agents, pack makers | `horizon-launcher` commands and its MCP server | preview | [launcher-commands.md](../launcher-commands.md) (generated) |
|
|
| [Data formats](data-formats.md) | 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, WebAssembly components 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.** Mods run in a sandbox and can only use the capabilities their manifest declares; 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](../../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 |
|
|
| --- | --- | --- |
|
|
| [mods-reference.md](mods-reference.md) | `crates/horizon-mod-sdk/wit/horizon.wit`, the manifest's capabilities | `HORIZON_WRITE_DOCS=1 cargo test -p horizon-mods --features pack --test api_reference` |
|
|
| [server-reference.md](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](../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-commands.md) | `launcher/src/cli.rs` | `HORIZON_WRITE_DOCS=1 cargo test --manifest-path launcher/Cargo.toml the_launcher_reference` |
|
|
|
|
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](stability.md)), **Changelog** and
|
|
**Not there yet** (what is planned, so nobody builds on a guess).
|
|
|
|
The website's summary for players and authors is [playhorizon.dev/docs/apis](https://playhorizon.dev/docs/apis)
|
|
(`website/docs/apis.md`).
|