From 48db367d4a32e7ad5ee6bfa51765052c375d25d9 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Mon, 26 Oct 2026 03:09:29 +0100 Subject: [PATCH 1/2] Mod API: zoom the camera, take the mouse wheel (render, input) render.set-zoom divides the field of view by up to 10, eased through the game's FOV easing or at once, with a turning scale (at least 0.05); only while playing, and the spyglass's own view wins. The strongest of several mods' zooms counts, and the built-in zoom keeps working beside it. input.claim-wheel takes the wheel from the hotbar while playing: its steps are the mod's wheel events. That is the one input a mod consumes; its keys never do (docs/api/stability.md). A screen opening now lets the mod's held keys up, and mod keys bound to mouse buttons (key.mouse.4) are heard. Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/game.rs | 2 + crates/horizon-client/src/game/extras.rs | 27 +++++--- crates/horizon-client/src/game/mod_input.rs | 62 ++++++++++++++++- crates/horizon-client/src/game/mods.rs | 4 ++ crates/horizon-mod-sdk/wit/horizon.wit | 25 ++++++- crates/horizon-mods/src/manifest.rs | 4 +- crates/horizon-mods/src/runtime.rs | 68 ++++++++++++++++++- crates/horizon-mods/tests/sandbox.rs | 50 ++++++++++++++ crates/horizon-mods/tests/ui_guest/src/lib.rs | 21 +++++- docs/api/mods-reference.md | 17 ++++- docs/api/stability.md | 13 +++- docs/mods.md | 4 +- 12 files changed, 273 insertions(+), 24 deletions(-) diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index 5b04d8716..508122bca 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -10995,6 +10995,7 @@ impl ApplicationHandler for Game<'_> { if self.screen == Screen::Playing && self.sleeping.is_none() && self.player.is_some() + && !self.mod_wheel(d) && !self.extras_scroll(d) && let Some((wheel, (_, vertical_steps))) = self.mouse @@ -11165,6 +11166,7 @@ impl ApplicationHandler for Game<'_> { return Ok(()); } self.extras_mouse(button, pressed); + self.mod_mouse_key(button, pressed); match self.settings.keys.translate_mouse(button) { Some(Err(b)) => self.play_mouse(b, pressed)?, Some(Ok(k)) if pressed => { diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs index 4664f0c6f..1978d003f 100644 --- a/crates/horizon-client/src/game/extras.rs +++ b/crates/horizon-client/src/game/extras.rs @@ -229,25 +229,34 @@ impl Game<'_> { fn zoom_factor(&self) -> f32 { self.extras.zoom.factor(self.scoping()) } + /// The zoom in effect, the extra's or a mod's (`render.set-zoom`), + /// whichever is stronger: (factor, smooth, turning scale). + fn zoom_now(&self) -> (f32, bool, f64) { + let factor = self.zoom_factor(); + let e = &self.settings.extras; + let own = (factor, e.zoom_smooth, turn_scale(factor, e.zoom_sensitivity)); + match self.mod_zoom() { + Some(z) if z.factor > factor => (z.factor, z.smooth, f64::from(z.turn)), + _ => own, + } + } /// The field-of-view modifier target, divided by a smooth zoom. pub(super) fn zoomed_fov_target(&self, vanilla: f32) -> f32 { - if self.settings.extras.zoom_smooth { - fov_target(vanilla, self.zoom_factor()) - } else { - vanilla + match self.zoom_now() { + (factor, true, _) => fov_target(vanilla, factor), + _ => vanilla, } } /// The field of view in degrees, divided by an instant zoom. pub(super) fn zoomed_fov_degrees(&self, fov: f32) -> f32 { - if self.settings.extras.zoom_smooth { - fov - } else { - fov / self.zoom_factor() + match self.zoom_now() { + (factor, false, _) => fov / factor, + _ => fov, } } /// Mouse turning while zoomed. pub(super) fn zoom_turn_scale(&self) -> f64 { - turn_scale(self.zoom_factor(), self.settings.extras.zoom_sensitivity) + self.zoom_now().2 } /// The FPS counter and keystrokes, in the HUD layer (hidden with F1 by /// the caller). The top left corner gives way to the debug screen. diff --git a/crates/horizon-client/src/game/mod_input.rs b/crates/horizon-client/src/game/mod_input.rs index ac80e8e42..199669957 100644 --- a/crates/horizon-client/src/game/mod_input.rs +++ b/crates/horizon-client/src/game/mod_input.rs @@ -1,6 +1,7 @@ //! Capability `input` (docs/mods.md): the use button on items a mod claims, -//! and the mod's own keys. With no mod claiming items or keys, each hook -//! here returns after one check. +//! the mod's own keys and the mouse wheel; and `render`'s zoom. With no mod +//! claiming items, keys or the wheel, each hook here returns after one +//! check. use super::Game; use winit::{event::MouseButton, keyboard::KeyCode}; #[cfg(feature = "mods")] @@ -20,6 +21,21 @@ impl Game<'_> { false } pub(super) fn mod_key(&mut self, _key: KeyCode, _pressed: bool, _repeat: bool) {} + pub(super) fn mod_mouse_key(&mut self, _button: MouseButton, _pressed: bool) {} + pub(super) fn mod_wheel(&mut self, _steps: f32) -> bool { + false + } + pub(super) fn mod_zoom(&self) -> Option { + None + } +} + +/// A mod's zoom (`render.set-zoom`), clamped by the runtime. +#[derive(Clone, Copy)] +pub(super) struct ModZoom { + pub(super) factor: f32, + pub(super) smooth: bool, + pub(super) turn: f32, } #[cfg(feature = "mods")] @@ -89,4 +105,46 @@ impl Game<'_> { self.mods.mods.key(name, pressed); } } + /// A mouse button while playing: a mod's key bound to it + /// (`key.mouse.4`...), as `mod_key`. + pub(super) fn mod_mouse_key(&mut self, button: MouseButton, pressed: bool) { + if self.mods.mods.has_keys() { + let name = horizon_client::keybinds::mouse_name(button); + self.mods.mods.key(&name, pressed); + } + } + /// Wheel steps while playing: true when a mod holds the wheel, so the + /// hotbar doesn't move. + pub(super) fn mod_wheel(&mut self, steps: f32) -> bool { + self.mods.mods.wheel(steps) + } + /// Playing, with nothing over the world: mods' keys and zoom apply. + fn mod_playing(&self) -> bool { + self.screen == Screen::Playing + && self.title.is_none() + && self.sign_edit.is_none() + && self.book.is_none() + } + /// Once a frame, before the mods run: a screen that opened lets their + /// held keys up. + pub(super) fn mod_input_frame(&mut self) { + let playing = self.mod_playing(); + if self.mods.playing && !playing { + self.mods.mods.release_keys(); + } + self.mods.playing = playing; + } + /// The strongest zoom a mod asks for, while playing; the spyglass's + /// own view wins. + pub(super) fn mod_zoom(&self) -> Option { + if !self.mod_playing() || self.scoping() { + return None; + } + let z = self.mods.mods.zoom()?; + Some(ModZoom { + factor: z.factor, + smooth: z.smooth, + turn: z.turn, + }) + } } diff --git a/crates/horizon-client/src/game/mods.rs b/crates/horizon-client/src/game/mods.rs index 9d6015ad7..63e6314fd 100644 --- a/crates/horizon-client/src/game/mods.rs +++ b/crates/horizon-client/src/game/mods.rs @@ -55,6 +55,9 @@ pub(super) struct ModsState { /// The HUD font's advances for `render.text-width`, made once. #[cfg(feature = "mods")] font_widths: std::sync::Arc<[f32]>, + /// Playing at the last frame, for `mod_input_frame`. + #[cfg(feature = "mods")] + pub(super) playing: bool, } /// The mappings `input.mapping` answers for, with the default key their @@ -399,6 +402,7 @@ impl Game<'_> { if !self.mods.mods.is_running() { return; } + self.mod_input_frame(); if self.mods.mods.wants_frames() { let snapshot = self.mod_snapshot(); self.mods.mods.set_snapshot(snapshot); diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit index b787ff675..5cee9ef51 100644 --- a/crates/horizon-mod-sdk/wit/horizon.wit +++ b/crates/horizon-mod-sdk/wit/horizon.wit @@ -199,9 +199,13 @@ interface input { /// 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. + /// 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. @@ -214,6 +218,10 @@ interface input { 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`. @@ -331,6 +339,21 @@ interface render { } /// 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); } /// What the game calls. Only the hooks `init` asks for are ever called. diff --git a/crates/horizon-mods/src/manifest.rs b/crates/horizon-mods/src/manifest.rs index 9e998dae1..4dfd9af51 100644 --- a/crates/horizon-mods/src/manifest.rs +++ b/crates/horizon-mods/src/manifest.rs @@ -132,9 +132,9 @@ impl Capability { Capability::Storage => "save its own settings to disk", Capability::Registries => "add blocks and items to your worlds", Capability::Ui => "show its own screens and a settings page", - Capability::Render => "draw on your screen and shake the camera", + Capability::Render => "draw on your screen, shake and zoom the camera", Capability::Input => { - "see the keys you hold and your clicks, take over the use button on its own items, and add keys" + "see the keys you hold and your clicks, take over the use button on its own items and the mouse wheel, and add keys" } } } diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs index f33839fe7..538b7edd5 100644 --- a/crates/horizon-mods/src/runtime.rs +++ b/crates/horizon-mods/src/runtime.rs @@ -53,7 +53,7 @@ pub use render_bindings::horizon::mods::input::{Event as InputEvent, HeldItem, I /// 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, + Rect as RenderRect, Shape, SpriteShape, TextShape, Zoom as ModZoom, }; use render_bindings::{RenderHost, horizon::mods::render}; @@ -189,6 +189,8 @@ struct State { shapes: Vec, /// Capability `render`'s corner panel. corner: Option, + /// Capability `render`'s zoom, when the mod zooms. + zoom: Option, input: InputState, /// Capability `storage`'s folder; made on first `set`. data_dir: PathBuf, @@ -331,6 +333,7 @@ impl Mods { ui: UiState::default(), shapes: Vec::new(), corner: None, + zoom: None, input: InputState::default(), data_dir, storage_budget: STORAGE_WRITE_BUDGET, @@ -587,6 +590,16 @@ impl Mods { .map(|k| k.name.clone()) .collect(); for name in names { + let held = input.down.iter().position(|n| *n == name); + match (down, held) { + (true, None) => input.down.push(name.clone()), + (false, Some(i)) => { + input.down.swap_remove(i); + } + // Already let go when a screen opened. + (false, None) => continue, + (true, Some(_)) => {} + } input.push(if down { InputEvent::KeyDown(name) } else { @@ -595,6 +608,35 @@ impl Mods { } } } + /// A screen opened, or the game stopped playing: every mod key held + /// lets go (`key-up`), so a key needs a new press afterwards. + pub fn release_keys(&mut self) { + for run in self.entries.iter_mut().filter_map(|e| e.run.as_mut()) { + let input = &mut run.store.data_mut().input; + for name in std::mem::take(&mut input.down) { + input.push(InputEvent::KeyUp(name)); + } + } + } + /// Some running mod holds the mouse wheel. + pub fn wheel_claimed(&self) -> bool { + self.inputs().any(|i| i.wheel) + } + /// Wheel steps while playing: `wheel` to the mods holding it; false + /// when none does (the hotbar takes them). + pub fn wheel(&mut self, steps: f32) -> bool { + let event = InputEvent::Wheel(steps); + let claimed = self.wheel_claimed(); + self.push_input(|i| i.wheel, &event); + claimed + } + /// The strongest zoom a running mod asks for (capability `render`). + pub fn zoom(&self) -> Option { + self.entries + .iter() + .filter_map(|e| e.run.as_ref()?.store.data().zoom) + .max_by(|a, b| a.factor.total_cmp(&b.factor)) + } fn inputs(&self) -> impl Iterator { self.entries .iter() @@ -824,6 +866,10 @@ struct InputState { claimed: Vec, keys: Vec, events: std::collections::VecDeque, + /// The mod's keys held now, by name. + down: Vec, + /// It holds the mouse wheel. + wheel: bool, } /// Events kept for `poll`, items claimed and keys, per mod. const INPUT_EVENTS: usize = 256; @@ -889,12 +935,19 @@ impl input::Host for State { fn clicks_per_second(&mut self) -> (u32, u32) { self.snapshot.cps } + fn claim_wheel(&mut self, on: bool) { + self.input.wheel = on; + } } /// HUD shapes one mod may keep (capability `render`). const SHAPES: usize = 1024; /// The longest jolt `render.shake` makes, in seconds. const SHAKE_SECONDS: f32 = 10.0; +/// `render.set-zoom`'s limits: `Camera.tickFov` keeps the modifier at 0.1 +/// or more, and turning never stops. +const ZOOM_MAX: f32 = 10.0; +const TURN_MIN: f32 = 0.05; /// A mod's corner panel: shapes in a `width` × `height` box the game /// places in `corner`, stacked with the other overlays. @@ -963,6 +1016,19 @@ impl render::Host for State { .sum::() .ceil() } + fn set_zoom(&mut self, zoom: ModZoom) { + let finite = |v: f32, lo: f32, hi: f32| if v.is_finite() { v.clamp(lo, hi) } else { lo }; + let factor = finite(zoom.factor, 1.0, ZOOM_MAX); + self.zoom = (factor > 1.0).then(|| ModZoom { + factor, + smooth: zoom.smooth, + turn: if zoom.turn.is_finite() { + zoom.turn.clamp(TURN_MIN, 1.0) + } else { + 1.0 + }, + }); + } 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 a9de4f55b..780899289 100644 --- a/crates/horizon-mods/tests/sandbox.rs +++ b/crates/horizon-mods/tests/sandbox.rs @@ -506,6 +506,56 @@ fn input_claims_keys_and_events() { }); assert!(mods.command("input_held")); assert_eq!(chat(&mut mods), ["holding minecraft:stick x3 in 2"]); + // A screen opening lets held keys up, once; the release that follows + // is not sent again. + mods.key("key.keyboard.r", true); + mods.release_keys(); + mods.release_keys(); + mods.key("key.keyboard.r", false); + assert!(mods.command("input_poll")); + assert_eq!(chat(&mut mods), ["key-down wheel", "key-up wheel"]); +} + +#[test] +fn input_wheel_is_the_mods_while_claimed() { + let mut mods = load("horizon_mods_test_ui_guest.hmod"); + let chat = |mods: &mut Mods| -> Vec { + mods.drain() + .into_iter() + .filter_map(|o| match o { + Output::Chat { text, .. } => Some(text), + _ => None, + }) + .collect() + }; + // Unclaimed, the hotbar keeps the wheel and the mod hears nothing. + assert!(!mods.wheel_claimed() && !mods.wheel(1.0)); + assert!(mods.command("input_wheel")); + assert!(mods.wheel_claimed()); + assert!(mods.wheel(1.0) && mods.wheel(-2.0)); + assert!(mods.command("input_poll")); + assert_eq!(chat(&mut mods), ["wheel 1", "wheel -2"]); + assert!(mods.command("input_wheel off")); + assert!(!mods.wheel(1.0)); +} + +#[test] +fn render_zoom_is_clamped_and_the_strongest_counts() { + let mut mods = load("horizon_mods_test_ui_guest.hmod"); + let zoom = |mods: &mut Mods, args: &str| { + assert!(mods.command(&format!("zoom {args}"))); + mods.zoom().map(|z| (z.factor, z.smooth, z.turn)) + }; + assert!(mods.zoom().is_none()); + assert_eq!(zoom(&mut mods, "4 1 0.25"), Some((4.0, true, 0.25))); + // Over 10 and a turn under 0.05 are clamped. + assert_eq!(zoom(&mut mods, "50 0 0"), Some((10.0, false, 0.05))); + // A NaN turn keeps the player's sensitivity. + assert_eq!(zoom(&mut mods, "2 0 x"), Some((2.0, false, 1.0))); + // 1, under 1 and NaN end the zoom. + assert_eq!(zoom(&mut mods, "1 0 1"), None); + assert_eq!(zoom(&mut mods, "0.5 0 1"), None); + assert_eq!(zoom(&mut mods, "x 0 1"), None); } #[test] diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs index ae6e4dfc4..1555b44f0 100644 --- a/crates/horizon-mods/tests/ui_guest/src/lib.rs +++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs @@ -2,7 +2,8 @@ //! of each widget, `/ui_settings` sets a settings page, `/ui_close` closes //! the screen; the `ui-events` calls answer in chat so the host sees them. //! `/render_hud`, `/render_clear` and `/render_shake` test `render`; -//! `/input_claim`, `/input_poll` and `/input_held` test `input`; +//! `/input_claim`, `/input_poll`, `/input_held` and `/input_wheel` test +//! `input`; `/zoom FACTOR SMOOTH TURN` tests `render.set-zoom`; //! `/corner` and `/readings` the calls the official extras mods use. use horizon_mod_sdk::{ Mod, Registration, chat, @@ -93,6 +94,8 @@ impl Mod for Guest { "input_claim", "input_poll", "input_held", + "input_wheel", + "zoom", "corner", "readings", ] @@ -100,7 +103,7 @@ impl Mod for Guest { .fold(Registration::new(), Registration::command); Ok((Guest, hooks)) } - fn command(&mut self, name: &str, _args: &str) -> Result, String> { + fn command(&mut self, name: &str, args: &str) -> Result, String> { match name { "ui_screen" => ui::open_screen(&Screen { title: "Guest's screen".into(), @@ -167,6 +170,7 @@ impl Mod for Guest { Event::UseStop(u) => format!("use-stop {} {}", u.item.id, u.ticks), Event::KeyDown(k) => format!("key-down {k}"), Event::KeyUp(k) => format!("key-up {k}"), + Event::Wheel(steps) => format!("wheel {steps}"), }); } } @@ -176,6 +180,19 @@ impl Mod for Guest { }); chat::show(&format!("holding {held}")); } + "input_wheel" => input::claim_wheel(args != "off"), + "zoom" => { + let mut words = args.split(' '); + let mut number = || words.next().and_then(|w| w.parse().ok()).unwrap_or(f32::NAN); + let factor = number(); + let smooth = number() == 1.0; + let turn = number(); + render::set_zoom(render::Zoom { + factor, + smooth, + turn, + }); + } // 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 333b65bd0..209a8298d 100644 --- a/docs/api/mods-reference.md +++ b/docs/api/mods-reference.md @@ -13,8 +13,8 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`, | `storage` | [`storage`](#storage) | save its own settings to disk | | `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds | | `ui` | [`ui`](#ui) | show its own screens and a settings page | -| `render` | [`render`](#render) | draw on your screen and shake the camera | -| `input` | [`input`](#input) | see the keys you hold and your clicks, take over the use button on its own items, and add keys | +| `render` | [`render`](#render) | draw on your screen, shake and zoom the camera | +| `input` | [`input`](#input) | see the keys you hold and your clicks, take over the use button on its own items and the mouse wheel, and add keys | ## World `horizon-mod` @@ -251,8 +251,9 @@ The main hand's stack. | --- | --- | --- | | `use-start` | `item-use` | 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-stop` | `item-use` | It came up again, or the item left the hand, or a screen opened. | -| `key-down` | `string` | A key `register-key` named went down or up while playing (no screen open). The game's own mapping on that key still runs. | +| `key-down` | `string` | 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-up` | `string` | | +| `wheel` | `f32` | Mouse wheel steps while the mod holds the wheel (`claim-wheel`): positive away from the player, as the hotbar reads them. | ### record `mapping-state` @@ -269,6 +270,7 @@ A mapping as the player has bound it. | `register-key` | `func(name: string, label: string, key: string) -> result<_, string>` | 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`). At most 16; an unknown key is an error. | | `held` | `func() -> option` | The main hand's stack, as of this tick; none when it is empty. | | `poll` | `func() -> list` | The events since the last call, oldest first. | +| `claim-wheel` | `func(on: bool)` | 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. | | `mapping` | `func(name: string) -> option` | 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. | | `clicks-per-second` | `func() -> tuple` | Clicks of the attack and use buttons in the last second. | @@ -369,6 +371,14 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun | `min` | `u32` | The slowest frame's rate, and the 1% low (the 99th percentile frame time's rate), over the last 5 seconds. | | `low` | `u32` | | +### record `zoom` + +| Field | Type | | +| --- | --- | --- | +| `factor` | `f32` | The field of view is divided by it: 1 is none, at most 10. | +| `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. | + | 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. | @@ -378,6 +388,7 @@ Any four-cornered shape (a wheel's segment, an arrow): the corners in order roun | `clear-corner` | `func()` | Removes the mod's corner panel. | | `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. | ## `events` diff --git a/docs/api/stability.md b/docs/api/stability.md index b513d5ddf..485d805af 100644 --- a/docs/api/stability.md +++ b/docs/api/stability.md @@ -88,8 +88,8 @@ Deprecations and breaking changes are in bold. The release notes of the game rel | --- | --- | --- | | Mod API: `log`, `game`, `chat`, `hud`, `storage`, `events` | preview | 0.1.0 | | Mod API: `ui`, `ui-events` (a mod's screens and settings page) | experimental | manifest `experimental = ["ui"]` | -| Mod API: `render` (HUD shapes, camera shake; drawn by the game, no mod shaders) | experimental | manifest `experimental = ["render"]` | -| Mod API: `input` (claimed items' use, the mod's keys) | experimental | manifest `experimental = ["input"]` | +| Mod API: `render` (HUD shapes, camera shake and zoom; drawn by the game, no mod shaders) | experimental | manifest `experimental = ["render"]` | +| Mod API: `input` (claimed items' use, the mod's keys, the mouse wheel) | experimental | manifest `experimental = ["input"]` | | Content mods (`registries`: data-driven blocks and items) | preview | manifest `api = "0.2"` | | Server mods (events, world, server commands) | not started | manifest `api = "0.3"`, experimental first | | Script mods (Lua run by an interpreter mod, [mods.md](mods.md#ways-in)) | not started | | @@ -104,3 +104,12 @@ Deprecations and breaking changes are in bold. The release notes of the game rel | Telemetry batch and consent | stable | `"schema": 1`, consent `2` | | `horizon-graphics.txt`, `horizon-extras.txt`, `horizon-mods.txt` | preview | none | | `SHA256SUMS` and `SHA256SUMS.sig` | stable | | + +### The experimental mod APIs' choices + +- **What a mod may take from the game.** `input.claim-wheel` is the one input a mod consumes: while it holds the + wheel, the steps are its `wheel` events and the hotbar doesn't move. `claim-items` takes the use button only on the + items it names. A mod's keys (`register-key`) never consume: vanilla's mapping on the same key still runs. Whether + 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. diff --git a/docs/mods.md b/docs/mods.md index d92c88fa6..9a75badb6 100644 --- a/docs/mods.md +++ b/docs/mods.md @@ -87,8 +87,8 @@ folder, loads no runtime and plays exactly like vanilla 26.3. | `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters | | `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 | | `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. 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); `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"]` | +| `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"]` | +| `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`; `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 | |---|---| From de294e34bbddb7bb2e8dc48c86efe1c662421e53 Mon Sep 17 00:00:00 2001 From: Ludovic Marie <136255825+ludovic111@users.noreply.github.com> Date: Mon, 26 Oct 2026 04:19:07 +0100 Subject: [PATCH 2/2] rustfmt Co-Authored-By: Claude Opus 5.5 --- crates/horizon-client/src/game/extras.rs | 6 +++++- crates/horizon-mods/tests/ui_guest/src/lib.rs | 7 ++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs index 1978d003f..a04196b69 100644 --- a/crates/horizon-client/src/game/extras.rs +++ b/crates/horizon-client/src/game/extras.rs @@ -234,7 +234,11 @@ impl Game<'_> { fn zoom_now(&self) -> (f32, bool, f64) { let factor = self.zoom_factor(); let e = &self.settings.extras; - let own = (factor, e.zoom_smooth, turn_scale(factor, e.zoom_sensitivity)); + let own = ( + factor, + e.zoom_smooth, + turn_scale(factor, e.zoom_sensitivity), + ); match self.mod_zoom() { Some(z) if z.factor > factor => (z.factor, z.smooth, f64::from(z.turn)), _ => own, diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs index 1555b44f0..9bede11f9 100644 --- a/crates/horizon-mods/tests/ui_guest/src/lib.rs +++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs @@ -183,7 +183,12 @@ impl Mod for Guest { "input_wheel" => input::claim_wheel(args != "off"), "zoom" => { let mut words = args.split(' '); - let mut number = || words.next().and_then(|w| w.parse().ok()).unwrap_or(f32::NAN); + let mut number = || { + words + .next() + .and_then(|w| w.parse().ok()) + .unwrap_or(f32::NAN) + }; let factor = number(); let smooth = number() == 1.0; let turn = number();