/// 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 ] message`, at that level. write: func(level: level, message: string); } /// Capability `game-read`: the local player, the world clock and the block /// the player looks at. 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; /// None on the title screen. get-clock: func() -> option; /// A block along the player's view. record hit { /// The block hit. block-x: s32, block-y: s32, block-z: s32, /// The point on its face where the view meets it. x: f64, y: f64, z: f64, /// `minecraft:stone`, ... block: string, } /// The first block along the player's view (fluids pass), up to /// `distance` blocks (at most 1024; past the loaded chunks, across the /// distant terrain when LOD Distance is on), as of this tick. None when /// nothing is hit, and on the title screen. raycast: func(distance: f32) -> option; } /// 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); /// 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>; /// Errs on a malformed key or over quota (bytes for the whole mod). set: func(key: string, value: list) -> result<_, string>; /// No error if `key` was already absent. delete: func(key: string); } /// Capability `command`: vanilla commands run as the player, with the /// player's permissions, after the hook call returns (8 per call). A mod's /// own commands are not run this way. interface command { /// `line` without its slash; its feedback goes to the chat as if typed. run: func(line: 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`, `:`; 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, /// The row to mark as the current choice, if any. selected: option, } /// A thing on a mod's screen or settings page. /// A button as the options pages have them (200 × 20): a click is /// `ui-events::select(id, 0)`. Mods cycle its label for a choice /// ("Corner: Top Left"). record button-widget { /// The mod's own name for the widget. id: u32, /// Up to 256 characters. label: string, } variant widget { /// Text the player reads. text(text-widget), /// A button. button(button-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, } /// 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); } /// 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(); } /// Capability `input` (experimental: the manifest needs /// `experimental = ["input"]`): the use button on items the mod claims, and /// the mod's own keys. Events wait for `poll`, at most 256. interface input { /// The main hand's stack. record held-item { /// `minecraft:spyglass`, `:`. id: string, count: u32, /// The hotbar slot, 0 to 8. slot: u32, } record item-use { item: held-item, /// Game ticks the button was held (0 on `use-start`). ticks: u32, } variant event { /// The use button went down with a claimed item in the main hand. /// The game does nothing else with the click: no placing, no eating, /// no swing. use-start(item-use), /// It came up again, or the item left the hand, or a screen opened. use-stop(item-use), /// A key `register-key` named went down or up while playing (no /// screen open). The game's own mapping on that key still runs. A /// screen opening lets every held key up. key-down(string), key-up(string), /// Mouse wheel steps while the mod holds the wheel (`claim-wheel`): /// positive away from the player, as the hotbar reads them. wheel(f32), } /// The items whose use the mod handles instead of the game, by id (at /// most 64). Replaces the previous list. claim-items: func(ids: list); /// A key of the mod's: `name` comes back in `key-down` and `key-up`, /// `label` says what it does, `key` is the key as options.txt writes /// it (`key.keyboard.r`), the default: the player can bind another /// one on the mod's page in Options > Mods, and that one wins. At most /// 16; an unknown key is an error. register-key: func(name: string, label: string, key: string) -> result<_, string>; /// The main hand's stack, as of this tick; none when it is empty. held: func() -> option; /// The events since the last call, oldest first. poll: func() -> list; /// Takes the mouse wheel while playing (true) or gives it back: while /// taken, its steps are the mod's `wheel` events and the hotbar doesn't /// move. The game gives it back when the mod stops. claim-wheel: func(on: bool); /// A mapping as the player has bound it. record mapping-state { /// The bound key's name as Controls shows it: `W`, `Space`, `LMB`. label: string, /// Held down now (as of this frame for a mod with a `frame` hook, /// else this tick). down: bool, } /// A movement or click mapping as the player has bound it: `key.forward`, /// `key.left`, `key.back`, `key.right`, `key.jump`, `key.sneak`, /// `key.sprint`, `key.attack` or `key.use`. None for another name. mapping: func(name: string) -> option; /// Clicks of the attack and use buttons in the last second. clicks-per-second: func() -> tuple; } /// Capability `render` (experimental: the manifest needs /// `experimental = ["render"]`): shapes the game draws for the mod with its /// own renderer, kept until the mod replaces them (no call per frame). A mod /// never supplies shader code. interface render { /// A corner of the screen, as `hud`'s panels use them. enum corner { top-left, top-right, bottom-left, bottom-right, } /// A rectangle in GUI pixels: the top left corner and the size. record rect { x: f32, y: f32, w: f32, h: f32, } /// A point in GUI pixels from the screen's top left. record point { x: f32, y: f32, } record fill-shape { rect: rect, /// 0xAARRGGBB. color: u32, } /// Any four-cornered shape (a wheel's segment, an arrow): the corners /// in order round it. record quad-shape { corners: tuple, /// 0xAARRGGBB. color: u32, } record sprite-shape { /// One of the game's GUI sprites, as `gui/sprites/` names them /// (`hud/heart/full`, `widget/button`), the resource packs' versions /// included. An unknown one draws nothing. sprite: string, rect: rect, /// A tint, 0xAARRGGBB: 0xFFFFFFFF draws it as it is. color: u32, } record item-shape { /// `minecraft:diamond`, `:`; an unknown one draws nothing. item: string, /// The icon's top left. at: point, /// 1.0 is the hotbar's 16 × 16. scale: f32, } record text-shape { /// Up to 256 characters, one line. text: string, at: point, /// 0xRRGGBB, as `hud`'s lines. color: u32, /// Centred on `at.x` instead of starting there. centered: bool, shadow: bool, } variant shape { fill(fill-shape), quad(quad-shape), sprite(sprite-shape), item(item-shape), text(text-shape), } /// Replaces the mod's HUD shapes: up to 1024, drawn every frame in /// order over the HUD (after the hotbar, under chat and screens), hidden /// with the HUD (F1). An empty list removes them. set-hud: func(shapes: list); /// The screen's size in GUI pixels (width, height), as of this tick. gui-size: func() -> tuple; /// Shakes the camera: a jolt of `strength` (0 to 1, 1 the hardest) that /// fades out over `seconds` (at most 10). Jolts add up to 1. The view /// turns, the player doesn't, and the player's Distortion Effects option /// scales it (0 turns it off). shake: func(strength: f32, seconds: f32); /// Replaces the mod's corner panel: shapes in GUI pixels from the top /// left of a `width` × `height` box that the game places in `corner`, /// stacked with the game's overlays and the other mods' panels (under /// the status effects at the top right), as `hud`'s panels are. set-corner: func(corner: corner, width: f32, height: f32, shapes: list); /// Removes the mod's corner panel. clear-corner: func(); /// The width of one line of text in GUI pixels, in the HUD's font: exact /// for Latin letters (U+0000 to U+024F), 6 per other character. text-width: func(text: string) -> f32; record frame-rate { /// Frames drawn in the last second. fps: u32, /// The slowest frame's rate, and the 1% low (the 99th percentile /// frame time's rate), over the last 5 seconds. min: u32, low: u32, } /// The game's frame counter, recomputed twice a second. frame-stats: func() -> frame-rate; record zoom { /// The field of view is divided by it: 1 is none, at most 10. factor: f32, /// Ease in and out through the game's field-of-view easing, as the /// spyglass does, instead of at once. smooth: bool, /// Mouse turning is multiplied by it while zoomed: 1 keeps the /// player's sensitivity, at least 0.05. turn: f32, } /// Zooms the camera until the next call (`factor` 1 ends it), only /// while playing: a screen opening or the spyglass's own view (which /// wins) leave the camera vanilla's. With several mods, the strongest /// zoom counts. set-zoom: func(zoom: zoom); record minimap { corner: corner, /// Its side in GUI pixels, 16 to 256. size: f32, /// World blocks per map pixel, 0.5 to 4; the map is 128 × 128 pixels. blocks-per-pixel: f32, /// The map turns with the player, who faces up, and an N on its rim /// marks north. Otherwise north is up and the player's arrow turns. rotate: bool, /// Round, the corners left clear; otherwise square. round: bool, } /// Shows a map of the world around the player in `corner`, stacked with /// the game's overlays and the mods' panels, until the next call (none /// hides it). It looks like a map item: vanilla's map colours with their /// height shading and water depth, and the player's arrow. Underground, /// under a roof and in the Nether it maps the floor around the player's /// height. The game keeps the map's tiles and refreshes them within its /// own frame budget; hidden, they are dropped. One map shows at a time: /// the first loaded mod's. set-minimap: func(minimap: option); } /// 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, /// 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; /// 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); } /// Capability `players`, server mods only (manifest `api = "0.3"`, /// experimental): the players on the server, and messages to them. interface players { enum game-mode { survival, creative, adventure, spectator, } record player { /// The player's UUID, `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. id: string, name: string, /// Feet position, in blocks. x: f64, y: f64, z: f64, /// `minecraft:overworld`, `minecraft:the_nether`, ... dimension: string, game-mode: game-mode, /// Hit points as vanilla counts them: 20 is full health without effects. health: f32, } /// The players online, in the order they joined. online: func() -> list; /// A system message to one player, after the mod's name; false when no /// player with that id is online. Up to 8 messages per call. tell: func(player: string, text: string) -> bool; /// A system message to every player and the server's log, after the /// mod's name. Counts toward the same 8 per call. broadcast: func(text: string); } /// What the server calls in a server mod (manifest `api = "0.3"`, /// experimental). Only the hooks `init` asks for are ever called. The player /// in each event is as the server saw them when it happened. interface server-events { use players.{player}; record registration { /// Commands players may type, without the slash. A name vanilla /// already uses is refused (vanilla's command runs). commands: list, /// Call `tick` every server tick (20 per second). tick: bool, /// Call `player-joined` and `player-left`. joins: bool, /// Call `chat` for each chat message a player sends. chat: bool, /// Call `block-broken` and `block-placed`. blocks: bool, } record block-pos { x: s32, y: s32, z: s32, } /// Once, after loading. An error keeps the mod off and is logged. init: func() -> result; /// Each server tick, with the server's tick counter. tick: func(tick: u64); /// A player joined the server; they are in `players.online` already. player-joined: func(player: player); /// A player left the server; they are no longer in `players.online`. player-left: func(player: player); /// A chat message a player sent, as plain text. chat: func(player: player, text: string); /// `/name args` typed by `player`: ok(some(text)) is their feedback, /// err(text) their error in red. command: func(player: player, name: string, args: string) -> result, string>; /// A player broke the block at `pos` in their dimension: `state` is what /// was there, as `minecraft:oak_log[axis=y]`. block-broken: func(player: player, pos: block-pos, state: string); /// A player placed `state` at `pos` in their dimension. block-placed: func(player: player, pos: block-pos, state: string); } /// A client mod: runs in the player's game. world horizon-mod { import log; import game; import chat; import hud; import storage; import command; export events; } /// A server mod (manifest `side = "server"`, `api = "0.3"`, experimental): /// runs where the world is simulated, on the dedicated server, a LAN host /// and single player's own server. world horizon-server-mod { import log; import storage; import players; export server-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; import render; import input; export ui-events; } /// The game's side of `horizon-ui-mod` beyond `horizon-mod`. world ui-host { import ui; export ui-events; } /// The game's side of capability `render` (imports only). world render-host { import render; import input; }