From 1b23a14ee706cf0464dba0a138f21dcbe551075b Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:38:18 +0200 Subject: [PATCH] Mod API reference generated from the WIT contract docs/api/mods-reference.md lists every capability, world, interface, type, function and hook of horizon:mods, generated from crates/horizon-mod-sdk/wit/horizon.wit and the manifest's capabilities by a test in horizon-mods (feature pack, as CI runs it). The test fails when the page is out of date (HORIZON_WRITE_DOCS=1 rewrites it), when a function has no doc comment, or when a capability grants an interface the contract lacks. The WIT's undocumented functions and fields get doc comments (no change to the contract itself). Co-Authored-By: Claude Opus 5.5 --- .gitattributes | 1 + crates/horizon-mod-sdk/wit/horizon.wit | 12 + crates/horizon-mods/Cargo.toml | 5 + crates/horizon-mods/tests/api_reference.rs | 304 +++++++++++++++++++++ docs/api/mods-reference.md | 141 ++++++++++ 5 files changed, 463 insertions(+) create mode 100644 crates/horizon-mods/tests/api_reference.rs create mode 100644 docs/api/mods-reference.md diff --git a/.gitattributes b/.gitattributes index 13584e4d9..358aeae7a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -3,3 +3,4 @@ docs/launcher-commands.md text eol=lf docs/horizon-ctl-commands.md text eol=lf website/src/tokens.css text eol=lf +docs/api/*-reference.md text eol=lf diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit index 972389a82..9f00a12b1 100644 --- a/crates/horizon-mod-sdk/wit/horizon.wit +++ b/crates/horizon-mod-sdk/wit/horizon.wit @@ -14,19 +14,24 @@ interface log { warn, error, } + /// One line in the game's log as `[mod ] message`, at that level. write: func(level: level, message: string); } /// Capability `game-read`: the local player and the world clock. interface game { record player { + /// Feet position, in blocks. x: f64, y: f64, z: f64, /// Degrees, as F3 shows them. yaw: f32, + /// Degrees: -90 looks straight up, 90 straight down. pitch: f32, + /// Hit points as vanilla counts them: 20 is full health without effects. health: f32, + /// 0 to 20, as the hunger bar. food: u32, /// `minecraft:overworld`, `minecraft:the_nether`, ... dimension: string, @@ -39,6 +44,7 @@ interface game { } /// None on the title screen. get-player: func() -> option; + /// None on the title screen. get-clock: func() -> option; } @@ -58,11 +64,14 @@ interface hud { bottom-right, } record line { + /// Plain text, up to 256 characters. text: string, /// 0xRRGGBB. color: u32, } + /// Replaces the mod's panel: up to 16 lines in that corner of the screen. set-panel: func(corner: corner, lines: list); + /// Removes the mod's panel. clear: func(); } @@ -92,10 +101,13 @@ interface events { } /// Once, after loading. An error keeps the mod off and is shown. init: func() -> result; + /// Each game tick while in a world, with the game's tick counter. tick: func(tick: u64); + /// Each rendered frame, with the seconds since the last one. frame: func(seconds: f32); /// `/name args`: ok(some(text)) is shown as feedback, err(text) in red. command: func(name: string, args: string) -> result, string>; + /// Each chat line the player receives, as plain text. chat: func(text: string); } diff --git a/crates/horizon-mods/Cargo.toml b/crates/horizon-mods/Cargo.toml index 013d38a99..3dfc02331 100644 --- a/crates/horizon-mods/Cargo.toml +++ b/crates/horizon-mods/Cargo.toml @@ -30,5 +30,10 @@ pack = ["dep:wit-component", "dep:wit-parser"] name = "sandbox" required-features = ["runtime", "pack"] +# docs/api/mods-reference.md from the WIT contract (HORIZON_WRITE_DOCS=1 rewrites it). +[[test]] +name = "api_reference" +required-features = ["pack"] + [lints] workspace = true diff --git a/crates/horizon-mods/tests/api_reference.rs b/crates/horizon-mods/tests/api_reference.rs new file mode 100644 index 000000000..5e6a0a069 --- /dev/null +++ b/crates/horizon-mods/tests/api_reference.rs @@ -0,0 +1,304 @@ +//! docs/api/mods-reference.md, generated from the WIT contract and the manifest's capabilities, and a test that +//! fails when it is out of date. Update it with: +//! `HORIZON_WRITE_DOCS=1 cargo test -p horizon-mods --features pack --test api_reference`. +use horizon_mods::manifest::{APIS, Capability}; +use std::{fmt::Write, path::Path}; +use wit_parser::{Docs, Function, Handle, Resolve, Type, TypeDefKind, WorldItem}; + +const WIT: &str = "crates/horizon-mod-sdk/wit/horizon.wit"; +const DOC: &str = "docs/api/mods-reference.md"; + +fn root() -> &'static Path { + Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/../..")) +} + +/// A doc comment on one line, for a table cell. +fn cell(docs: &Docs) -> String { + let text = docs.contents.as_deref().unwrap_or("").trim(); + text.split_whitespace() + .collect::>() + .join(" ") + .replace('|', "\\|") +} + +/// A type as WIT spells it. +fn ty(resolve: &Resolve, t: &Type) -> String { + let id = match t { + Type::Bool => return "bool".into(), + Type::U8 => return "u8".into(), + Type::U16 => return "u16".into(), + Type::U32 => return "u32".into(), + Type::U64 => return "u64".into(), + Type::S8 => return "s8".into(), + Type::S16 => return "s16".into(), + Type::S32 => return "s32".into(), + Type::S64 => return "s64".into(), + Type::F32 => return "f32".into(), + Type::F64 => return "f64".into(), + Type::Char => return "char".into(), + Type::String => return "string".into(), + Type::ErrorContext => return "error-context".into(), + Type::Id(id) => *id, + }; + match &resolve.types[id].name { + Some(name) => name.clone(), + None => definition(resolve, &resolve.types[id].kind), + } +} + +/// What an anonymous type, or the right-hand side of a `type` alias, spells. +fn definition(resolve: &Resolve, kind: &TypeDefKind) -> String { + let of = |t: &Option| t.as_ref().map_or("_".into(), |t| ty(resolve, t)); + match kind { + TypeDefKind::Option(t) => format!("option<{}>", ty(resolve, t)), + TypeDefKind::List(t) => format!("list<{}>", ty(resolve, t)), + TypeDefKind::FixedSizeList(t, n) => format!("list<{}, {n}>", ty(resolve, t)), + TypeDefKind::Result(r) => match (&r.ok, &r.err) { + (None, None) => "result".into(), + (ok, None) => format!("result<{}>", of(ok)), + (ok, err) => format!("result<{}, {}>", of(ok), of(err)), + }, + TypeDefKind::Tuple(t) => { + let items: Vec<_> = t.types.iter().map(|t| ty(resolve, t)).collect(); + format!("tuple<{}>", items.join(", ")) + } + TypeDefKind::Future(t) => t + .as_ref() + .map_or("future".into(), |t| format!("future<{}>", ty(resolve, t))), + TypeDefKind::Stream(t) => t + .as_ref() + .map_or("stream".into(), |t| format!("stream<{}>", ty(resolve, t))), + TypeDefKind::Handle(Handle::Own(t)) => ty(resolve, &Type::Id(*t)), + TypeDefKind::Handle(Handle::Borrow(t)) => format!("borrow<{}>", ty(resolve, &Type::Id(*t))), + TypeDefKind::Type(t) => ty(resolve, t), + other => panic!( + "{WIT}: an anonymous {} the reference can't spell", + other.as_str() + ), + } +} + +fn signature(resolve: &Resolve, f: &Function) -> String { + let params: Vec<_> = f + .params + .iter() + .map(|(name, t)| format!("{name}: {}", ty(resolve, t))) + .collect(); + let result = f + .result + .as_ref() + .map_or(String::new(), |t| format!(" -> {}", ty(resolve, t))); + format!("func({}){result}", params.join(", ")) +} + +/// Who may use an interface: the capability that grants it, or what it is. +fn access(interface: &str, exported: bool) -> String { + if exported { + return "exported by the mod: the game calls it".into(); + } + if interface == "log" { + return "always granted".into(); + } + match Capability::ALL.iter().find(|c| c.interface() == interface) { + Some(c) => format!("capability `{c}`"), + None => "not granted by any capability".into(), + } +} + +fn markdown() -> String { + let mut resolve = Resolve::new(); + let package = resolve + .push_file(root().join(WIT)) + .expect("the WIT contract parses"); + let package = &resolve.packages[package]; + let name = &package.name; + let mut out = String::new(); + let w = &mut out; + writeln!(w, "").unwrap(); + writeln!(w, "# Mod API reference\n").unwrap(); + writeln!( + w, + "The contract between Horizon and its mods: the WIT package `{name}`, every interface, type, function and hook in it, \ + and the capabilities a manifest may list. The guide is [mods.md](../mods.md); stability and versions: \ + [stability.md](stability.md). Manifest `api` lines this game serves: {}.\n", + APIS.map(|a| format!("`{a}`")).join(", ") + ) + .unwrap(); + + writeln!(w, "## Capabilities\n").unwrap(); + writeln!( + w, + "| In `capabilities` | Grants | The player reads \"May …\" |\n| --- | --- | --- |" + ) + .unwrap(); + for c in Capability::ALL { + let grants = if package.interfaces.contains_key(c.interface()) { + format!("[`{0}`](#{0})", c.interface()) + } else { + "data files (`assets/`, `data/`), no interface".into() + }; + writeln!(w, "| `{c}` | {grants} | {} |", c.describe()).unwrap(); + } + + let mut exported = Vec::new(); + for (world_name, &world) in &package.worlds { + let world = &resolve.worlds[world]; + let prefix = format!("{}:{}/", name.namespace, name.name); + let names = |keys: Vec<&wit_parser::WorldKey>| { + keys.into_iter() + .map(|key| { + let full = resolve.name_world_key(key); + let short = full.trim_start_matches(&prefix); + format!("`{}`", short.split('@').next().unwrap_or(short)) + }) + .collect::>() + .join(", ") + }; + writeln!(w, "\n## World `{world_name}`\n").unwrap(); + if world.docs.contents.is_some() { + writeln!(w, "{}\n", cell(&world.docs)).unwrap(); + } + writeln!( + w, + "- Imports (what the game offers): {}", + names(world.imports.keys().collect()) + ) + .unwrap(); + writeln!( + w, + "- Exports (what the mod provides): {}", + names(world.exports.keys().collect()) + ) + .unwrap(); + for item in world.exports.values() { + if let WorldItem::Interface { id, .. } = item { + exported.push(*id); + } + } + } + + for (interface_name, &id) in &package.interfaces { + let interface = &resolve.interfaces[id]; + writeln!(w, "\n## `{interface_name}`\n").unwrap(); + writeln!( + w, + "Access: {}.\n", + access(interface_name, exported.contains(&id)) + ) + .unwrap(); + if interface.docs.contents.is_some() { + writeln!(w, "{}\n", cell(&interface.docs)).unwrap(); + } + for (type_name, &type_id) in &interface.types { + let def = &resolve.types[type_id]; + writeln!(w, "### {} `{type_name}`\n", def.kind.as_str()).unwrap(); + if def.docs.contents.is_some() { + writeln!(w, "{}\n", cell(&def.docs)).unwrap(); + } + match &def.kind { + TypeDefKind::Record(r) => { + writeln!(w, "| Field | Type | |\n| --- | --- | --- |").unwrap(); + for f in &r.fields { + writeln!( + w, + "| `{}` | `{}` | {} |", + f.name, + ty(&resolve, &f.ty), + cell(&f.docs) + ) + .unwrap(); + } + } + TypeDefKind::Enum(e) => { + writeln!(w, "| Case | |\n| --- | --- |").unwrap(); + for c in &e.cases { + writeln!(w, "| `{}` | {} |", c.name, cell(&c.docs)).unwrap(); + } + } + TypeDefKind::Variant(v) => { + writeln!(w, "| Case | Payload | |\n| --- | --- | --- |").unwrap(); + for c in &v.cases { + let payload = + c.ty.as_ref() + .map_or(String::new(), |t| format!("`{}`", ty(&resolve, t))); + writeln!(w, "| `{}` | {payload} | {} |", c.name, cell(&c.docs)).unwrap(); + } + } + TypeDefKind::Flags(f) => { + writeln!(w, "| Flag | |\n| --- | --- |").unwrap(); + for flag in &f.flags { + writeln!(w, "| `{}` | {} |", flag.name, cell(&flag.docs)).unwrap(); + } + } + TypeDefKind::Resource => { + writeln!(w, "A resource: the game owns it, the mod holds a handle.").unwrap() + } + kind => writeln!(w, "`type {type_name} = {}`", definition(&resolve, kind)).unwrap(), + } + writeln!(w).unwrap(); + } + if !interface.functions.is_empty() { + writeln!( + w, + "| Function | Signature | What it does |\n| --- | --- | --- |" + ) + .unwrap(); + for (fn_name, f) in &interface.functions { + writeln!( + w, + "| `{fn_name}` | `{}` | {} |", + signature(&resolve, f), + cell(&f.docs) + ) + .unwrap(); + } + } + } + out +} + +#[test] +fn the_mod_api_reference_is_up_to_date() { + let path = root().join(DOC); + let want = markdown(); + if std::env::var_os("HORIZON_WRITE_DOCS").is_some() { + std::fs::write(&path, &want).unwrap(); + } + let have = std::fs::read_to_string(&path) + .unwrap_or_default() + .replace("\r\n", "\n"); + assert!( + have == want, + "{DOC} is out of date: HORIZON_WRITE_DOCS=1 cargo test -p horizon-mods --features pack --test api_reference" + ); +} + +#[test] +fn every_function_is_documented() { + let mut resolve = Resolve::new(); + resolve.push_file(root().join(WIT)).unwrap(); + for (_, interface) in resolve.interfaces.iter() { + for (name, f) in &interface.functions { + assert!( + f.docs.contents.is_some(), + "{WIT}: `{name}` needs a doc comment: the reference shows it to mod authors" + ); + } + } +} + +#[test] +fn every_capability_with_an_interface_is_in_the_contract() { + let mut resolve = Resolve::new(); + let package = resolve.push_file(root().join(WIT)).unwrap(); + let interfaces = &resolve.packages[package].interfaces; + for c in Capability::ALL { + if c != Capability::Registries { + assert!( + interfaces.contains_key(c.interface()), + "capability {c} grants `{}`, missing from {WIT}", + c.interface() + ); + } + } +} diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md new file mode 100644 index 000000000..ca2fe9d7a --- /dev/null +++ b/docs/api/mods-reference.md @@ -0,0 +1,141 @@ + +# Mod API reference + +The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`, every interface, type, function and hook in it, and the capabilities a manifest may list. The guide is [mods.md](../mods.md); stability and versions: [stability.md](stability.md). Manifest `api` lines this game serves: `0.1`, `0.2`. + +## Capabilities + +| In `capabilities` | Grants | The player reads "May …" | +| --- | --- | --- | +| `game-read` | [`game`](#game) | see your position, health and the time | +| `chat` | [`chat`](#chat) | show you chat messages | +| `hud` | [`hud`](#hud) | draw text on your screen | +| `storage` | [`storage`](#storage) | save its own settings to disk | +| `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds | + +## World `horizon-mod` + +- Imports (what the game offers): `log`, `game`, `chat`, `hud`, `storage` +- Exports (what the mod provides): `events` + +## `log` + +Access: always granted. + +The mod's log, in the game's log under the mod's id. Always granted. + +### enum `level` + +| Case | | +| --- | --- | +| `debug` | | +| `info` | | +| `warn` | | +| `error` | | + +| Function | Signature | What it does | +| --- | --- | --- | +| `write` | `func(level: level, message: string)` | One line in the game's log as `[mod ] message`, at that level. | + +## `game` + +Access: capability `game-read`. + +Capability `game-read`: the local player and the world clock. + +### record `player` + +| Field | Type | | +| --- | --- | --- | +| `x` | `f64` | Feet position, in blocks. | +| `y` | `f64` | | +| `z` | `f64` | | +| `yaw` | `f32` | Degrees, as F3 shows them. | +| `pitch` | `f32` | Degrees: -90 looks straight up, 90 straight down. | +| `health` | `f32` | Hit points as vanilla counts them: 20 is full health without effects. | +| `food` | `u32` | 0 to 20, as the hunger bar. | +| `dimension` | `string` | `minecraft:overworld`, `minecraft:the_nether`, ... | + +### record `clock` + +| Field | Type | | +| --- | --- | --- | +| `game-time` | `u64` | Ticks since the world was created. | +| `day-time` | `u64` | 24000 ticks per day; 0 is 6:00 on the first day. | + +| Function | Signature | What it does | +| --- | --- | --- | +| `get-player` | `func() -> option` | None on the title screen. | +| `get-clock` | `func() -> option` | None on the title screen. | + +## `chat` + +Access: capability `chat`. + +Capability `chat`: messages only the local player sees. + +| Function | Signature | What it does | +| --- | --- | --- | +| `show` | `func(text: string)` | Shown in chat after the mod's name, like a system message. | + +## `hud` + +Access: capability `hud`. + +Capability `hud`: one panel of text lines per mod, drawn by the game every frame until the mod changes or clears it (no call per frame). + +### enum `corner` + +| Case | | +| --- | --- | +| `top-left` | | +| `top-right` | | +| `bottom-left` | | +| `bottom-right` | | + +### record `line` + +| Field | Type | | +| --- | --- | --- | +| `text` | `string` | Plain text, up to 256 characters. | +| `color` | `u32` | 0xRRGGBB. | + +| Function | Signature | What it does | +| --- | --- | --- | +| `set-panel` | `func(corner: corner, lines: list)` | Replaces the mod's panel: up to 16 lines in that corner of the screen. | +| `clear` | `func()` | Removes the mod's panel. | + +## `storage` + +Access: capability `storage`. + +Capability `storage`: a per-mod folder of small key/value files, quota'd (docs/mods.md). Keys are `[a-z0-9_.-]{1,64}`, one path segment. + +| Function | Signature | What it does | +| --- | --- | --- | +| `get` | `func(key: string) -> option>` | None if `key` has never been `set`, or the key is not well-formed. | +| `set` | `func(key: string, value: list) -> result<_, string>` | Errs on a malformed key or over quota (bytes for the whole mod). | +| `delete` | `func(key: string)` | No error if `key` was already absent. | + +## `events` + +Access: exported by the mod: the game calls it. + +What the game calls. Only the hooks `init` asks for are ever called. + +### record `registration` + +| Field | Type | | +| --- | --- | --- | +| `commands` | `list` | Chat commands, without the slash. A name vanilla already uses is refused (vanilla's command runs). | +| `tick` | `bool` | Call `tick` every game tick (20 per second while playing). | +| `frame` | `bool` | Call `frame` every rendered frame. Budget: 0.1 ms. | +| `chat` | `bool` | Call `chat` for each chat line the player receives. | + +| Function | Signature | What it does | +| --- | --- | --- | +| `init` | `func() -> result` | Once, after loading. An error keeps the mod off and is shown. | +| `tick` | `func(tick: u64)` | Each game tick while in a world, with the game's tick counter. | +| `frame` | `func(seconds: f32)` | Each rendered frame, with the seconds since the last one. | +| `command` | `func(name: string, args: string) -> result, string>` | `/name args`: ok(some(text)) is shown as feedback, err(text) in red. | +| `chat` | `func(text: string)` | Each chat line the player receives, as plain text. |