Mod API: capability render (experimental): HUD shapes and camera shake

Mods draw through the game's own renderer, never their own shaders:

- WIT `render`: set-hud(shapes) with fill, quad (any four corners),
  sprite (the game's GUI sprites), item (scaled) and text shapes, up
  to 1024, kept until replaced; gui-size(); shake(strength, seconds).
- Drawn over the HUD after the extras, under chat and screens, hidden
  with F1 (game/mod_render.rs). Colours are 0xAARRGGBB.
- shake turns the view, not the player: jolts fade out squared, add up
  to 1, at most 3 degrees of yaw and 2 of pitch, scaled by Distortion
  Effects (screenEffectScale; 0 turns it off).
- Experimental: the manifest needs experimental = ["render"].
- No mod drawing, no cost: an empty iterator and an is_empty check.
- cargo horizon-mod check reports shakes and HUD shapes. The ui test
  guest gains /render_hud, /render_clear and /render_shake, with a
  sandbox test; HudBatch gets fill_quad.
- Docs: mods.md, stability.md, the changelog, the regenerated reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-25 21:35:12 +01:00
parent befec1995f
commit 61c44c22ef
15 changed files with 582 additions and 14 deletions
+9
View File
@@ -198,6 +198,8 @@ fn play(path: &Path, report: &mut Report) -> Result<(), String> {
game_time: t,
day_time: 1000 + t,
}),
// The GUI of a 1280 x 720 window at scale 3.
gui_size: (427.0, 240.0),
});
mods.tick(t);
for _ in 0..FRAMES_PER_TICK {
@@ -217,8 +219,15 @@ fn play(path: &Path, report: &mut Report) -> Result<(), String> {
Output::Stopped { reason, .. } => return Err(format!("it stopped: {reason}")),
Output::OpenScreen { .. } => "opened a screen".to_string(),
Output::CloseScreen { .. } => "closed its screen".to_string(),
Output::Shake { strength, seconds } => {
format!("shook the camera: {strength:.2} for {seconds:.1} s")
}
});
}
let shapes = mods.hud_shapes().count();
if shapes > 0 {
report.output.push(format!("drew {shapes} HUD shape(s)"));
}
match failed(&mods) {
Some(reason) => Err(format!("it stopped: {reason}")),
None => Ok(()),
+3
View File
@@ -96,6 +96,7 @@ mod maps;
mod minecarts;
mod mob_blocks;
mod mob_gear;
mod mod_render;
mod mods;
mod mount_menu;
mod mounts;
@@ -4894,6 +4895,7 @@ impl Game<'_> {
// Hud: the action bar and titles draw over the hotbar (nextStratum).
self.draw_boss_bars(&mut batch);
self.draw_extras(&mut batch);
self.draw_mod_shapes(&mut batch);
}
if show_hud {
// Hud.nextContextualInfoState: the jump bar, the experience bar or
@@ -9865,6 +9867,7 @@ impl Game<'_> {
self.pitch,
),
};
let (view_yaw, view_pitch) = self.shaken_view(view_yaw, view_pitch);
self.audio
.set_listener([camera.x, camera.y, camera.z], view_yaw, view_pitch);
let block = [
@@ -0,0 +1,176 @@
//! Capability `render` (docs/mods.md): the shapes mods keep on the HUD,
//! drawn by the game's own HUD renderer, and their camera shakes. Mods
//! never supply shader code. With no mod drawing, each hook here returns
//! after one check.
use super::Game;
use horizon_client::hud::HudBatch;
#[cfg(feature = "mods")]
use {
horizon_client::{hud::rgba, items::ItemStack, text::Text},
horizon_mods::Shape,
std::time::Instant,
};
/// The camera's jolts from `render.shake`, while any is fading.
#[cfg(feature = "mods")]
#[derive(Default)]
pub(super) struct Shake {
jolts: Vec<Jolt>,
}
#[cfg(feature = "mods")]
struct Jolt {
start: Instant,
strength: f32,
seconds: f32,
}
/// The HUD batch's colour (ABGR) from a mod's 0xAARRGGBB.
#[cfg(feature = "mods")]
fn argb(color: u32) -> u32 {
let [a, r, g, b] = color.to_be_bytes();
rgba(r, g, b, a)
}
/// The view's turn at full strength, in degrees: yaw, then pitch.
#[cfg(feature = "mods")]
const SHAKE_DEGREES: (f32, f32) = (3.0, 2.0);
#[cfg(feature = "mods")]
impl Shake {
pub(super) fn add(&mut self, strength: f32, seconds: f32) {
self.jolts.push(Jolt {
start: Instant::now(),
strength,
seconds,
});
}
/// How far the view turns now (yaw, pitch degrees), `scale` being the
/// player's Distortion Effects; fades jolts out and forgets ended ones.
fn offset(&mut self, now: Instant, scale: f32) -> (f32, f32) {
self.jolts
.retain(|j| now.duration_since(j.start).as_secs_f32() < j.seconds);
let mut strength = 0.0;
for j in &self.jolts {
let left = 1.0 - now.duration_since(j.start).as_secs_f32() / j.seconds;
strength += j.strength * left * left;
}
let strength = strength.min(1.0) * scale.clamp(0.0, 1.0);
if strength <= 0.0 {
return (0.0, 0.0);
}
// Smooth noise: sines at unrelated rates, so it never repeats visibly.
let t = self
.jolts
.first()
.map_or(0.0, |j| now.duration_since(j.start).as_secs_f32());
let wave = |a: f32, b: f32, c: f32| {
((t * a).sin() * 0.5 + (t * b).sin() * 0.3 + (t * c).sin() * 0.2).clamp(-1.0, 1.0)
};
(
strength * SHAKE_DEGREES.0 * wave(23.0, 37.3, 51.7),
strength * SHAKE_DEGREES.1 * wave(29.1, 43.9, 61.3),
)
}
}
#[cfg(not(feature = "mods"))]
impl Game<'_> {
pub(super) fn draw_mod_shapes(&self, _batch: &mut HudBatch) {}
pub(super) fn shaken_view(&mut self, yaw: f32, pitch: f32) -> (f32, f32) {
(yaw, pitch)
}
}
#[cfg(feature = "mods")]
impl Game<'_> {
/// The running mods' HUD shapes, in order, over the HUD.
pub(super) fn draw_mod_shapes(&self, batch: &mut HudBatch) {
let atlas = &self.gui.atlas;
for shape in self.mods.mods.hud_shapes() {
match shape {
Shape::Fill(f) => {
let r = f.rect;
batch.fill(atlas, r.x, r.y, r.w, r.h, argb(f.color));
}
Shape::Quad(q) => {
let (a, b, c, d) = q.corners;
let corners = [[a.x, a.y], [b.x, b.y], [c.x, c.y], [d.x, d.y]];
batch.fill_quad(atlas, corners, argb(q.color));
}
Shape::Sprite(s) => {
let r = s.rect;
let name = s.sprite.strip_prefix("minecraft:").unwrap_or(&s.sprite);
let name = format!("gui/sprites/{name}");
batch.sprite_scaled(atlas, &name, r.x, r.y, r.w, r.h, argb(s.color));
}
Shape::Item(i) => {
if self.res.items().get(&i.item).is_none() {
continue;
}
let start = batch.vertices.len();
let stack = ItemStack::new(i.item.as_str(), 1);
self.draw_item_model(batch, &stack, i.at.x, i.at.y);
batch.scale_since(start, i.at.x, i.at.y, i.scale, i.scale);
}
Shape::Text(t) => {
let text = Text::literal(t.text.clone());
let x = if t.centered {
t.at.x - (HudBatch::text_width(atlas, &t.text) / 2.0).floor()
} else {
t.at.x
};
batch.text_styled(
atlas,
&text,
x,
t.at.y,
argb(t.color | 0xFF00_0000),
t.shadow,
);
}
}
}
}
/// The view's yaw and pitch after the mods' camera shakes; unchanged
/// while none is fading.
pub(super) fn shaken_view(&mut self, yaw: f32, pitch: f32) -> (f32, f32) {
if self.mods.shake.jolts.is_empty() {
return (yaw, pitch);
}
let scale = self.settings.file.double("screenEffectScale") as f32;
let (dy, dp) = self.mods.shake.offset(Instant::now(), scale);
(yaw + dy, (pitch + dp).clamp(-90.0, 90.0))
}
}
#[cfg(all(test, feature = "mods"))]
mod tests {
use super::*;
use std::time::Duration;
#[test]
fn a_jolt_fades_out_and_distortion_scales_it() {
let mut shake = Shake::default();
shake.add(1.0, 2.0);
let start = shake.jolts[0].start;
let at = |s: f32| start + Duration::from_secs_f32(s);
let size = |(y, p): (f32, f32)| y.abs() + p.abs();
// Off with Distortion Effects at 0, inside the limits otherwise.
assert_eq!(shake.offset(at(0.3), 0.0), (0.0, 0.0));
let (y, p) = shake.offset(at(0.3), 1.0);
assert!(y.abs() <= SHAKE_DEGREES.0 && p.abs() <= SHAKE_DEGREES.1);
// Fading: the largest turn over a window shrinks.
let mut peak = |from: f32| {
(0..50)
.map(|i| size(shake.offset(at(from + i as f32 * 0.002), 1.0)))
.fold(0.0, f32::max)
};
let early = peak(0.1);
let late = peak(1.6);
assert!(late < early, "{late} !< {early}");
// Gone once it ends.
assert_eq!(shake.offset(at(2.1), 1.0), (0.0, 0.0));
assert!(shake.jolts.is_empty());
}
}
+13 -2
View File
@@ -33,7 +33,10 @@ use {
#[derive(Default)]
pub(super) struct ModsState {
#[cfg(feature = "mods")]
mods: Mods,
pub(super) mods: Mods,
/// Capability `render`'s camera shakes.
#[cfg(feature = "mods")]
pub(super) shake: super::mod_render::Shake,
/// `--dev-mod PATH`: always on, reloaded when rebuilt.
pub(super) dev: Vec<PathBuf>,
/// When dev mods were last checked for a rebuild.
@@ -308,7 +311,11 @@ impl Game<'_> {
game_time: self.world.game_time.max(0) as u64,
day_time: self.world.day_time.max(0) as u64,
});
Snapshot { player, clock }
Snapshot {
player,
clock,
gui_size: self.gui_size(),
}
}
/// A game tick.
pub(super) fn tick_mods(&mut self) {
@@ -382,6 +389,10 @@ impl Game<'_> {
self.open_mod_screen(owner, false);
continue;
}
Output::Shake { strength, seconds } => {
self.mods.shake.add(strength, seconds);
continue;
}
Output::CloseScreen { owner } => {
if self.mods.screen.as_ref().is_some_and(|s| s.owner == owner) {
self.close_mod_screen(false);
+6
View File
@@ -835,6 +835,12 @@ impl HudBatch {
r.v1 = cv;
self.rect_uv(x, y, w, h, r, color);
}
/// Any four-cornered shape in one colour, corners in order round it.
pub fn fill_quad(&mut self, atlas: &HudAtlas, corners: [[f32; 2]; 4], color: u32) {
let w = atlas.white;
let uv = [(w.u0 + w.u1) / 2.0, (w.v0 + w.v1) / 2.0];
self.quad(corners, [uv; 4], color);
}
/// GuiGraphics.fillGradient: `top` to `bottom`, down the rectangle.
pub fn fill_gradient(
&mut self,
+1 -1
View File
@@ -38,7 +38,7 @@ wit_bindgen::generate!({
pub use exports::horizon::mods::events::{Guest as __Guest, Registration};
pub use exports::horizon::mods::ui_events::Guest as __UiEventsGuest;
pub use horizon::mods::{chat, game, hud, log, storage, ui};
pub use horizon::mods::{chat, game, hud, log, render, storage, ui};
/// The game's calls into a mod. Only the hooks [`Registration`] asks for
/// are called; the others may stay as their defaults.
+82
View File
@@ -163,6 +163,82 @@ interface ui-events {
settings-opened: func();
}
/// 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 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<point, point, point, point>,
/// 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`, `<mod>:<path>`; 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<shape>);
/// The screen's size in GUI pixels (width, height), as of this tick.
gui-size: func() -> tuple<f32, f32>;
/// 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);
}
/// What the game calls. Only the hooks `init` asks for are ever called.
interface events {
record registration {
@@ -203,6 +279,7 @@ world horizon-mod {
world horizon-ui-mod {
include horizon-mod;
import ui;
import render;
export ui-events;
}
@@ -211,3 +288,8 @@ world ui-host {
import ui;
export ui-events;
}
/// The game's side of capability `render` (imports only).
world render-host {
import render;
}
+9 -2
View File
@@ -84,15 +84,19 @@ pub enum Capability {
/// A screen the mod owns and a settings page in Options > Mods, drawn
/// with the menus' own widgets (interface `ui`, calls `ui-events`).
Ui,
/// Shapes on the HUD and the camera's shake, drawn by the game's own
/// renderer (interface `render`).
Render,
}
impl Capability {
pub const ALL: [Capability; 6] = [
pub const ALL: [Capability; 7] = [
Capability::GameRead,
Capability::Chat,
Capability::Hud,
Capability::Storage,
Capability::Registries,
Capability::Ui,
Capability::Render,
];
/// The WIT interface it grants, in `horizon:mods`.
pub fn interface(self) -> &'static str {
@@ -103,12 +107,13 @@ impl Capability {
Capability::Storage => "storage",
Capability::Registries => "registries",
Capability::Ui => "ui",
Capability::Render => "render",
}
}
/// May change in any release: a mod uses it only with
/// `experimental = ["<name>"]` in its manifest.
pub fn is_experimental(self) -> bool {
matches!(self, Capability::Ui)
matches!(self, Capability::Ui | Capability::Render)
}
/// What the player reads before turning the mod on: "May <this>".
pub fn describe(self) -> &'static str {
@@ -119,6 +124,7 @@ 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",
}
}
/// The capability a component import needs, `Ok(None)` for one every
@@ -150,6 +156,7 @@ impl fmt::Display for Capability {
Capability::Storage => "storage",
Capability::Registries => "registries",
Capability::Ui => "ui",
Capability::Render => "render",
};
f.write_str(name)
}
+81
View File
@@ -40,6 +40,19 @@ pub use ui_bindings::horizon::mods::ui::{
ItemWidget, ListWidget, Screen as UiScreen, TextWidget, Widget as UiWidget,
};
use ui_bindings::{UiHost, horizon::mods::ui};
/// Capability `render`'s imports (docs/mods.md): the game draws the shapes.
mod render_bindings {
wasmtime::component::bindgen!({
path: "../horizon-mod-sdk/wit",
world: "render-host",
});
}
/// What capability `render` asks the game to draw (WIT `interface render`).
pub use render_bindings::horizon::mods::render::{
FillShape, ItemShape, Point as RenderPoint, QuadShape, Rect as RenderRect, Shape, SpriteShape,
TextShape,
};
use render_bindings::{RenderHost, horizon::mods::render};
/// A mod's linear memory cap.
const MEMORY: usize = 64 << 20;
@@ -70,6 +83,8 @@ const STORAGE_WRITE_BUDGET: u64 = 1 << 20;
pub struct Snapshot {
pub player: Option<Player>,
pub clock: Option<Clock>,
/// The screen in GUI pixels (capability `render`'s `gui-size`).
pub gui_size: (f32, f32),
}
/// What mods asked the game to show since the last [`Mods::drain`].
@@ -86,6 +101,8 @@ pub enum Output {
OpenScreen { owner: usize },
/// `ui.close-screen`: the mod closed its own screen (no `closed` back).
CloseScreen { owner: usize },
/// `render.shake`: strength 0 to 1, fading out over `seconds` (≤ 10).
Shake { strength: f32, seconds: f32 },
}
/// A mod's text panel, drawn every frame until it changes.
@@ -153,6 +170,8 @@ struct State {
out: Vec<Output>,
panel: Option<Panel>,
ui: UiState,
/// Capability `render`'s HUD shapes, drawn until replaced.
shapes: Vec<Shape>,
/// Capability `storage`'s folder; made on first `set`.
data_dir: PathBuf,
/// Bytes `storage::set` may still write before this hook call ends
@@ -231,6 +250,8 @@ impl Mods {
.map_err(|e| e.to_string())?;
UiHost::add_to_linker::<State, HasSelf<State>>(&mut linker, |s| s)
.map_err(|e| e.to_string())?;
RenderHost::add_to_linker::<State, HasSelf<State>>(&mut linker, |s| s)
.map_err(|e| e.to_string())?;
self.engine = Some((engine, linker));
}
Ok(self.engine.as_ref().expect("made above"))
@@ -290,6 +311,7 @@ impl Mods {
out: Vec::new(),
panel: None,
ui: UiState::default(),
shapes: Vec::new(),
data_dir,
storage_budget: STORAGE_WRITE_BUDGET,
limits: StoreLimitsBuilder::new()
@@ -481,6 +503,14 @@ impl Mods {
.iter()
.filter_map(|e| e.run.as_ref()?.store.data().panel.as_ref())
}
/// The running mods' HUD shapes (capability `render`), each mod's in
/// its own order, mods in load order.
pub fn hud_shapes(&self) -> impl Iterator<Item = &Shape> {
self.entries
.iter()
.filter_map(|e| e.run.as_ref())
.flat_map(|r| &r.store.data().shapes)
}
/// The screen mod `i` last pushed with `ui.open-screen`, while it is up.
pub fn screen(&self, i: usize) -> Option<&UiScreen> {
self.entries
@@ -668,6 +698,57 @@ impl chat::Host for State {
}
}
}
/// 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;
impl render::Host for State {
fn set_hud(&mut self, shapes: Vec<Shape>) {
self.shapes = shapes
.into_iter()
.take(SHAPES)
.map(|shape| match shape {
Shape::Sprite(mut s) => {
s.sprite = clip(s.sprite);
Shape::Sprite(s)
}
Shape::Item(mut i) => {
i.item = clip(i.item);
i.scale = if i.scale.is_finite() {
i.scale.clamp(0.0, 16.0)
} else {
1.0
};
Shape::Item(i)
}
Shape::Text(mut t) => {
t.text = clip(t.text);
t.color &= 0xFF_FFFF;
Shape::Text(t)
}
other => other,
})
.collect();
}
fn gui_size(&mut self) -> (f32, f32) {
self.snapshot.gui_size
}
fn shake(&mut self, strength: f32, seconds: f32) {
let ok = |v: f32, max: f32| {
if v.is_finite() {
v.clamp(0.0, max)
} else {
0.0
}
};
let (strength, seconds) = (ok(strength, 1.0), ok(seconds, SHAKE_SECONDS));
if strength > 0.0 && seconds > 0.0 {
self.out.push(Output::Shake { strength, seconds });
}
}
}
impl hud::Host for State {
fn set_panel(&mut self, corner: Corner, lines: Vec<Line>) {
let lines = lines
+35 -3
View File
@@ -1,7 +1,7 @@
//! Loads real mods built with the SDK: the coords-hud example and a guest
//! that misbehaves on command. Needs `rustup target add wasm32-unknown-unknown`.
use horizon_mods::{
Clock, Corner, Mods, Output, Package, Player, Snapshot, Status, manifest::componentize,
Clock, Corner, Mods, Output, Package, Player, Shape, Snapshot, Status, manifest::componentize,
};
use std::{
path::{Path, PathBuf},
@@ -22,8 +22,8 @@ id = "test_ui_guest"
name = "Test UI Guest"
version = "0.1.0"
api = "0.1"
capabilities = ["chat", "ui"]
experimental = ["ui"]
capabilities = ["chat", "ui", "render"]
experimental = ["ui", "render"]
"#;
/// Builds both mods once and writes their `.hmod` files; returns the folder.
@@ -89,6 +89,7 @@ fn player() -> Snapshot {
game_time: 100,
day_time: 24000 + 6000,
}),
gui_size: (427.0, 240.0),
}
}
@@ -416,6 +417,37 @@ fn ui_screens_settings_and_events() {
assert!(mods.screen(0).is_none());
}
#[test]
fn render_shapes_and_shakes() {
let mut mods = load("horizon_mods_test_ui_guest.hmod");
mods.set_snapshot(Snapshot {
gui_size: (427.0, 240.0),
..Snapshot::default()
});
assert_eq!(mods.hud_shapes().count(), 0);
assert!(mods.command("render_hud"));
let shapes: Vec<_> = mods.hud_shapes().cloned().collect();
assert_eq!(shapes.len(), 5);
// The guest read `gui-size`; text is clipped to 256 characters.
let Shape::Text(t) = &shapes[4] else {
panic!("{:?}", shapes[4])
};
assert!(t.text.starts_with("gui 427x240 "), "{}", t.text);
assert_eq!(t.text.chars().count(), 256);
assert!(mods.command("render_clear"));
assert_eq!(mods.hud_shapes().count(), 0);
// One jolt, clamped; zero and NaN shake nothing.
mods.drain();
assert!(mods.command("render_shake"));
assert_eq!(
mods.drain(),
[Output::Shake {
strength: 1.0,
seconds: 10.0
}]
);
}
#[test]
fn content_only_mods_load_without_an_engine() {
let manifest = r#"
+68 -3
View File
@@ -1,11 +1,61 @@
//! A mod for the runtime's `ui` tests: `/ui_screen` opens a screen with one
//! 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`.
use horizon_mod_sdk::{
Mod, Registration, chat,
render::{self, FillShape, ItemShape, Point, QuadShape, Rect, Shape, SpriteShape, TextShape},
ui::{self, ItemWidget, ListWidget, Screen, TextWidget, Widget},
};
/// One of each shape, the text too long by 44 characters.
fn shapes() -> Vec<Shape> {
let (w, h) = render::gui_size();
let p = |x, y| Point { x, y };
vec![
Shape::Fill(FillShape {
rect: Rect {
x: 4.0,
y: 4.0,
w: 60.0,
h: 20.0,
},
color: 0x80FF0000,
}),
Shape::Quad(QuadShape {
corners: (
p(w / 2.0, 10.0),
p(w / 2.0 + 20.0, 30.0),
p(w / 2.0, 50.0),
p(w / 2.0 - 20.0, 30.0),
),
color: 0xC000FF00,
}),
Shape::Sprite(SpriteShape {
sprite: "hud/heart/full".into(),
rect: Rect {
x: 70.0,
y: 4.0,
w: 18.0,
h: 18.0,
},
color: 0xFFFFFFFF,
}),
Shape::Item(ItemShape {
item: "minecraft:diamond".into(),
at: p(92.0, 4.0),
scale: 2.0,
}),
Shape::Text(TextShape {
text: format!("gui {w}x{h} {}", "x".repeat(300)),
at: p(w / 2.0, h / 2.0 - 30.0),
color: 0xFFFF55,
centered: true,
shadow: true,
}),
]
}
struct Guest;
fn widgets() -> Vec<Widget> {
@@ -30,9 +80,16 @@ fn widgets() -> Vec<Widget> {
impl Mod for Guest {
fn init() -> Result<(Self, Registration), String> {
let hooks = ["ui_screen", "ui_settings", "ui_close"]
.into_iter()
.fold(Registration::new(), Registration::command);
let hooks = [
"ui_screen",
"ui_settings",
"ui_close",
"render_hud",
"render_clear",
"render_shake",
]
.into_iter()
.fold(Registration::new(), Registration::command);
Ok((Guest, hooks))
}
fn command(&mut self, name: &str, _args: &str) -> Result<Option<String>, String> {
@@ -43,6 +100,14 @@ impl Mod for Guest {
}),
"ui_settings" => ui::set_settings(&widgets()),
"ui_close" => ui::close_screen(),
"render_hud" => render::set_hud(&shapes()),
"render_clear" => render::set_hud(&[]),
// Clamped to (1, 10); the two after it shake nothing.
"render_shake" => {
render::shake(2.0, 99.0);
render::shake(0.0, 1.0);
render::shake(f32::NAN, 1.0);
}
_ => {}
}
Ok(None)
+93 -1
View File
@@ -13,6 +13,7 @@ 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 |
## World `horizon-mod`
@@ -23,7 +24,7 @@ The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`,
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.
- Imports (what the game offers): `ui`, `log`, `game`, `chat`, `hud`, `storage`
- Imports (what the game offers): `ui`, `render`, `log`, `game`, `chat`, `hud`, `storage`
- Exports (what the mod provides): `ui-events`, `events`
## World `ui-host`
@@ -33,6 +34,13 @@ The game's side of `horizon-ui-mod` beyond `horizon-mod`.
- Imports (what the game offers): `ui`
- Exports (what the mod provides): `ui-events`
## World `render-host`
The game's side of capability `render` (imports only).
- Imports (what the game offers): `render`
- Exports (what the mod provides):
## `log`
Access: always granted.
@@ -205,6 +213,90 @@ What the game calls on a mod that shows widgets (capability `ui`): what the play
| `closed` | `func()` | 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. |
| `settings-opened` | `func()` | The player opened the mod's settings page in Options > Mods: call `ui::set-settings` now to fill it with fresh widgets. |
## `render`
Access: capability `render`.
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.
### record `rect`
A rectangle in GUI pixels: the top left corner and the size.
| Field | Type | |
| --- | --- | --- |
| `x` | `f32` | |
| `y` | `f32` | |
| `w` | `f32` | |
| `h` | `f32` | |
### record `point`
A point in GUI pixels from the screen's top left.
| Field | Type | |
| --- | --- | --- |
| `x` | `f32` | |
| `y` | `f32` | |
### record `fill-shape`
| Field | Type | |
| --- | --- | --- |
| `rect` | `rect` | |
| `color` | `u32` | 0xAARRGGBB. |
### record `quad-shape`
Any four-cornered shape (a wheel's segment, an arrow): the corners in order round it.
| Field | Type | |
| --- | --- | --- |
| `corners` | `tuple<point, point, point, point>` | |
| `color` | `u32` | 0xAARRGGBB. |
### record `sprite-shape`
| Field | Type | |
| --- | --- | --- |
| `sprite` | `string` | 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. |
| `rect` | `rect` | |
| `color` | `u32` | A tint, 0xAARRGGBB: 0xFFFFFFFF draws it as it is. |
### record `item-shape`
| Field | Type | |
| --- | --- | --- |
| `item` | `string` | `minecraft:diamond`, `<mod>:<path>`; an unknown one draws nothing. |
| `at` | `point` | The icon's top left. |
| `scale` | `f32` | 1.0 is the hotbar's 16 × 16. |
### record `text-shape`
| Field | Type | |
| --- | --- | --- |
| `text` | `string` | Up to 256 characters, one line. |
| `at` | `point` | |
| `color` | `u32` | 0xRRGGBB, as `hud`'s lines. |
| `centered` | `bool` | Centred on `at.x` instead of starting there. |
| `shadow` | `bool` | |
### variant `shape`
| Case | Payload | |
| --- | --- | --- |
| `fill` | `fill-shape` | |
| `quad` | `quad-shape` | |
| `sprite` | `sprite-shape` | |
| `item` | `item-shape` | |
| `text` | `text-shape` | |
| Function | Signature | What it does |
| --- | --- | --- |
| `set-hud` | `func(shapes: list<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. |
| `gui-size` | `func() -> tuple<f32, f32>` | The screen's size in GUI pixels (width, height), as of this tick. |
| `shake` | `func(strength: f32, seconds: f32)` | 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). |
## `events`
Access: exported by the mod: the game calls it.
+2
View File
@@ -95,5 +95,7 @@ What real mods need next, in the order modpacks and servers need it:
## Changelog
- Experimental `render` (`experimental = ["render"]`): HUD shapes (fill, quad, sprite, item, text), `gui-size`, camera
`shake`, drawn by the game's own renderer.
- API 0.2 (content): data-driven blocks and items, tags, `horizon:add_to`, terrain adaptation.
- API 0.1.0: `log`, `game`, `chat`, `hud`, `storage`; `init`, `tick`, `frame`, `command`, `chat`.
+1
View File
@@ -88,6 +88,7 @@ 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"]` |
| 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 | |
+3 -2
View File
@@ -87,6 +87,7 @@ 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, 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; `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"]` |
| Hook (export) | When |
|---|---|
@@ -114,7 +115,7 @@ loading. Ordered by what the first native ports need:
| `inventory-read` | the player's inventory, held item, open container | AppleSkin, recipe viewers |
| `recipes` | the recipe registry and lookups | JEI/EMI-style viewers |
| `world-read` | blocks and biomes around the player, within the render distance | minimaps, schematics |
| `render` | world-space lines, boxes and ghost blocks in a per-frame budget | Litematica-style placement, waypoints |
| `render` (world) | world-space lines, boxes and billboards, beside the HUD shapes `render` has | Litematica-style placement, waypoints |
| `registries` | new blocks, items, entities and recipes, mostly data: JSON models, textures, loot and recipes in the `.hmod`'s `assets/` and `data/` | server side; see [Multiplayer](#multiplayer) |
| `server` | world events (block break/place, entity spawn/death, player join), game rules, server commands | runs where the world is simulated |
| `net` | a mod's own client↔server channel (custom payloads) | only between the two halves of the same mod |
@@ -288,7 +289,7 @@ experimental = [] # experimental capabilities it uses, e.g. ["ui"]
```
Unknown keys are refused, so a typo is an error, not a silently ignored
permission. An experimental capability (today `ui`) may change in any release
permission. An experimental capability (today `ui` and `render`) may change in any release
([stability](api/stability.md)): a mod uses it only by naming it in
`experimental` as well, so nobody depends on it by accident.