Files
horizon-airdef/crates/horizon-mod-sdk/wit/horizon.wit
T
socksprox af7a685b5c Mod API: capability ui — mod-owned screens and settings pages
New WIT interface `ui` (text, item and list widgets; open-screen,
close-screen, set-settings) plus a `ui-events` export (select, closed,
settings-opened), in a second world `horizon-ui-mod` so mods built before
it keep loading. The game lays out and draws the widgets with its own
menus' code: a screen the mod owns (Esc/Done to leave) and a Settings
button on the mod's Options > Mods row that opens its page.

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-10-25 17:09:25 +01:00

214 lines
7.6 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);
}
/// Capability `ui`: widgets the game draws with its own menus' widgets, for
/// a screen the mod owns and a settings page in Options > Mods. Layout and
/// drawing are the game's: a mod says what its widgets hold, never where
/// they sit or how they look, and the game clips everything it is handed.
interface ui {
/// A line of text.
record text-widget {
/// The mod's own name for the widget; `ui-events` calls echo it.
id: u32,
/// Up to 256 characters.
text: string,
/// 0xRRGGBB; 0 is the menus' white.
color: u32,
}
/// An item's icon and a name beside it, as recipe viewers show them.
record item-widget {
/// The mod's own name for the widget.
id: u32,
/// `minecraft:diamond`, `<mod>:<path>`; an unknown id draws a "?".
item: string,
/// The name shown beside the icon (empty: the item's own).
name: string,
}
/// Rows the player picks one of, as an options page lists choices: a
/// pick is `ui-events::select`, `selected` is the row to mark now.
record list-widget {
/// The mod's own name for the widget; `ui-events::select` echoes it.
id: u32,
/// The rows' texts, at most 512, each up to 256 characters.
rows: list<string>,
/// The row to mark as the current choice, if any.
selected: option<u32>,
}
/// A thing on a mod's screen or settings page.
variant widget {
/// Text the player reads.
text(text-widget),
/// An item's icon and name.
item(item-widget),
/// Rows the player picks from.
%list(list-widget),
}
/// A screen the mod owns: a title over widgets stacked down the middle,
/// the Done button the game adds, and Esc to leave it.
record screen {
/// Its title, up to 256 characters.
title: string,
/// Its widgets, in order, at most 64.
widgets: list<widget>,
}
/// Show `screen` over the game; a second call while it is open replaces
/// it. Only the last call of one hook counts.
open-screen: func(screen: screen);
/// Close the mod's screen when it is open (the mod hears no `closed`
/// for this: it was its own doing).
close-screen: func();
/// The mod's page in Options > Mods, reached from a settings button on
/// its row: the widgets it shows, an empty list for no page. The player
/// opening the page is `ui-events::settings-opened`: push fresh widgets
/// then; later calls update the page while it shows.
set-settings: func(widgets: list<widget>);
}
/// What the game calls on a mod that shows widgets (capability `ui`):
/// what the player did with them.
interface ui-events {
/// A row of one of the mod's `list` widgets was picked: the widget's
/// `id` and the row, on the screen or the settings page that showed it.
select: func(id: u32, row: u32);
/// The player left the mod's screen (Esc or Done); not for a screen the
/// mod closed itself or one that went away with the mod.
closed: func();
/// The player opened the mod's settings page in Options > Mods: call
/// `ui::set-settings` now to fill it with fresh widgets.
settings-opened: func();
}
/// 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;
}
/// A mod with widgets (capability `ui`): the SDK builds every mod against
/// this world. Mods built for `horizon-mod` alone (no `ui-events` export)
/// still load and simply hear nothing of their widgets.
world horizon-ui-mod {
include horizon-mod;
import ui;
export ui-events;
}
/// The game's side of `horizon-ui-mod` beyond `horizon-mod`.
world ui-host {
import ui;
export ui-events;
}