From 24ab642e7bc79eea0cd97d99a7abcf1c5049f9ea Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Mon, 26 Oct 2026 08:20:30 +0100 Subject: [PATCH] Mod API: render.set-minimap, a map the game keeps in a corner What the official Minimap mod needs: a mod picks the corner, side, scale, shape and turning, and the game draws the map as the minimap extra does, from the same tiles (vanilla's map colours, the floor under roofs) within its own frame budget. One map at a time, the first loaded mod's. A new function and type, so mods built before it keep loading. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/game/extras.rs | 48 +++++++++++++------ crates/horizon-client/src/game/mod_input.rs | 31 ++++++++++++ crates/horizon-mod-sdk/wit/horizon.wit | 21 ++++++++ crates/horizon-mods/src/runtime.rs | 25 +++++++++- crates/horizon-mods/tests/sandbox.rs | 26 ++++++++++ crates/horizon-mods/tests/ui_guest/src/lib.rs | 19 ++++++++ docs/api/mods-reference.md | 11 +++++ docs/api/stability.md | 4 ++ docs/mods.md | 2 +- 9 files changed, 169 insertions(+), 18 deletions(-) diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs index 30073f186..3abe6f5c7 100644 --- a/crates/horizon-client/src/game/extras.rs +++ b/crates/horizon-client/src/game/extras.rs @@ -159,25 +159,44 @@ impl Game<'_> { } Ok(()) } - /// The minimap's view of the player, if it shows. - fn minimap_view(&self) -> Option { - let e = &self.settings.extras; + /// The minimap that shows, the extra's or else a mod's + /// (`render.set-minimap`): its corner, its side in GUI pixels and its + /// view of the player. + fn minimap_shown(&self) -> Option<(Corner, f32, View)> { let p = self.player.as_ref()?; - let shown = e.minimap && self.title.is_none() && !self.ui.hide_gui; - shown.then_some(View { + if self.title.is_some() || self.ui.hide_gui { + return None; + } + let e = &self.settings.extras; + let (corner, size, rotate, blocks_per_pixel, round) = if e.minimap { + let size = f32::from(e.minimap_size); + ( + e.minimap_corner, + size, + e.minimap_rotate, + e.minimap_zoom, + e.minimap_round, + ) + } else { + let m = self.mod_minimap()?; + (m.corner, m.size, m.rotate, m.blocks_per_pixel, m.round) + }; + let view = View { x: p.position.x, z: p.position.z, yaw: self.yaw, - rotate: e.minimap_rotate, - blocks_per_pixel: e.minimap_zoom, - round: e.minimap_round, - }) + rotate, + blocks_per_pixel, + round, + }; + Some((corner, size, view)) } /// Refresh the minimap's tiles within the frame budget, recompose its /// image when the view or a tile changed, and queue the upload. fn update_minimap(&mut self) { - let Some(view) = self.minimap_view() else { - if !self.settings.extras.minimap || self.player.is_none() { + let Some((_, _, view)) = self.minimap_shown() else { + let wanted = self.settings.extras.minimap || self.mod_minimap().is_some(); + if !wanted || self.player.is_none() { self.extras.minimap.clear(); self.extras.minimap_dim = None; } @@ -265,16 +284,15 @@ impl Game<'_> { /// The minimap and mods' corner panels, in the HUD layer (hidden with F1 /// by the caller). The top left corner gives way to the debug screen. pub(super) fn draw_extras(&mut self, batch: &mut HudBatch) { - let e = &self.settings.extras; let mod_panels = self.mods.has_panels(); - if !e.minimap && !mod_panels { + let map = self.minimap_shown(); + if map.is_none() && !mod_panels { return; } - let (map_corner, map_size) = (e.minimap_corner, f32::from(e.minimap_size)); let visible = |corner| !(self.debug && corner == Corner::TopLeft); let mut corners = Corners::new(batch.width, batch.height, self.effect_rows_height()); let atlas = &self.gui.atlas; - if let Some(view) = self.minimap_view() + if let Some((map_corner, map_size, view)) = map && visible(map_corner) && !self.extras.minimap.image.is_empty() && let Some(image) = atlas.sprites.get(MINIMAP_SPRITE).copied() diff --git a/crates/horizon-client/src/game/mod_input.rs b/crates/horizon-client/src/game/mod_input.rs index 199669957..10faf6a81 100644 --- a/crates/horizon-client/src/game/mod_input.rs +++ b/crates/horizon-client/src/game/mod_input.rs @@ -28,6 +28,9 @@ impl Game<'_> { pub(super) fn mod_zoom(&self) -> Option { None } + pub(super) fn mod_minimap(&self) -> Option { + None + } } /// A mod's zoom (`render.set-zoom`), clamped by the runtime. @@ -38,6 +41,16 @@ pub(super) struct ModZoom { pub(super) turn: f32, } +/// A mod's minimap (`render.set-minimap`), clamped by the runtime. +#[derive(Clone, Copy)] +pub(super) struct ModMinimap { + pub(super) corner: horizon_client::extras::Corner, + pub(super) size: f32, + pub(super) blocks_per_pixel: f32, + pub(super) rotate: bool, + pub(super) round: bool, +} + #[cfg(feature = "mods")] impl Game<'_> { /// The main hand's stack as `input` shows it; none when it is empty. @@ -147,4 +160,22 @@ impl Game<'_> { turn: z.turn, }) } + /// The minimap the first mod showing one asks for. + pub(super) fn mod_minimap(&self) -> Option { + use horizon_client::extras::Corner; + use horizon_mods::RenderCorner; + let m = self.mods.mods.minimap()?; + Some(ModMinimap { + corner: match m.corner { + RenderCorner::TopLeft => Corner::TopLeft, + RenderCorner::TopRight => Corner::TopRight, + RenderCorner::BottomLeft => Corner::BottomLeft, + RenderCorner::BottomRight => Corner::BottomRight, + }, + size: m.size, + blocks_per_pixel: m.blocks_per_pixel, + rotate: m.rotate, + round: m.round, + }) + } } diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit index 9088c0c39..5fbfafc24 100644 --- a/crates/horizon-mod-sdk/wit/horizon.wit +++ b/crates/horizon-mod-sdk/wit/horizon.wit @@ -364,6 +364,27 @@ interface render { /// 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. diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs index 0011fa99d..4dc334ea5 100644 --- a/crates/horizon-mods/src/runtime.rs +++ b/crates/horizon-mods/src/runtime.rs @@ -52,8 +52,9 @@ use render_bindings::horizon::mods::input; pub use render_bindings::horizon::mods::input::{Event as InputEvent, HeldItem, ItemUse}; /// What capability `render` asks the game to draw (WIT `interface render`). pub use render_bindings::horizon::mods::render::{ - Corner as RenderCorner, FillShape, FrameRate, ItemShape, Point as RenderPoint, QuadShape, - Rect as RenderRect, Shape, SpriteShape, TextShape, Zoom as ModZoom, + Corner as RenderCorner, FillShape, FrameRate, ItemShape, Minimap as ModMinimap, + Point as RenderPoint, QuadShape, Rect as RenderRect, Shape, SpriteShape, TextShape, + Zoom as ModZoom, }; use render_bindings::{RenderHost, horizon::mods::render}; @@ -196,6 +197,8 @@ struct State { corner: Option, /// Capability `render`'s zoom, when the mod zooms. zoom: Option, + /// Capability `render`'s minimap, when the mod shows one. + minimap: Option, input: InputState, /// Capability `storage`'s folder; made on first `set`. data_dir: PathBuf, @@ -339,6 +342,7 @@ impl Mods { shapes: Vec::new(), corner: None, zoom: None, + minimap: None, input: InputState::default(), data_dir, storage_budget: STORAGE_WRITE_BUDGET, @@ -684,6 +688,12 @@ impl Mods { .filter_map(|e| e.run.as_ref()?.store.data().zoom) .max_by(|a, b| a.factor.total_cmp(&b.factor)) } + /// The minimap the first running mod shows (capability `render`). + pub fn minimap(&self) -> Option { + self.entries + .iter() + .find_map(|e| e.run.as_ref()?.store.data().minimap) + } fn inputs(&self) -> impl Iterator { self.entries .iter() @@ -1013,6 +1023,9 @@ const SHAKE_SECONDS: f32 = 10.0; /// or more, and turning never stops. const ZOOM_MAX: f32 = 10.0; const TURN_MIN: f32 = 0.05; +/// `set-minimap`'s side in GUI pixels and its blocks per map pixel. +const MINIMAP_SIZE: (f32, f32) = (16.0, 256.0); +const MINIMAP_SCALE: (f32, f32) = (0.5, 4.0); /// A mod's corner panel: shapes in a `width` × `height` box the game /// places in `corner`, stacked with the other overlays. @@ -1094,6 +1107,14 @@ impl render::Host for State { }, }); } + fn set_minimap(&mut self, minimap: Option) { + let finite = |v: f32, lo: f32, hi: f32| if v.is_finite() { v.clamp(lo, hi) } else { lo }; + self.minimap = minimap.map(|m| ModMinimap { + size: finite(m.size, MINIMAP_SIZE.0, MINIMAP_SIZE.1), + blocks_per_pixel: finite(m.blocks_per_pixel, MINIMAP_SCALE.0, MINIMAP_SCALE.1), + ..m + }); + } fn frame_stats(&mut self) -> FrameRate { let (fps, min, low) = self.snapshot.frame; FrameRate { fps, min, low } diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs index 8c6c9d451..0be4fa47d 100644 --- a/crates/horizon-mods/tests/sandbox.rs +++ b/crates/horizon-mods/tests/sandbox.rs @@ -633,6 +633,32 @@ fn render_zoom_is_clamped_and_the_strongest_counts() { assert_eq!(zoom(&mut mods, "x 0 1"), None); } +#[test] +fn render_minimap_is_clamped_and_hidden() { + let mut mods = load("horizon_mods_test_ui_guest.hmod"); + let map = |mods: &mut Mods, args: &str| { + assert!(mods.command(&format!("minimap {args}"))); + mods.minimap() + .map(|m| (m.corner, m.size, m.blocks_per_pixel, m.rotate, m.round)) + }; + assert!(mods.minimap().is_none()); + let corner = horizon_mods::RenderCorner::BottomLeft; + assert_eq!( + map(&mut mods, "96 2 1 0"), + Some((corner, 96.0, 2.0, true, false)) + ); + // The side and the scale are clamped; NaN takes the smallest. + assert_eq!( + map(&mut mods, "999 0.1 0 1"), + Some((corner, 256.0, 0.5, false, true)) + ); + assert_eq!( + map(&mut mods, "x 9 0 0"), + Some((corner, 16.0, 4.0, false, false)) + ); + assert_eq!(map(&mut mods, "off"), None); +} + #[test] fn corner_panels_text_width_and_readings() { let mut mods = load("horizon_mods_test_ui_guest.hmod"); diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs index 9bede11f9..3d4c66076 100644 --- a/crates/horizon-mods/tests/ui_guest/src/lib.rs +++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs @@ -96,6 +96,7 @@ impl Mod for Guest { "input_held", "input_wheel", "zoom", + "minimap", "corner", "readings", ] @@ -198,6 +199,24 @@ impl Mod for Guest { turn, }); } + // `minimap off`, or `minimap SIZE BLOCKS-PER-PIXEL ROTATE ROUND`. + "minimap" => { + let words: Vec<&str> = args.split(' ').collect(); + let number = |i: usize| { + words + .get(i) + .and_then(|w| w.parse().ok()) + .unwrap_or(f32::NAN) + }; + let map = (args != "off").then(|| render::Minimap { + corner: render::Corner::BottomLeft, + size: number(0), + blocks_per_pixel: number(1), + rotate: words.get(2) == Some(&"1"), + round: words.get(3) == Some(&"1"), + }); + render::set_minimap(map); + } // Clamped to (1, 10); the two after it shake nothing. "render_shake" => { render::shake(2.0, 99.0); diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md index a51fb904b..14c815958 100644 --- a/docs/api/mods-reference.md +++ b/docs/api/mods-reference.md @@ -390,6 +390,16 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun | `smooth` | `bool` | Ease in and out through the game's field-of-view easing, as the spyglass does, instead of at once. | | `turn` | `f32` | Mouse turning is multiplied by it while zoomed: 1 keeps the player's sensitivity, at least 0.05. | +### record `minimap` + +| Field | Type | | +| --- | --- | --- | +| `corner` | `corner` | | +| `size` | `f32` | Its side in GUI pixels, 16 to 256. | +| `blocks-per-pixel` | `f32` | World blocks per map pixel, 0.5 to 4; the map is 128 × 128 pixels. | +| `rotate` | `bool` | 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. | +| `round` | `bool` | Round, the corners left clear; otherwise square. | + | Function | Signature | What it does | | --- | --- | --- | | `set-hud` | `func(shapes: list)` | 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. | @@ -400,6 +410,7 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun | `text-width` | `func(text: string) -> f32` | 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. | | `frame-stats` | `func() -> frame-rate` | The game's frame counter, recomputed twice a second. | | `set-zoom` | `func(zoom: zoom)` | 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-minimap` | `func(minimap: option)` | 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. | ## `events` diff --git a/docs/api/stability.md b/docs/api/stability.md index d5bd0e545..5c1b32362 100644 --- a/docs/api/stability.md +++ b/docs/api/stability.md @@ -114,3 +114,7 @@ Deprecations and breaking changes are in bold. The release notes of the game rel keys may consume too is decided before `input` becomes preview. - **`input`'s `wheel` event** is a new case in a variant the game sends, so it breaks mods built before it (allowed because `input` is experimental): an `input` mod that calls `poll` needs a rebuild against the new WIT. +- **`render.set-minimap`** draws a map the game makes, not one a mod composes: reading the blocks around the player + for a map image costs too much through hook calls, so the game keeps the tiles (vanilla's map colours) and the mod + picks the corner, side, scale and shape. One map shows at a time, the first loaded mod's. It is a new function and a + new type, so mods built before it keep loading. diff --git a/docs/mods.md b/docs/mods.md index 556a77187..b94aac089 100644 --- a/docs/mods.md +++ b/docs/mods.md @@ -89,7 +89,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3. | `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of up to 64 files, 4 MiB total, at most 1 MiB written per call | | `command` | `command` | `run(line)`: a vanilla command run as the player, with the player's permissions, after the hook returns (8 per call); mods' own commands are not run | | `ui` | `ui` | `open-screen`, `close-screen`, `set-settings`: a screen the mod owns and a page in Options > Mods, of text, button, item and list widgets the game lays out and draws with its own menus' code. **Experimental:** the manifest needs `experimental = ["ui"]` | -| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects; `set-zoom(zoom)`: the field of view divided by up to 10, eased or at once, with slower turning, while playing and not through a spyglass (the strongest of several mods' zooms counts). The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` | +| `render` | `render` | `set-hud(shapes)`: up to 1024 fills, four-cornered shapes, GUI sprites, items and text, kept on the HUD (over the hotbar, under chat and screens, hidden with F1) until replaced; `set-corner(corner, w, h, shapes)`: a box the game places in a corner, stacked with its overlays and other panels, as `hud`'s panels are; `text-width(text)`; `frame-stats()`: the game's FPS, min and 1% low; `gui-size()`; `shake(strength, seconds)`: the view turns, the player doesn't, scaled by Distortion Effects; `set-zoom(zoom)`: the field of view divided by up to 10, eased or at once, with slower turning, while playing and not through a spyglass (the strongest of several mods' zooms counts); `set-minimap(minimap)`: a map of the world around the player in a corner, as a map item colours it (the floor underground and under roofs), square or round, turning with the player or north up, with the player's arrow; the game keeps its tiles within its own frame budget (one map at a time, the first loaded mod's). The game's own HUD renderer draws them: a mod never supplies shader code. **Experimental:** `experimental = ["render"]` | | `input` | `input` | `claim-items(ids)`: the use button on those items is the mod's (`use-start`, `use-stop` with the ticks held; the game doesn't place, eat or swing); `register-key(name, label, key)`: up to 16 keys (`key.keyboard.r`), heard while playing as `key-down` / `key-up` (the game's own mapping on that key still runs; a screen opening lets held keys up), mouse buttons as `key.mouse.4`. The player rebinds them on the mod's page in Options > Mods, where the game lists them first as Key Binds rows (click, then press a key or mouse button; Esc binds none), even for a mod without `ui`; the choice is kept in `horizon-mods.txt` (`key..:key.keyboard.z`) and wins over `register-key`'s default; `claim-wheel(on)`: the wheel's steps become `wheel` events and the hotbar doesn't move (the one input a mod takes from the game; a mod's keys never do); `held()`; `mapping(name)`: a movement or click mapping's key label and whether it is held; `clicks-per-second()`; `poll()` returns the events, at most 256 kept. **Experimental:** `experimental = ["input"]` | | Hook (export) | When |