Merge pull request #1583 from ludovic111/docs/platform-apis
This commit is contained in:
@@ -20,6 +20,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
|
||||
- [Resource packs](resource-packs.md): everything a 26.3 resource pack can change, whether Horizon honours it, and the proof.
|
||||
- [Opt-in data collection](telemetry.md): the consent, exactly what is sent, how it is stored and sent.
|
||||
- [Benchmark report format](benchmark-report.md): the versioned JSON every benchmark writes (game, launcher, `tools/perf_bench.py`), the local log and, with consent, the upload.
|
||||
- [Horizon APIs](api/README.md): every surface other programs build on (mods, shaders, agent control, servers, the launcher, data formats), each with its guide, generated reference, stability and changelog, and the [stability and versioning policy](api/stability.md).
|
||||
- Menus: every screen is vanilla's (title, world list, create world, multiplayer, options, pause). Horizon's own settings hang off vanilla's Options the way mods add theirs: **Horizon Settings...** and **Mods...** in the last two slots of the Options grid (Horizon Settings opens Graphics, Advanced Graphics, Controller Settings, Extras and Mods, each a vanilla options list), with Horizon Graphics and Advanced Graphics also at the top of Video Settings and Controller Settings at the bottom of Controls. The title screen's and pause menu's Friends buttons open Join a Friend and Play with Friends ([play-with-friends.md](play-with-friends.md)).
|
||||
|
||||
## Parity
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# 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`).
|
||||
@@ -0,0 +1,55 @@
|
||||
# Agent control API
|
||||
|
||||
How a program drives a running game: an AI agent through MCP, a script through `horizon-ctl`, a test through the
|
||||
control socket. Design and inventory: [agent-control.md](../agent-control.md); for players:
|
||||
[playhorizon.dev/docs/agents](https://playhorizon.dev/docs/agents).
|
||||
|
||||
## Overview
|
||||
|
||||
The game listens on a local control socket (a Unix socket, or localhost TCP with a token on Windows), takes one
|
||||
command per text line and answers one JSON line. `horizon-ctl` wraps it: it starts the game, sends commands and
|
||||
serves the same commands as MCP tools. The launcher's MCP server offers them too, as `game_<tool>`.
|
||||
|
||||
| | Count |
|
||||
| --- | --- |
|
||||
| `horizon-ctl` commands | 96, in 8 groups (session, observe, move and look, act, screens and chat, multiplayer, world and cheats, scripting and benchmarks) |
|
||||
| MCP tools | 88 (8 commands are CLI only) |
|
||||
| Destructive commands (need `--confirm`) | 3 |
|
||||
| Command names the game's socket answers | about 160, test hooks included (`horizon-ctl help --game`) |
|
||||
|
||||
## Guide
|
||||
|
||||
1. Build `horizon-ctl` (`cargo build --profile fast -p horizon-client`), then
|
||||
`horizon-ctl --socket $PWD/ctl.sock launch --world W --creative --wait --resources <prepared files>`.
|
||||
2. `horizon-ctl --socket … state`, `keys`, `turn`, `command`, `screenshot`, `quit`.
|
||||
3. For an agent: `horizon-ctl mcp`, or the launcher's `horizon-launcher mcp` with `agent-config` to connect a client
|
||||
([launcher-commands.md](../launcher-commands.md)).
|
||||
|
||||
## Reference
|
||||
|
||||
[horizon-ctl-commands.md](../horizon-ctl-commands.md), generated from the command table in
|
||||
`crates/horizon-client/src/bin/horizon-ctl/commands.rs`: every command, its MCP tool and its arguments.
|
||||
|
||||
## Examples
|
||||
|
||||
- `tools/agent_control_e2e.py`: starts a game and drives it end to end through `horizon-ctl` and MCP.
|
||||
- `tools/lan_e2e.py`: two games over LAN, both driven through their sockets.
|
||||
|
||||
## Stability
|
||||
|
||||
Preview ([stability.md](stability.md)). The commands in `horizon-ctl`'s table and their MCP tool names are what the
|
||||
API offers; the other commands the game's socket answers are test hooks and experimental.
|
||||
|
||||
## Not there yet
|
||||
|
||||
- **A version.** A `hello` command that answers the protocol version, the game's release and the features it has;
|
||||
MCP `serverInfo` carries the same version; `horizon-ctl` refuses a game whose major it doesn't speak.
|
||||
- **Reply schemas.** Each command's reply described in the table (fields, types, units), so the reference documents
|
||||
replies as well as arguments and MCP tools declare an output schema.
|
||||
- **Events as a stream.** `events --since` polls today; a subscription that pushes events as they happen.
|
||||
- **Test hooks apart.** The hooks only harnesses use move under their own prefix, out of the agent's tool list.
|
||||
- **Compatibility tests.** A transcript per protocol version: commands and the reply keys each must keep.
|
||||
|
||||
## Changelog
|
||||
|
||||
- Unversioned so far: the command table and the generated reference are the contract.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Data formats
|
||||
|
||||
The files Horizon writes that other tools may read: benchmark reports, telemetry, settings, mods, release checksums
|
||||
and worlds. Each entry names its version field, its documentation and its level ([stability.md](stability.md)).
|
||||
|
||||
## Overview
|
||||
|
||||
| Format | Where | Version | Level | Documented in |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Benchmark report | the benchmark's output, the local log, uploads | `"format": "horizon-benchmark-report"`, `"version": 1` | stable | [benchmark-report.md](../benchmark-report.md) |
|
||||
| Telemetry batch | `POST /v1/batch` from the launcher | `"schema": 1` | stable | [telemetry.md](../telemetry.md) |
|
||||
| Telemetry consent | `telemetry/consent.json` in the game folder | `"version": 2` | stable | [telemetry.md](../telemetry.md) |
|
||||
| Mod package | `.hmod`: a zip with `horizon-mod.toml`, `mod.wasm`, `assets/`, `data/` | the manifest's `api` | preview | [mods.md](../mods.md#the-manifest), [mods-reference.md](mods-reference.md) |
|
||||
| Mods turned on | `horizon-mods.txt` | none | preview | [mods.md](../mods.md#playing-with-mods) |
|
||||
| Horizon settings | `horizon-graphics.txt`, `horizon-extras.txt` (`key:value`, as `options.txt`) | none: unknown keys fall back to defaults | preview | [graphics.md](../graphics.md), [extras.md](../extras.md#options-storage) |
|
||||
| Server settings | `server.toml` | its keys | stable | [server-reference.md](server-reference.md) |
|
||||
| Control endpoints | the game's socket file (TCP form), `.horizon/api.json` | none | preview | [agent-control.md](agent-control.md), [server-reference.md](server-reference.md) |
|
||||
| Release checksums | `SHA256SUMS`, `SHA256SUMS.sig` on releases since signing began (#1011) | the signed text names the tag | stable | [security.md](../security.md) |
|
||||
| Worlds | the world folder | vanilla 26.3's (`DataVersion`) | vanilla's | [world-data.md](../world-data.md) |
|
||||
|
||||
Worlds are vanilla's format, so any tool that reads a 26.3 world reads a Horizon world; Horizon adds itself to
|
||||
`level.dat`'s `ServerBrands` as vanilla's server does.
|
||||
|
||||
## Rules for every format
|
||||
|
||||
- A reader ignores fields it doesn't know, and refuses a version newer than it knows with a clear message.
|
||||
- An optional field may be added in the same version; renaming, removing or changing the meaning of a field makes the
|
||||
next version, and Horizon's own readers keep reading the older ones for the deprecation window.
|
||||
- Each versioned format has a sample file of every version its reader accepts, read by a test.
|
||||
|
||||
## Not there yet
|
||||
|
||||
- Versions for the settings files and the control endpoint files (a `version` line or field).
|
||||
- Sample files and reader tests for every versioned format.
|
||||
- A generated schema for the benchmark report and the telemetry batch from their Rust types, checked by a test like
|
||||
the references.
|
||||
|
||||
## Changelog
|
||||
|
||||
- Benchmark report version 1; telemetry schema 1, consent version 2.
|
||||
@@ -0,0 +1,57 @@
|
||||
# Launcher API
|
||||
|
||||
What a player's agent, a script or a pack maker can do with `horizon-launcher`: install and run versions, manage
|
||||
accounts, settings, mods, modpacks and hosted servers, from a terminal or over MCP. The launcher itself:
|
||||
[launcher/README.md](../../launcher/README.md).
|
||||
|
||||
## Overview
|
||||
|
||||
Every page of the launcher has a command, and every command but three has an MCP tool with the same arguments; a tool
|
||||
runs the command with `--json`. Tools that change the player's things for good need `confirm: true`; with No AI on,
|
||||
the MCP server is off.
|
||||
|
||||
| | Count |
|
||||
| --- | --- |
|
||||
| Commands | 46: versions, installs, play, the server, notes, links, accounts, settings, logs, updates, data collection, modpacks, mods, hosted servers, MCP, benchmark |
|
||||
| MCP tools | 43, plus the game's tools as `game_<tool>` ([agent-control.md](agent-control.md)) |
|
||||
| Modpack formats it imports | 3: a Modrinth `.mrpack`, a CurseForge zip, an instance folder |
|
||||
|
||||
## Guide
|
||||
|
||||
1. `horizon-launcher versions`, `horizon-launcher install latest`, `horizon-launcher play`.
|
||||
2. Modpacks: `horizon-launcher modpack import <file>`, then `modpack port` and `modpack play`
|
||||
([modpacks.md](../modpacks.md)).
|
||||
3. For an agent: `horizon-launcher agent-config` prints how to connect a client to `horizon-launcher mcp`.
|
||||
|
||||
## Reference
|
||||
|
||||
[launcher-commands.md](../launcher-commands.md), generated from `launcher/src/cli.rs`: every command, its arguments
|
||||
and its MCP tool.
|
||||
|
||||
## Examples
|
||||
|
||||
```sh
|
||||
horizon-launcher versions --installed --json
|
||||
horizon-launcher mods search minimap --kind mod --json
|
||||
horizon-launcher servers create --name "Weekend" --player Alex --json
|
||||
```
|
||||
|
||||
## Stability
|
||||
|
||||
Preview ([stability.md](stability.md)): command names, arguments and MCP tool names are the contract; `--json`
|
||||
output shapes are not yet described in the reference.
|
||||
|
||||
## Not there yet
|
||||
|
||||
- **A Horizon modpack manifest.** A pack made for Horizon (not a port of a Java pack) needs its own file: the pack's
|
||||
id, name and version; the Horizon API lines and the release line it needs; its `.hmod` mods (id, version, SHA-256,
|
||||
where to download it, client, server or both); resource packs; default settings; and whether it has a server side.
|
||||
One manifest serves the launcher, `horizon-server` (a server installs the server side of the same pack) and the mod
|
||||
browser. Designed from what a pack maker does, versioned per [stability.md](stability.md), with a schema test.
|
||||
- **JSON output schemas** for every command, in the generated reference, so MCP tools declare their output.
|
||||
- **A version** in MCP `serverInfo` and `--json` output, as for agent control.
|
||||
- **Compatibility tests**: golden `--json` output per command.
|
||||
|
||||
## Changelog
|
||||
|
||||
- Unversioned so far: the command table and the generated reference are the contract.
|
||||
@@ -0,0 +1,99 @@
|
||||
# Mod API
|
||||
|
||||
Mods are Rust crates compiled to sandboxed WebAssembly components. They run in the player's game and, once server
|
||||
mods land, wherever a world is simulated. Design and the runtime: [mods.md](../mods.md).
|
||||
|
||||
## Overview
|
||||
|
||||
A mod today can read the local player and the world clock, show chat lines only that player sees, draw a text panel
|
||||
on the HUD, keep small files of its own, register chat commands, and run on every tick, frame or chat line it asks
|
||||
for. A content mod adds blocks and items from JSON in its `.hmod`, copying vanilla templates, plus tags, recipes,
|
||||
loot, models, textures and structures in its own namespaces. Every capability is declared in the manifest, shown to
|
||||
the player before the mod is turned on, and checked against the component's real imports.
|
||||
|
||||
| | Count |
|
||||
| --- | --- |
|
||||
| Interfaces the game offers | 5: `log`, `game`, `chat`, `hud`, `storage` |
|
||||
| Functions in them | 9 |
|
||||
| Hooks a mod exports | 5: `init`, `tick`, `frame`, `command`, `chat` |
|
||||
| Capabilities | 5: `game-read`, `chat`, `hud`, `storage`, `registries` |
|
||||
| Manifest `api` lines served | 2: `0.1` (code), `0.2` (content) |
|
||||
| SDK | the `Mod` trait (5 methods), `Registration` (4 builders), `export_mod!`, log helpers |
|
||||
| `cargo horizon-mod` | `new`, `build`, `run` |
|
||||
| Example mods | `coords-hud` (code), `ruby-content` (content) |
|
||||
|
||||
## Guide
|
||||
|
||||
1. `rustup target add wasm32-unknown-unknown`, `cargo install --git https://github.com/ludovic111/horizon
|
||||
cargo-horizon-mod`, then `cargo horizon-mod new my-mod` ([Making a mod](../mods.md#making-a-mod)).
|
||||
2. Implement `Mod` for your type, list the capabilities you import in `horizon-mod.toml`
|
||||
([The manifest](../mods.md#the-manifest)).
|
||||
3. `cargo horizon-mod run` builds the `.hmod` and starts the game with it as a dev mod; after an edit,
|
||||
`cargo horizon-mod build` and the running game reloads it.
|
||||
4. Content mods: [Content mods (API 0.2)](../mods.md#content-mods-api-02).
|
||||
|
||||
## Reference
|
||||
|
||||
[mods-reference.md](mods-reference.md), generated from `crates/horizon-mod-sdk/wit/horizon.wit`: every capability,
|
||||
interface, type, function and hook, with the limits the guide lists (16 HUD lines of 256 characters, 8 chat lines per
|
||||
call, 4 MiB of storage, fuel per call).
|
||||
|
||||
## Examples
|
||||
|
||||
- `crates/horizon-mod-sdk/examples/coords-hud`: coordinates, facing and time on the HUD; `/where`, `/coords`; storage.
|
||||
- `crates/horizon-mod-sdk/examples/ruby-content`: no code; a gem and a block of ruby from vanilla templates, with
|
||||
their recipes, loot, tags, models, textures and names.
|
||||
- `crates/horizon-mods/tests/guest`: a mod that misbehaves on command (spins, panics, grows its memory), for the
|
||||
sandbox tests.
|
||||
|
||||
## Ways in
|
||||
|
||||
One API (the WIT world) and one sandbox (WebAssembly), whatever the mod is written in. Every way in produces a
|
||||
component for the same world, checked against the same capabilities and given the same limits; there is no second
|
||||
scripting runtime in the game.
|
||||
|
||||
| Way in | For | Status | Template and example |
|
||||
| --- | --- | --- | --- |
|
||||
| Rust | most mods; the fastest | first-class: the SDK, `cargo horizon-mod` | `cargo horizon-mod new`, `coords-hud` |
|
||||
| Lua scripts | people who don't want a compiler | planned: a script mod whose code is a `.lua` file, run by Horizon's own interpreter mod | planned, with the same example as Rust |
|
||||
| C, C++, Zig | authors of those languages | to evaluate: bindings generated from the WIT, built without WASI | one each if it passes |
|
||||
| Go (TinyGo), AssemblyScript, JavaScript / TypeScript | authors of those languages | to evaluate: each needs its toolchain to emit a component without WASI imports, or an interpreter mod as for Lua | one each if it passes |
|
||||
|
||||
- **Scripts run inside the sandbox.** The Lua interpreter is itself a WebAssembly mod, built in Rust with the SDK and
|
||||
shipped by Horizon. A script mod's manifest names the interpreter and its own capabilities; the game links the
|
||||
interpreter with only those, so a script can do exactly what a compiled mod with the same manifest can.
|
||||
- **Hot reload.** The game keeps the interpreter compiled and loads the script into a fresh instance when the file
|
||||
changes, without restarting the game; what it saved with `storage` survives, as for dev mods.
|
||||
- **Measured, not guessed.** Each way in is listed with its measured cost on the same tick-heavy example (time and
|
||||
fuel per tick, memory, load time) against Rust, and a language is supported only with a template, an example and a
|
||||
test that builds and loads it in CI.
|
||||
|
||||
## Stability
|
||||
|
||||
Preview ([stability.md](stability.md)): API 0.1 and content 0.2 are served together; a mod built for 0.1.0 keeps
|
||||
loading on every 0.1.x game. Server mods come as their own line, `api = "0.3"`, experimental first.
|
||||
|
||||
## Not there yet
|
||||
|
||||
What real mods need next, in the order modpacks and servers need it:
|
||||
|
||||
- **Server mods** (`api = "0.3"`): the same component running on the server thread and the dedicated server, with world events (block
|
||||
broken or placed, entity spawned or killed, player joined or left), game rules and server commands with typed
|
||||
arguments.
|
||||
- **World and blocks**: read blocks, block states and biomes in loaded chunks; change them through the server's block
|
||||
log, so clients and the parity harnesses see vanilla's updates.
|
||||
- **Items and inventories**: the player's inventory, held item and open container; item stacks with components.
|
||||
- **Entities**: query and change entities near a position; spawn from a mod's own entity types (data first).
|
||||
- **Block entities and menus**: ticking machines with slots and their screens.
|
||||
- **Screens and UI**: widgets built from vanilla's, a screen the mod owns, a settings page under Options > Mods.
|
||||
- **Networking**: a channel between a mod's two halves, client and server, typed by the mod's own WIT.
|
||||
- **Config**: typed settings the game shows and stores for the mod, on the server too.
|
||||
- **Keys and the crosshair target**: keybinds in Controls; what the player is looking at.
|
||||
- **Script mods and other languages**: see [Ways in](#ways-in).
|
||||
- **SDK**: a headless test runner (load a mod, feed it ticks and events, assert on its output, no window), templates
|
||||
per kind of mod, typed wrappers in the SDK for every interface. Dev mods already reload when rebuilt.
|
||||
|
||||
## Changelog
|
||||
|
||||
- API 0.2 (content): data-driven blocks and items, tags, `horizon:add_to`, terrain adaptation.
|
||||
- API 0.1.0: `log`, `game`, `chat`, `hud`, `storage`; `init`, `tick`, `frame`, `command`, `chat`.
|
||||
@@ -0,0 +1,60 @@
|
||||
# Server API
|
||||
|
||||
What a host, a panel or a bot can do with a Horizon server: the `horizon-server` commands, `server.toml` and the
|
||||
control API. How to host: [hosting.md](../hosting.md); the design: [server.md](../server.md).
|
||||
|
||||
## Overview
|
||||
|
||||
`horizon-server` sets up a server folder, runs the game as a dedicated server under a supervisor (restarts on a crash,
|
||||
backups on a schedule, updates with a rollback), and lets other programs manage it through a local HTTP API with a
|
||||
token. The web panel uses that API.
|
||||
|
||||
| | Count |
|
||||
| --- | --- |
|
||||
| Commands | 22 (`init`, `run`, `start`, `stop`, `restart`, `status`, `cmd`, `logs`, `backup`, `backups`, `restore`, `service`, `panel`, `update`, `rollback`, `config`, `config set`, `import`, `op`, `deop`, `whitelist`, `version`) |
|
||||
| `server.toml` keys | 22 in 6 sections, plus `[properties]` for any other vanilla key |
|
||||
| Control API endpoints | 11 under `/api/v1` |
|
||||
|
||||
## Guide
|
||||
|
||||
1. `horizon-server init` in an empty folder, then `horizon-server start` ([hosting.md](../hosting.md)).
|
||||
2. From a script: `horizon-server status --json`, `horizon-server cmd say hi`, `horizon-server backup`.
|
||||
3. From a program: read `.horizon/api.json` (address and token), then `GET /api/v1/status` with
|
||||
`Authorization: Bearer <token>`.
|
||||
|
||||
## Reference
|
||||
|
||||
[server-reference.md](server-reference.md), generated from `horizon-server`'s source: the help text, every
|
||||
`server.toml` key with its default and the `server.properties` key it writes, and every endpoint.
|
||||
|
||||
## Examples
|
||||
|
||||
```sh
|
||||
token=$(jq -r .token .horizon/api.json); address=$(jq -r .address .horizon/api.json)
|
||||
curl -s -H "Authorization: Bearer $token" "http://$address/api/v1/status"
|
||||
curl -s -H "Authorization: Bearer $token" -d '{"line": "list"}' "http://$address/api/v1/command"
|
||||
```
|
||||
|
||||
## Stability
|
||||
|
||||
Stable ([stability.md](stability.md)): the commands, `server.toml`'s keys and `/api/v1`. A new key or endpoint is an
|
||||
addition; a change to one starts `/api/v2`, served beside `/api/v1`.
|
||||
|
||||
## Not there yet
|
||||
|
||||
- **Players**: list with ping and position, kick, ban and pardon, op and deop, the whitelist, as endpoints (today only
|
||||
through `cmd` and the files).
|
||||
- **Console stream**: the log as a stream (server-sent events) rather than `logs?since=N` polling; chat, joins, leaves,
|
||||
deaths and crashes as typed events.
|
||||
- **Metrics**: a plain-text metrics endpoint any monitoring tool can scrape (TPS, MSPT percentiles, players, chunks,
|
||||
entities, RAM, CPU), from the samples `status` already takes.
|
||||
- **Backups**: delete and download one; restore a single dimension.
|
||||
- **Server mods**: list, turn on and off, and their settings, once the mod API runs on the server
|
||||
([mods.md](mods.md)).
|
||||
- **An MCP server** for the same endpoints, so a host's agent manages the server as it manages the game.
|
||||
- **Compatibility tests**: golden replies per endpoint, and a `server.toml` from each release line.
|
||||
|
||||
## Changelog
|
||||
|
||||
- `api::ROUTES` lists the endpoints; the reference is generated from it.
|
||||
- `/api/v1`: status, metrics, logs, command, stop, restart, backups, restore, update, panel login.
|
||||
@@ -0,0 +1,54 @@
|
||||
# Shader API
|
||||
|
||||
Horizon has no shader packs today: the earlier implementation was removed on 2026-10-24. Two things will replace it,
|
||||
designed separately: a **Horizon shader API**, described here, and a clean-room loader for the existing pack format
|
||||
(its own spec; it is not part of this API). Both sit on the same renderer hooks, agreed between the two.
|
||||
|
||||
## Overview: what a shader author will be able to do
|
||||
|
||||
Write WGSL against documented stages of Horizon's renderer, with typed inputs, options the player can change, a
|
||||
reload as soon as a file is saved and an overlay that shows what each pass costs and draws. The renderer keeps
|
||||
everything that makes it fast (culling, batching, LOD, the mesher); a pack changes how surfaces and light look, not
|
||||
how the world is fed to the GPU.
|
||||
|
||||
## The design
|
||||
|
||||
- **A pack** is a folder or a zip with `horizon-shaders.toml` (id, name, version, the `api` line, the stages it
|
||||
uses, its options) and WGSL files. No preprocessor and no other shading language: WGSL is what wgpu validates and
|
||||
compiles for Vulkan, Metal and DirectX 12.
|
||||
- **Stages, not pipelines.** A stage is a function with a fixed signature that the renderer calls inside its own pass,
|
||||
for example a terrain material (`fn material(input: TerrainInput) -> Surface`), the lighting of the visible
|
||||
surfaces, the sky, an optional shadow pass, and a chain of full-screen post passes ending in the frame. A pack
|
||||
that leaves a stage out gets vanilla's look for it.
|
||||
- **Typed inputs.** Each stage receives structs (the frame: time, camera, sun and moon, weather, fog; the surface:
|
||||
position, normal, block and its light) whose WGSL is generated from the Rust types the renderer uploads. The
|
||||
generated reference lists every field with its unit and range, and a test fails when it drifts.
|
||||
- **Options are WGSL `override` constants.** The manifest declares each option (on/off, a number in a range, a choice)
|
||||
with its default; the game shows them on the pack's settings screen and sets them when it builds the pipeline. No
|
||||
text substitution, and every option combination is validated the same way.
|
||||
- **Hot reload.** The game watches the pack's folder. A saved file is validated with naga and the stage rebuilt; on an
|
||||
error the last good version keeps drawing and the error, with its file and line, is shown in the overlay.
|
||||
- **Debug overlay.** GPU time per stage and pass (timestamp queries), the targets each pass writes (show any of them
|
||||
full-screen), the pack's options and its compile errors.
|
||||
- **Budgets.** A pack declares the targets and passes it needs; the renderer refuses more than its limits, and the
|
||||
benchmark ([benchmark-report.md](../benchmark-report.md)) records the pack and its cost, so "fast" stays measured.
|
||||
- **Off by default.** Without a pack the renderer is vanilla's look, and no pack code runs.
|
||||
|
||||
## Guide, reference and examples
|
||||
|
||||
None yet. When the first stage lands: a guide here, a generated reference (`shaders-reference.md`) and an example pack
|
||||
in the repository that the renderer's tests load.
|
||||
|
||||
## Stability
|
||||
|
||||
Not started. The first stages will be experimental (opt-in), then preview once a reference, an example and a test
|
||||
pack exist ([stability.md](stability.md)).
|
||||
|
||||
## Not there yet
|
||||
|
||||
Everything on this page. The order: the renderer hooks shared with the format loader, then the material and post
|
||||
stages with options and hot reload, then the overlay, lighting, sky and shadow stages.
|
||||
|
||||
## Changelog
|
||||
|
||||
- 2026-10-24: the earlier shader pack code was removed; this API is designed from scratch.
|
||||
@@ -0,0 +1,103 @@
|
||||
# API stability and versioning
|
||||
|
||||
The rules every Horizon API follows ([the APIs](README.md)): how each one is versioned, what the stability levels
|
||||
promise, how something is deprecated and removed, and the tests that keep old mods, scripts and tools working.
|
||||
|
||||
## Versions
|
||||
|
||||
- **Each API has its own version**, separate from the game's release (`v0.2.14`, [versioning.md](../versioning.md))
|
||||
and from Minecraft's. A game release says which API versions it serves.
|
||||
- **Semantic versioning**, `MAJOR.MINOR.PATCH`. A **line** is what stays compatible: `0.1`, `0.2`, … before 1.0,
|
||||
then `1`, `2`, ….
|
||||
- Before 1.0: an addition makes the next patch (`0.1.0` → `0.1.1`); a breaking change starts the next line
|
||||
(`0.2.0`).
|
||||
- From 1.0: an addition makes the next minor (`1.0` → `1.1`); a breaking change starts the next major (`2.0`).
|
||||
- **Where the version lives:**
|
||||
|
||||
| API | The version | A user names the line they need |
|
||||
| --- | --- | --- |
|
||||
| Mods | the WIT package (`horizon:mods@0.1.0`) | `api = "0.1"` in `horizon-mod.toml` |
|
||||
| Agent control | the control protocol's version (planned: a `hello` reply and MCP `serverInfo`) | `horizon-ctl --api 1` (planned) |
|
||||
| Server control API | the path (`/api/v1/`) | the path |
|
||||
| `server.toml` | the file's keys; a key is never renamed in place | nothing: old files keep loading |
|
||||
| Launcher commands | the command names and their `--json` output | nothing |
|
||||
| Data formats | a `version` or `schema` field in the file | the reader rejects versions newer than it knows |
|
||||
|
||||
## What counts as a breaking change
|
||||
|
||||
Breaking: removing or renaming anything; changing a type, a default, a unit or a meaning; making something optional
|
||||
required; refusing input that was accepted; a new case in a WIT `enum` or `variant` the game sends to mods (an older
|
||||
component cannot decode it); a JSON field that changes type.
|
||||
|
||||
Not breaking: a new function, interface, capability, command, endpoint, tool or `server.toml` key; a new optional
|
||||
argument or JSON field (readers must ignore fields they don't know); a new WIT case the mod *sends* (the game decodes
|
||||
every case it ever served); faster, or fixing behaviour to what the reference already says.
|
||||
|
||||
## Stability levels
|
||||
|
||||
Every part of an API has one level, shown in its reference and its surface page.
|
||||
|
||||
| | Experimental | Preview | Stable |
|
||||
| --- | --- | --- | --- |
|
||||
| Who may use it | opt-in only (a flag or a manifest field naming it); never in a release default | anyone; marked "preview" where players see it (a mod's row on the Mods page) | anyone |
|
||||
| May change | in any release, without notice | only at a new line, after a deprecation | only at a new major, after a deprecation |
|
||||
| Deprecation window | none | at least 30 days, with one release line serving old and new | at least 180 days, with the old major served beside the new one |
|
||||
| Needs | a design note | a generated reference, a guide section, an example, compatibility tests | the same, plus one line of real use without a break |
|
||||
|
||||
- **Promotion.** Experimental → preview when it has what the table asks. Preview → stable when real users (a published
|
||||
mod, a host's script, an agent's tool) used it for a whole line and nothing broke. The maintainers' orchestrator
|
||||
proposes the promotion with the evidence (the compatibility tests, the complete docs, that line of use) and Ludovic
|
||||
approves it.
|
||||
- **Horizon-only by design.** An API is stable only for what Horizon itself does; a vanilla concept it exposes (a block
|
||||
id, a command, a `server.properties` key) changes when vanilla changes it, with a version port
|
||||
([version-ports.md](../version-ports.md)), and the changelog says so.
|
||||
|
||||
## Deprecation and removal
|
||||
|
||||
1. The pull request that deprecates marks it where it is defined (a `/// Deprecated: use X; goes in 0.3.` doc comment,
|
||||
WIT's `@deprecated`, a `deprecated` field in a tool's schema) and adds the replacement in the same release.
|
||||
2. The reference shows it as deprecated, and the surface page's changelog says what replaces it and when it goes.
|
||||
3. Using it logs one warning per mod, session or client, naming the replacement; it keeps working.
|
||||
4. It is removed only after the window, and only at the next line (preview) or major (stable).
|
||||
5. A line or major that is no longer served is refused with a clear message (`needs API 0.1; this Horizon serves 0.3
|
||||
and 0.4`), never loaded half-way.
|
||||
|
||||
## Compatibility tests
|
||||
|
||||
Every preview and stable API has tests that run old users against the current code, in CI:
|
||||
|
||||
| API | The test |
|
||||
| --- | --- |
|
||||
| Mods | a test mod per served line, built from source against that line's WIT and SDK, loaded by today's runtime with expected output (`crates/horizon-mods/tests/`); a line is served as long as its test mod passes |
|
||||
| Agent control | a transcript per protocol version: commands and the reply keys each must have |
|
||||
| Server | `api::ROUTES` against `route()` (generated reference); a `server.toml` from each release line parses to the same settings; golden replies per endpoint |
|
||||
| Launcher | the generated reference; golden `--json` output per command |
|
||||
| Data formats | a sample file of every version a reader accepts, read by today's reader |
|
||||
|
||||
The generated references are the API's own diff: a pull request that changes an API changes its reference, and the
|
||||
reviewer applies the rules above to that diff.
|
||||
|
||||
## Changelog
|
||||
|
||||
Each surface page ends with a changelog: one line per change, newest first, with the API version and the pull request.
|
||||
Deprecations and breaking changes are in bold. The release notes of the game release that ships a change link it.
|
||||
|
||||
## Today
|
||||
|
||||
| Part | Level | Version |
|
||||
| --- | --- | --- |
|
||||
| Mod API: `log`, `game`, `chat`, `hud`, `storage`, `events` | preview | 0.1.0 |
|
||||
| Content mods (`registries`: data-driven blocks and items) | preview | manifest `api = "0.2"` |
|
||||
| Server mods (events, world, server commands) | not started | manifest `api = "0.3"`, experimental first |
|
||||
| Script mods (Lua run by an interpreter mod, [mods.md](mods.md#ways-in)) | not started | |
|
||||
| `cargo horizon-mod` (`new`, `build`, `run`), `horizon-mod-sdk` | preview | 0.1.0 |
|
||||
| Shader API | not started | |
|
||||
| `horizon-ctl` commands and MCP tools | preview | none yet (unversioned) |
|
||||
| The game's own control-socket commands outside `horizon-ctl`'s table (test hooks) | experimental | |
|
||||
| `horizon-server` commands, `server.toml` | stable | `horizon-server --version` |
|
||||
| Server control API | stable | `/api/v1` |
|
||||
| `horizon-launcher` commands and MCP tools | preview | none yet (unversioned) |
|
||||
| Benchmark report | stable | `"version": 1` |
|
||||
| Telemetry batch and consent | stable | `"schema": 1`, consent `2` |
|
||||
| `horizon-graphics.txt`, `horizon-extras.txt`, `horizon-mods.txt` | preview | none |
|
||||
| `SHA256SUMS` and `SHA256SUMS.sig` | stable | |
|
||||
@@ -0,0 +1,34 @@
|
||||
# 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](https://github.com/ludovic111/horizon/tree/main/docs/api). Mods for players: [Mods](/docs/mods). Agents: [Control Horizon with your AI agent](/docs/agents). Hosting: [Host a server](/docs/hosting).
|
||||
|
||||
## 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](https://github.com/ludovic111/horizon/blob/main/docs/api/stability.md).
|
||||
|
||||
## 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.
|
||||
@@ -3,5 +3,6 @@
|
||||
{ "group": "Playing", "pages": ["settings", "multiplayer", "troubleshooting"] },
|
||||
{ "group": "Hosting", "pages": ["hosting"] },
|
||||
{ "group": "Going further", "pages": ["modpacks", "mods", "performance", "agents"] },
|
||||
{ "group": "Build on Horizon", "pages": ["apis"] },
|
||||
{ "group": "Project", "pages": ["contributing", "faq"] }
|
||||
]
|
||||
|
||||
Reference in New Issue
Block a user