af7a685b5c
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>
214 lines
7.6 KiB
Plaintext
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;
|
|
}
|