Files
horizon-airdef/website/docs/apis.md
T
Ludovic Marie 0a1d3a7534 Horizon APIs: the docs portal and the stability and versioning policy
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>
2026-10-24 20:50:20 +02:00

3.0 KiB

Horizon's APIs

Horizon is built to be built on. Mods, shaders, agents, server panels, launchers' scripts and tools all get a documented API with a version, a stability level and a reference generated from the code, so it never says something the game doesn't do.

What you can build on

Surface For Today Stability
Mods mod authors Rust compiled to sandboxed WebAssembly: read the player and the clock, chat, a HUD panel, storage, commands, tick and frame hooks; data-driven blocks and items preview
Shaders shader authors a new shader API in WGSL is being designed: stages with typed inputs, options, reload on save, a debug overlay planned
Agent control AI agents, scripts, tests horizon-ctl and its MCP server: 96 commands to watch and play the game preview
Servers hosts, panels, bots horizon-server's commands, server.toml and a local HTTP control API stable
Launcher your agent, pack makers horizon-launcher's 46 commands and its MCP server preview
Data formats tools that read Horizon's files benchmark reports, telemetry, settings, release checksums; worlds are vanilla's format per format

The full pages, one per surface, are in the repository: docs/api. Mods for players: Mods. Agents: Control Horizon with your AI agent. Hosting: Host a server.

What the levels mean

  • Stable: only additions within a major version. A change that would break you comes as a new major, served beside the old one for at least 180 days.
  • Preview: documented and tested. It may change at a new line (0.1 to 0.2), after a deprecation of at least 30 days during which old and new both work.
  • Experimental: opt-in only, and it may change in any release.

Every API has its own version (the mod API is horizon:mods@0.1.0, the server's control API is /api/v1), separate from the game's release number. The whole policy: stability and versioning.

How they are designed

Each API starts from what its users need to do, and from how Horizon is built: Rust, wgpu, WebAssembly and a server thread that runs every world. Horizon's APIs are its own: they are not modelled on another mod loader's, renderer's or server platform's. Vanilla Minecraft 26.3 is the reference for game concepts such as ids, commands and data packs.

They are safe by default (mods run in a sandbox with the permissions you allow; control sockets only listen on your computer, behind a token) and cost nothing when unused.

References that can't drift

Each reference is written by code from the source it describes, and a test fails when the two differ: the mod API from its WIT contract, horizon-ctl and the launcher from their command tables, the server from its settings template and route table. A change to an API changes its reference in the same pull request.