Ludovic Marie
e5bfce3b37
docs/api/mods.md gets "Ways in": one API (the WIT world) and one sandbox (WebAssembly) for every language. Rust is first-class; Lua scripts are planned, run by an interpreter that is itself a WebAssembly mod linked with the script's capabilities only, with hot reload of the script; C, C++, Zig, TinyGo, AssemblyScript and JavaScript/TypeScript are to be evaluated, each listed with its cost measured against Rust. Server mods are their own line (api 0.3); block entities are no longer tied to a draft. Promotion to stable: the orchestrator proposes with the evidence, Ludovic approves. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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. Lua scripts, run in the same sandbox, are planned | 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.