From 6230ec7031bc079fca8ba30e461194d9f90e5c06 Mon Sep 17 00:00:00 2001 From: chexit Date: Wed, 4 Nov 2026 16:07:18 +0300 Subject: [PATCH] Report per-run point light processing milestones Co-Authored-By: Codex --- crates/horizon-client/src/game/mod_models.rs | 13 ++- crates/horizon-mod-sdk/wit/horizon.wit | 6 ++ crates/horizon-mods/src/api_level.rs | 5 +- crates/horizon-mods/src/runtime.rs | 87 +++++++++++++++++++ crates/horizon-mods/tests/sandbox.rs | 79 ++++++++++++++++- crates/horizon-mods/tests/ui_guest/src/lib.rs | 20 +++++ docs/api/mods-reference.md | 1 + 7 files changed, 204 insertions(+), 7 deletions(-) diff --git a/crates/horizon-client/src/game/mod_models.rs b/crates/horizon-client/src/game/mod_models.rs index 076de6657..ba14b98e2 100644 --- a/crates/horizon-client/src/game/mod_models.rs +++ b/crates/horizon-client/src/game/mod_models.rs @@ -179,6 +179,7 @@ impl Game<'_> { lights.insert(key, (before, *l)); } self.mods.models.lights = lights; + self.mods.mods.cache_point_lights(); let mut spots: HashMap<(usize, u32), (SpotLight, SpotLight)> = HashMap::new(); for (owner, l) in self.mods.mods.spot_lights() { let key = (owner, l.id); @@ -212,7 +213,7 @@ impl Game<'_> { /// The mods' lights between their last two settings, relative to the camera; the nearest and /// brightest first when there are too many. pub(super) fn mod_lights( - &self, + &mut self, camera: DVec3, alpha: f64, ) -> Vec { @@ -243,7 +244,10 @@ impl Game<'_> { }) .collect(); out.sort_by(|x, y| y.0.total_cmp(&x.0)); - out.into_iter().take(512).map(|(_, l)| l).collect() + let lights = out.into_iter().take(512).map(|(_, l)| l).collect(); + let hd_enabled = self.mod_hd().is_some(); + self.mods.mods.prepare_point_lights(hd_enabled); + lights } /// The mods' spot lights between their last two settings, relative to the camera; the nearest @@ -468,7 +472,10 @@ impl Game<'_> { let n = q.len() as f32; let u = q.iter().map(|v| v.uv[0]).sum::() / n; let w = q.iter().map(|v| v.uv[1]).sum::() / n; - if let Some((_, m)) = special.iter().find(|(r, _)| u > r[0] && u < r[2] && w > r[1] && w < r[3]) { + if let Some((_, m)) = special + .iter() + .find(|(r, _)| u > r[0] && u < r[2] && w > r[1] && w < r[3]) + { for v in q { v.layer = *m; if *m == MODEL_GLOW { diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit index 73ae75a0f..3d7f92d64 100644 --- a/crates/horizon-mod-sdk/wit/horizon.wit +++ b/crates/horizon-mod-sdk/wit/horizon.wit @@ -1039,6 +1039,12 @@ interface render { /// completion and errors. Other mods cannot claim it. A world transition /// invalidates ownership and asks the host to cancel the capture. capture-owner-status: func() -> capability-state; + /// API level 28. The calling run's non-empty point-light submission for this world. + /// Enabled means HD was selected for the last main frame, not GPU availability. + /// Prepared means the host processed its cached submissions for an HD main frame, + /// not that every light survived culling or that a GPU produced visible pixels. + /// Empty submissions clear the request; a new submission awaits another frame. + point-lights-status: func() -> capability-state; /// A directional light with a visible beam (AirDef fork): a searchlight, a /// headlight. The HD lighting lights the surfaces and flying things inside /// its cone (smoothly from the inner to the outer angle, down to nothing at diff --git a/crates/horizon-mods/src/api_level.rs b/crates/horizon-mods/src/api_level.rs index bfa3a4238..3e853f6b7 100644 --- a/crates/horizon-mods/src/api_level.rs +++ b/crates/horizon-mods/src/api_level.rs @@ -7,13 +7,13 @@ //! version's level so the launcher can tell before it installs. /// The newest level this Horizon serves. -pub const LEVEL: u32 = 27; +pub const LEVEL: u32 = 28; /// Every function the game offers mods, as `interface.function`, with its /// level. Level 0 is the contract of Horizon 0.2.67 to 0.2.69. A new /// function takes the next level and raises [`LEVEL`] (the `api_reference` /// test fails until it is listed here). -pub const FUNCTIONS: [(&str, u32); 94] = [ +pub const FUNCTIONS: [(&str, u32); 95] = [ ("log.write", 0), ("game.get-player", 0), ("game.get-clock", 0), @@ -123,6 +123,7 @@ pub const FUNCTIONS: [(&str, u32); 94] = [ ("render.smoke-status", 26), ("render.acoustics-status", 27), ("render.capture-owner-status", 27), + ("render.point-lights-status", 28), ]; /// What the game's program carries so the launcher can read its level diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs index 89d83500d..e2c501932 100644 --- a/crates/horizon-mods/src/runtime.rs +++ b/crates/horizon-mods/src/runtime.rs @@ -320,6 +320,8 @@ pub struct ModelTable { smoke_world: Option<(String, Option)>, /// The renderer draws the mods' spot lights and their beams (`render.set-spot-lights`). spot_active: bool, + point_lights_frame_seen: bool, + point_lights_enabled: bool, /// `render.capture-start`: the request the game has not taken yet. capture_request: Option, /// `render.capture-stop`: asked, with whether to throw the file away. @@ -552,6 +554,9 @@ struct State { main_view: Option, /// `render.set-lights` and `render.set-lighting` (AirDef fork). lights: Vec, + point_request_generation: Option, + point_cached_generation: Option, + point_prepared_generation: Option, /// `render.set-spot-lights` (AirDef fork). spots: Vec, /// `render.sound-sources` (AirDef fork): the changes the game has not taken, and this run's number. @@ -834,6 +839,9 @@ impl Mods { views: Vec::new(), main_view: None, lights: Vec::new(), + point_request_generation: None, + point_cached_generation: None, + point_prepared_generation: None, spots: Vec::new(), sources: Default::default(), run_serial: { @@ -946,6 +954,8 @@ impl Mods { t.smoke_active = false; t.smoke_enabled = false; t.smoke_frame_seen = false; + t.point_lights_frame_seen = false; + t.point_lights_enabled = false; t.acoustics_prepared = false; // A world-bound mod capture must not survive into another world. // Only mod-owned captures are touched; game/admin captures remain independent. @@ -958,6 +968,10 @@ impl Mods { for entry in &mut self.entries { if let Some(run) = &mut entry.run { let state = run.store.data_mut(); + state.lights.clear(); + state.point_request_generation = None; + state.point_cached_generation = None; + state.point_prepared_generation = None; state.smoke.clear(); state.smoke_clock = (0.0, 0.0); state.smoke_request_generation = None; @@ -1549,6 +1563,36 @@ impl Mods { .flat_map(move |r| r.store.data().lights.iter().map(move |l| (i, l))) }) } + /// Called after the game copied submissions into its interpolation cache. + pub fn cache_point_lights(&mut self) { + for entry in &mut self.entries { + if let Some(run) = &mut entry.run { + let state = run.store.data_mut(); + state.point_cached_generation = state.point_request_generation; + } + } + } + /// Called after the main-view light list is processed, with the actual HD setting. + pub fn prepare_point_lights(&mut self, enabled: bool) { + let generation = if let Ok(mut t) = self.model_table.lock() { + t.point_lights_frame_seen = true; + t.point_lights_enabled = enabled && t.smoke_world.is_some(); + t.smoke_generation + } else { + return; + }; + for entry in &mut self.entries { + if let Some(run) = &mut entry.run { + let state = run.store.data_mut(); + state.point_prepared_generation = + if enabled && state.point_cached_generation == Some(generation) { + Some(generation) + } else { + None + }; + } + } + } /// Moves the generation `render.sound-source-generation` reports (the game released /// every source): the mods' pending source changes go with the old one. pub fn set_source_generation(&mut self, generation: u32) { @@ -2741,6 +2785,8 @@ impl render::Host for State { self.main_view = view; } fn set_lights(&mut self, lights: Vec) { + self.point_cached_generation = None; + self.point_prepared_generation = None; let finite = |v: f64| v.is_finite() && v.abs() < 30_000_000.0; let unit = |v: f32| { if v.is_finite() { @@ -2768,6 +2814,15 @@ impl render::Host for State { l }) .collect(); + self.point_request_generation = if self.lights.is_empty() { + None + } else { + self.model_table + .lock() + .ok() + .map(|t| t.smoke_generation) + .filter(|g| *g != 0) + }; } fn set_spot_lights(&mut self, lights: Vec) -> bool { let finite = |v: f64| v.is_finite() && v.abs() < 30_000_000.0; @@ -2948,6 +3003,7 @@ impl render::Host for State { // Do not tell a caller to hide its fallback while a disabled request waits for a frame. t.smoke_enabled = false; t.smoke_active = false; + t.point_lights_enabled = false; } self.lighting = Some(lighting); } @@ -3046,6 +3102,37 @@ impl render::Host for State { reason, } } + fn point_lights_status(&mut self) -> render::CapabilityState { + let Ok(t) = self.model_table.lock() else { + return unavailable_capability(); + }; + let accepted = + self.point_request_generation == Some(t.smoke_generation) && t.smoke_generation != 0; + let prepared = accepted + && t.point_lights_enabled + && self.point_prepared_generation == Some(t.smoke_generation); + let reason = if t.smoke_world.is_none() { + render::CapabilityReason::AwaitingWorld + } else if !accepted { + render::CapabilityReason::NotRequested + } else if !t.point_lights_frame_seen { + render::CapabilityReason::AwaitingBackend + } else if !t.point_lights_enabled { + render::CapabilityReason::Disabled + } else if !prepared { + render::CapabilityReason::AwaitingBackend + } else { + render::CapabilityReason::Ready + }; + render::CapabilityState { + generation: t.smoke_generation, + available: true, + enabled: t.point_lights_enabled, + request_accepted: accepted, + prepared, + reason, + } + } fn capture_owner_status(&mut self) -> render::CapabilityState { let Ok(t) = self.model_table.lock() else { return unavailable_capability(); diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs index d75f3bf8d..e736de89a 100644 --- a/crates/horizon-mods/tests/sandbox.rs +++ b/crates/horizon-mods/tests/sandbox.rs @@ -110,6 +110,81 @@ fn player() -> Snapshot { } } +/// Exercise the SDK/WIT through a real guest, then the same cache and frame hooks the game calls. +#[test] +fn point_lights_milestones_follow_processing_and_world_generation() { + let dir = mods_dir().join("point_lights_reload"); + std::fs::create_dir_all(&dir).unwrap(); + let path = dir.join("guest.hmod"); + std::fs::copy(mods_dir().join("horizon_mods_test_ui_guest.hmod"), &path).unwrap(); + let mut mods = Mods::load(std::slice::from_ref(&path), |_| true, |_| false); + let snapshot = |world: &str| Snapshot { + world: Some(world.into()), + world_seed: Some(17), + ..Snapshot::default() + }; + let status = |mods: &mut Mods| { + assert!(mods.command("point_status")); + mods.drain() + .into_iter() + .find_map(|o| match o { + Output::Chat { text, .. } => Some(text), + _ => None, + }) + .unwrap() + }; + mods.set_snapshot(snapshot("world:a")); + assert!(status(&mut mods).ends_with("false false false CapabilityReason::NotRequested")); + assert!(mods.command("point_set")); + assert!(status(&mut mods).ends_with("false true false CapabilityReason::AwaitingBackend")); + mods.prepare_point_lights(true); // a frame without a cache copy cannot acknowledge it + assert!(status(&mut mods).ends_with("true true false CapabilityReason::AwaitingBackend")); + assert_eq!(mods.lights().count(), 1); + mods.cache_point_lights(); + mods.prepare_point_lights(false); + assert!(status(&mut mods).ends_with("false true false CapabilityReason::Disabled")); + mods.prepare_point_lights(true); + assert!(status(&mut mods).ends_with("true true true CapabilityReason::Ready")); + assert!(mods.command("smoke_disable")); + assert!(status(&mut mods).ends_with("false true false CapabilityReason::Disabled")); + mods.prepare_point_lights(true); + assert!(status(&mut mods).ends_with("true true true CapabilityReason::Ready")); + assert!(mods.command("point_set")); + assert!(status(&mut mods).ends_with("true true false CapabilityReason::AwaitingBackend")); + mods.cache_point_lights(); + mods.prepare_point_lights(true); + assert!(mods.command("point_clear")); + assert!(status(&mut mods).ends_with("true false false CapabilityReason::NotRequested")); + assert!(mods.command("point_set")); + mods.cache_point_lights(); + mods.prepare_point_lights(true); + let old = status(&mut mods) + .split_whitespace() + .next() + .unwrap() + .to_owned(); + mods.set_snapshot(snapshot("world:b")); + let new = status(&mut mods); + assert_ne!(new.split_whitespace().next().unwrap(), old); + assert!(new.ends_with("false false false CapabilityReason::NotRequested")); + assert_eq!(mods.lights().count(), 0); + assert!(mods.command("point_set")); + mods.cache_point_lights(); + mods.prepare_point_lights(true); + assert!(status(&mut mods).ends_with("true true true CapabilityReason::Ready")); + let later = std::time::SystemTime::now() + std::time::Duration::from_secs(5); + std::fs::File::options() + .write(true) + .open(&path) + .unwrap() + .set_modified(later) + .unwrap(); + assert!(mods.reload_changed(|_| false)); + assert!(status(&mut mods).ends_with("true false false CapabilityReason::NotRequested")); + mods.set_snapshot(Snapshot::default()); + assert!(status(&mut mods).ends_with("false false false CapabilityReason::AwaitingWorld")); +} + /// The SDK/WIT call is exercised by a real guest against the host's frame and world state. #[test] fn smoke_handshake_keeps_fallback_until_the_current_world_is_ready() { @@ -120,7 +195,7 @@ fn smoke_handshake_keeps_fallback_until_the_current_world_is_ready() { let functions = horizon_mods::api_level::imports(&wasm).unwrap(); assert_eq!( horizon_mods::api_level::needed(functions.iter().map(String::as_str)), - (27, Some("render.acoustics-status")) + (28, Some("render.point-lights-status")) ); let mut mods = load("horizon_mods_test_ui_guest.hmod"); let snapshot = |world: &str| Snapshot { @@ -459,7 +534,7 @@ experimental = ["ui", "render", "input", "recipes"] needed(imports(&wasm).unwrap().iter().map(String::as_str)).0 }; assert_eq!(level("coords_hud.hmod"), 0); - // The UI guest calls the level-27 capability handshake. + // The UI guest calls the level-28 point-light handshake. assert_eq!(level("horizon_mods_test_ui_guest.hmod"), LEVEL); } diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs index 8ddb8e0e5..10420d876 100644 --- a/crates/horizon-mods/tests/ui_guest/src/lib.rs +++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs @@ -108,6 +108,9 @@ impl Mod for Guest { "render_hud", "render_clear", "cap_status", + "point_status", + "point_set", + "point_clear", "cap_acoustics", "cap_capture", "smoke_status", @@ -177,6 +180,23 @@ impl Mod for Guest { } "render_hud" => render::set_hud(&shapes()), "render_clear" => render::set_hud(&[]), + "point_status" => { + let s = render::point_lights_status(); + chat::show(&format!( + "{} {} {} {} {:?}", + s.generation, s.enabled, s.request_accepted, s.prepared, s.reason + )); + } + "point_set" => render::set_lights(&[render::PointLight { + id: 1, + x: 1.0, + y: 2.0, + z: 3.0, + color: (1.0, 0.5, 0.0), + intensity: 2.0, + radius: 8.0, + }]), + "point_clear" => render::set_lights(&[]), "cap_status" => { let a = render::acoustics_status(); let c = render::capture_owner_status(); diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md index ad3660ad2..c41560495 100644 --- a/docs/api/mods-reference.md +++ b/docs/api/mods-reference.md @@ -917,6 +917,7 @@ Where a capture is. | `smoke-status` | `func() -> smoke-state` | The calling mod's submission and the last main-view smoke path state. | | `acoustics-status` | `func() -> capability-state` | The caller's last set-acoustics request and the last geometry processing step. Enabled reflects the actual audio setting. A silent or headless world may remain awaiting-backend until a positional sound is processed. A later disable or world transition clears the processing milestone. | | `capture-owner-status` | `func() -> capability-state` | The caller's capture request, scoped to its run and world generation. Enabled means a world is present, not that the encoder or GPU is ready. Prepared means recording, encoding, or done; inspect capture-status for completion and errors. Other mods cannot claim it. A world transition invalidates ownership and asks the host to cancel the capture. | +| `point-lights-status` | `func() -> capability-state` | API level 28. The calling run's non-empty point-light submission for this world. Enabled means HD was selected for the last main frame, not GPU availability. Prepared means the host processed its cached submissions for an HD main frame, not that every light survived culling or that a GPU produced visible pixels. Empty submissions clear the request; a new submission awaits another frame. | | `set-spot-lights` | `func(lights: list) -> bool` | Replaces the mod's spot lights: up to 32 (the nearest 16 are drawn), interpolated per id between the last two calls. Returns whether the HD renderer draws them with their beams; when it does not (the effects preset, HD off), the mod draws its own beam if it wants one. | | `capture-start` | `func(options: capture-options) -> result<_, string>` | Records the screen frame by frame (AirDef fork), at a fixed time step whatever the speed of the machine: while it records, the game clock advances exactly `1 / fps` seconds a frame (ticks, interpolation, the mod's `tick`s and the sounds with it), so a slow frame is a longer wait and not a skipped one. The frames are read back from the GPU and encoded to H.264 MP4 by `ffmpeg` (found on the `PATH`, or named by `HORIZON_FFMPEG`) through a bounded queue, never held in memory; with no `ffmpeg` they are written as a PNG sequence. Returns an error for a capture already running, a bad name, or an invalid size. Only the game's own files are written, under its home. | | `capture-stop` | `func(cancel: bool)` | Ends this mod run's capture: finishes the file, or (`cancel`) throws it away. A different mod cannot stop it. World transitions cancel mod-owned captures. |