Files
horizon-airdef/docs/api
Ludovic Marie 7bffc4c670 cargo horizon-mod test: run a mod's TOML test scripts headless
A mod's tests/<name>.toml scripts run in the sandbox the game uses, with no game
and no window. The runner plays the game's part (the player and clock the mod
reads, ticks, frames, chat lines, commands, a reload) and each step checks what
the mod did: its commands, chat lines, command feedback and errors, HUD panel
and corner, or that it was turned off. A failing step names itself and prints
expected against got. Each script runs on a scratch copy, so storage starts
empty and is removed afterwards.

horizon_mods::testing (feature runtime) holds TestGame and Script; the cargo
subcommand builds the mod (or takes --hmod), filters scripts by name, and fails
when one does. The template gains tests/hello.toml, coords-hud gains panel and
where scripts, and the sandbox tests run the example's scripts and check the
runner's failures, reload and expected stops. Scripts don't care what language
the mod is written in, so script mods (Lua) get the same runner.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 15:25:52 +01:00
..

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.

Surface For API today Stability Reference
Mods mod authors WIT horizon:mods@0.1.0, manifest api 0.1 (code) and 0.2 (content) preview mods-reference.md (generated)
Shaders shader authors none yet: packs were removed on 2026-10-24 planned none
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)
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, 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), 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 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 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

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's summary for players and authors is playhorizon.dev/docs/apis (website/docs/apis.md).