Merge pull request #1583 from ludovic111/docs/platform-apis
This commit is contained in:
@@ -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 | |
|
||||
Reference in New Issue
Block a user