From e5bfce3b37e94b6583b37d6061aa1cd428dfaa0d Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:53:43 +0200 Subject: [PATCH] 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 --- docs/api/mods.md | 29 ++++++++++++++++++++++++++--- docs/api/stability.md | 7 +++++-- website/docs/apis.md | 2 +- 3 files changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/api/mods.md b/docs/api/mods.md index ec42bc0db..bec03e84e 100644 --- a/docs/api/mods.md +++ b/docs/api/mods.md @@ -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. diff --git a/docs/api/stability.md b/docs/api/stability.md index deca14d1d..2d4476fc7 100644 --- a/docs/api/stability.md +++ b/docs/api/stability.md @@ -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) | diff --git a/website/docs/apis.md b/website/docs/apis.md index 0c4d431db..f948b1d54 100644 --- a/website/docs/apis.md +++ b/website/docs/apis.md @@ -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 |