Horizon APIs: ways in for mods, server mods as api 0.3, who promotes to stable
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>
This commit is contained in:
+26
-3
@@ -46,27 +46,50 @@ call, 4 MiB of storage, fuel per call).
|
||||
- `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. Block entities (draft #1189, `api = "0.4"`) are experimental.
|
||||
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**: the same component running on the server thread and the dedicated server, with world events (block
|
||||
- **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 (draft #1189 is the first step).
|
||||
- **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.
|
||||
|
||||
|
||||
@@ -45,7 +45,9 @@ Every part of an API has one level, shown in its reference and its surface page.
|
||||
| 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; Ludovic decides that step.
|
||||
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.
|
||||
@@ -86,7 +88,8 @@ Deprecations and breaking changes are in bold. The release notes of the game rel
|
||||
| --- | --- | --- |
|
||||
| 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"` |
|
||||
| Block entities for code mods (draft #1189) | experimental | manifest `api = "0.4"` |
|
||||
| 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) |
|
||||
|
||||
@@ -6,7 +6,7 @@ Horizon is built to be built on. Mods, shaders, agents, server panels, launchers
|
||||
|
||||
| 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 |
|
||||
| **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 |
|
||||
|
||||
Reference in New Issue
Block a user