1b23a14ee7
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 <noreply@anthropic.com>
122 lines
4.0 KiB
Plaintext
122 lines
4.0 KiB
Plaintext
/// The contract between Horizon and its mods (docs/mods.md).
|
|
///
|
|
/// A mod is a WebAssembly component targeting the `mod` world. Each imported
|
|
/// interface but `log` is a capability: the mod's manifest lists the ones it
|
|
/// uses, the player sees them before turning the mod on, and the game refuses
|
|
/// a component that imports one its manifest does not declare.
|
|
package horizon:mods@0.1.0;
|
|
|
|
/// The mod's log, in the game's log under the mod's id. Always granted.
|
|
interface log {
|
|
enum level {
|
|
debug,
|
|
info,
|
|
warn,
|
|
error,
|
|
}
|
|
/// One line in the game's log as `[mod <id>] 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,
|
|
}
|
|
record clock {
|
|
/// Ticks since the world was created.
|
|
game-time: u64,
|
|
/// 24000 ticks per day; 0 is 6:00 on the first day.
|
|
day-time: u64,
|
|
}
|
|
/// None on the title screen.
|
|
get-player: func() -> option<player>;
|
|
/// None on the title screen.
|
|
get-clock: func() -> option<clock>;
|
|
}
|
|
|
|
/// Capability `chat`: messages only the local player sees.
|
|
interface chat {
|
|
/// Shown in chat after the mod's name, like a system message.
|
|
show: func(text: string);
|
|
}
|
|
|
|
/// 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).
|
|
interface hud {
|
|
enum corner {
|
|
top-left,
|
|
top-right,
|
|
bottom-left,
|
|
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<line>);
|
|
/// Removes the mod's panel.
|
|
clear: func();
|
|
}
|
|
|
|
/// 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.
|
|
interface storage {
|
|
/// None if `key` has never been `set`, or the key is not well-formed.
|
|
get: func(key: string) -> option<list<u8>>;
|
|
/// Errs on a malformed key or over quota (bytes for the whole mod).
|
|
set: func(key: string, value: list<u8>) -> result<_, string>;
|
|
/// No error if `key` was already absent.
|
|
delete: func(key: string);
|
|
}
|
|
|
|
/// What the game calls. Only the hooks `init` asks for are ever called.
|
|
interface events {
|
|
record registration {
|
|
/// Chat commands, without the slash. A name vanilla already uses is
|
|
/// refused (vanilla's command runs).
|
|
commands: list<string>,
|
|
/// Call `tick` every game tick (20 per second while playing).
|
|
tick: bool,
|
|
/// Call `frame` every rendered frame. Budget: 0.1 ms.
|
|
frame: bool,
|
|
/// Call `chat` for each chat line the player receives.
|
|
chat: bool,
|
|
}
|
|
/// Once, after loading. An error keeps the mod off and is shown.
|
|
init: func() -> result<registration, string>;
|
|
/// 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<option<string>, string>;
|
|
/// Each chat line the player receives, as plain text.
|
|
chat: func(text: string);
|
|
}
|
|
|
|
world horizon-mod {
|
|
import log;
|
|
import game;
|
|
import chat;
|
|
import hud;
|
|
import storage;
|
|
export events;
|
|
}
|