From efe017ffb1e82b8005604979bdef6969bd4b9b83 Mon Sep 17 00:00:00 2001 From: chexit Date: Wed, 4 Nov 2026 17:49:42 +0300 Subject: [PATCH] Report per-run camera picture readiness milestones API 30 adds render.camera-status: availability, the last noted frame's mod-camera picture path, the calling run's accepted set-views submission for this world generation, and per-camera prepared flags. A camera is prepared when the renderer encoded its picture into the texture target in a real frame of this generation, or a world frame rendered from it as the set-main-view selection: a host-side encoding milestone, not target registration, not a GPU fence, not a visible pixel. An empty set-views clears the request; a resubmission, world transition or mod reload waits for a new frame. The renderer reports the pictures it drew each frame; the game notes the frame after a successful render. Verified with two real Wasmtime guests sharing local camera id 7: each run's readiness follows only its own submission and main-view choice, and a world transition resets both. Co-Authored-By: Kimi Code --- crates/horizon-client/src/game.rs | 7 + crates/horizon-client/src/gfx.rs | 13 ++ crates/horizon-mod-sdk/wit/horizon.wit | 40 ++++ crates/horizon-mods/src/api_level.rs | 5 +- crates/horizon-mods/src/runtime.rs | 134 +++++++++++- crates/horizon-mods/tests/sandbox.rs | 204 +++++++++++++++++- crates/horizon-mods/tests/ui_guest/src/lib.rs | 60 +++++- docs/api/mods-reference.md | 34 +++ 8 files changed, 485 insertions(+), 12 deletions(-) diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index be28f5d34..0881fde41 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -12154,6 +12154,13 @@ impl Game<'_> { } None => Err("renderer".into()), }; + // AirDef fork: the camera-ready milestone of the frame just encoded (not GPU completion). + if let (Ok(true), Some(renderer)) = (&result, &self.renderer) { + let enabled = !frame.title && !frame.mod_views.is_empty(); + self.mods + .mods + .note_camera_frame(enabled, renderer.drawn_mod_views()); + } // Restore storage even when rendering fails (for example, a lost surface). self.entity_vertices = entities; *self.entity_spans.get_mut() = entity_spans; diff --git a/crates/horizon-client/src/gfx.rs b/crates/horizon-client/src/gfx.rs index 1d8573eee..d92dca064 100644 --- a/crates/horizon-client/src/gfx.rs +++ b/crates/horizon-client/src/gfx.rs @@ -589,6 +589,9 @@ pub struct Renderer { mod_post_source: Option, mod_post_hdr: bool, mod_views: Option, + /// AirDef fork: the (run, camera id) pictures encoded in the last drawn frame, + /// for the mods' camera-ready status. Not GPU completion. + drawn_mod_views: Vec<(u64, u32)>, /// AirDef fork: the HD lighting's G-buffer pipelines (terrain, entities) and its targets. gbuffer_terrain: wgpu::RenderPipeline, /// The sprite layers' material classes (leaves, plants, metal) for the HD wind and specular. @@ -2995,6 +2998,7 @@ impl Renderer { mod_post_source: None, mod_post_hdr: false, mod_views: None, + drawn_mod_views: Vec::new(), gbuffer_terrain, hd_materials, gbuffer_water, @@ -3420,6 +3424,7 @@ impl Renderer { let Some(views) = &mut self.mod_views else { return; }; + let mut drawn = std::mem::take(&mut self.drawn_mod_views); let size = std::mem::size_of::() as u64; self.uploads .buffer(encoder, &views.main, 0, bytemuck::bytes_of(globals)); @@ -3456,6 +3461,7 @@ impl Renderer { continue; }; t.drawn = true; + drawn.push((d.owner, d.id)); encoder.copy_buffer_to_buffer(&t.globals, 0, &self.globals, 0, size); let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor { label: Some("Mod view"), @@ -3556,6 +3562,12 @@ impl Renderer { } } encoder.copy_buffer_to_buffer(&views.main, 0, &self.globals, 0, size); + self.drawn_mod_views = drawn; + } + /// The (run, camera id) mod pictures encoded in the last drawn frame + /// (`render.camera-status`'s prepared milestone; not GPU completion). + pub fn drawn_mod_views(&self) -> &[(u64, u32)] { + &self.drawn_mod_views } /// Draws `count` section draws from `first` with the arena and section /// origins bound: one indirect multi-draw, or a loop without it. @@ -4125,6 +4137,7 @@ impl Renderer { fn draw_frame(&mut self, frame: &Frame) -> Result { self.arena.trim(); self.sorted_indices.trim(); + self.drawn_mod_views.clear(); if let Some(flat) = &mut self.flat { flat.trim(|page| self.arena.has_page(page)); } diff --git a/crates/horizon-mod-sdk/wit/horizon.wit b/crates/horizon-mod-sdk/wit/horizon.wit index 26dd78802..d390f5598 100644 --- a/crates/horizon-mod-sdk/wit/horizon.wit +++ b/crates/horizon-mod-sdk/wit/horizon.wit @@ -1051,6 +1051,46 @@ interface render { /// 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; + /// One `set-views` camera's readiness in the calling run and world generation. + /// `request-accepted` means the run's latest non-empty `set-views` stored this + /// camera this generation. `prepared` means the renderer encoded this camera's + /// picture into its texture target in a real frame of this generation (or the + /// camera is the run's `set-main-view` selection and a world frame rendered + /// from it): a host-side encoding milestone, not GPU completion, not a visible + /// pixel. A rotating per-frame budget may skip a picture camera some frames. + record camera-readiness { + id: u32, + request-accepted: bool, + prepared: bool, + reason: camera-reason, + } + enum camera-reason { + awaiting-frame, + ready, + } + /// API level 30. State of the calling run's `set-views` cameras for this world. + /// Available means this host implements the API. Enabled means the renderer's + /// mod-camera picture path was live in the last noted frame (a world frame, not + /// a title screen), not that any camera was drawn. `request-accepted` and + /// `prepared` aggregate the per-camera list: accepted means the run's latest + /// `set-views` stored cameras this generation, prepared means at least one was + /// drawn (or rendered as the screen's main view). `main-view` is the camera id + /// the run last selected with `set-main-view`, if any. An empty `set-views` + /// clears the request; a world transition or mod reload invalidates readiness. + record camera-state { + generation: u64, + available: bool, + enabled: bool, + request-accepted: bool, + prepared: bool, + reason: capability-reason, + cameras: list, + main-view: option, + } + /// The caller's `set-views` cameras and the last noted mod-camera frame. + /// This does not inspect the GPU: prepared is the host encoding the picture, + /// not a fence, a presented frame, or the player seeing the picture. + camera-status: func() -> camera-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 4c02bd020..15e5fafed 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 = 29; +pub const LEVEL: u32 = 30; /// 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); 96] = [ +pub const FUNCTIONS: [(&str, u32); 97] = [ ("log.write", 0), ("game.get-player", 0), ("game.get-clock", 0), @@ -125,6 +125,7 @@ pub const FUNCTIONS: [(&str, u32); 96] = [ ("render.capture-owner-status", 27), ("render.point-lights-status", 28), ("render.sound-sources-status", 29), + ("render.camera-status", 30), ]; /// 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 6fdcd211e..fc54d00fb 100644 --- a/crates/horizon-mods/src/runtime.rs +++ b/crates/horizon-mods/src/runtime.rs @@ -82,13 +82,14 @@ 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::{ - CameraView, CanvasButton, CanvasEvent, CanvasScroll, CaptureOptions, CapturePhase, - CaptureState, Changes as WorldChanges, Corner as RenderCorner, FarTerrain as ModFarTerrain, - FillShape, FrameRate, ItemShape, Lighting as ModLighting, Minimap as ModMinimap, ModelInstance, - ModelInstanceId, ParticleSpawn, Point as RenderPoint, PointLight, Policy as WorldPolicy, - QuadShape, Ray as WorldRay, RayAnswer as WorldRayAnswer, Rect as RenderRect, - Section as WorldSection, SectionFill, Shape, SmokeSegment, SourceOp, SourceOpKind, SpotLight, - SpriteShape, TerrainShape, TextShape, Verdict as WorldVerdict, ViewShape, Zoom as ModZoom, + CameraReadiness, CameraReason, CameraState, CameraView, CanvasButton, CanvasEvent, + CanvasScroll, CaptureOptions, CapturePhase, CaptureState, Changes as WorldChanges, + Corner as RenderCorner, FarTerrain as ModFarTerrain, FillShape, FrameRate, ItemShape, + Lighting as ModLighting, Minimap as ModMinimap, ModelInstance, ModelInstanceId, ParticleSpawn, + Point as RenderPoint, PointLight, Policy as WorldPolicy, QuadShape, Ray as WorldRay, + RayAnswer as WorldRayAnswer, Rect as RenderRect, Section as WorldSection, SectionFill, Shape, + SmokeSegment, SourceOp, SourceOpKind, SpotLight, SpriteShape, TerrainShape, TextShape, + Verdict as WorldVerdict, ViewShape, Zoom as ModZoom, }; use render_bindings::{RenderHost, horizon::mods::render}; /// Capability `recipes`'s imports (docs/mods.md): the game's recipes and items. @@ -320,6 +321,9 @@ 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, + /// `render.set-views`: the last noted frame's mod-camera picture path state. + camera_frame_seen: bool, + camera_enabled: bool, point_lights_frame_seen: bool, point_lights_enabled: bool, /// `render.capture-start`: the request the game has not taken yet. @@ -554,6 +558,10 @@ struct State { views: Vec, /// `render.set-main-view`: the camera the screen's world is rendered from. main_view: Option, + /// The world generation this run's latest non-empty `set-views` stored, if any. + views_request_generation: Option, + /// Camera ids of this run's submission the renderer drew this generation. + views_prepared: Vec, /// `render.set-lights` and `render.set-lighting` (AirDef fork). lights: Vec, point_request_generation: Option, @@ -843,6 +851,8 @@ impl Mods { post_params: Vec::new(), views: Vec::new(), main_view: None, + views_request_generation: None, + views_prepared: Vec::new(), lights: Vec::new(), point_request_generation: None, point_cached_generation: None, @@ -964,6 +974,8 @@ impl Mods { t.smoke_frame_seen = false; t.point_lights_frame_seen = false; t.point_lights_enabled = false; + t.camera_frame_seen = false; + t.camera_enabled = false; t.source_output_seen = false; t.source_output_ready = false; t.acoustics_prepared = false; @@ -988,6 +1000,8 @@ impl Mods { state.smoke.clear(); state.smoke_clock = (0.0, 0.0); state.smoke_request_generation = None; + state.views_request_generation = None; + state.views_prepared.clear(); } } } @@ -1700,6 +1714,37 @@ impl Mods { } } } + /// State of the last frame's mod-camera picture path, as the game noted it + /// after a rendered frame. `enabled` means the picture path was live (a world + /// frame with mod cameras, not a title screen); `drawn` lists the (run, camera + /// id) pictures the renderer encoded this frame. This is a host-side encoding + /// milestone, not GPU completion. + pub fn note_camera_frame(&mut self, enabled: bool, drawn: &[(u64, u32)]) { + let generation = if let Ok(mut t) = self.model_table.lock() { + t.camera_frame_seen = t.smoke_world.is_some(); + t.camera_enabled = enabled && t.camera_frame_seen; + t.smoke_generation + } else { + return; + }; + for entry in &mut self.entries { + if let Some(run) = &mut entry.run { + let state = run.store.data_mut(); + if state.views_request_generation != Some(generation) { + continue; + } + for &(_, id) in drawn + .iter() + .filter(|(serial, _)| *serial == state.run_serial) + { + if state.views.iter().any(|v| v.id == id) && !state.views_prepared.contains(&id) + { + state.views_prepared.push(id); + } + } + } + } + } /// The runs that are alive: the game releases the sources of any other. pub fn source_runs(&self) -> Vec { self.entries @@ -2846,6 +2891,17 @@ impl render::Host for State { v }) .collect(); + // A new submission has not been drawn yet; an empty one is no request. + self.views_prepared.clear(); + self.views_request_generation = if self.views.is_empty() { + None + } else { + self.model_table + .lock() + .ok() + .map(|t| t.smoke_generation) + .filter(|g| *g != 0) + }; } fn set_main_view(&mut self, view: Option) { self.main_view = view; @@ -3228,6 +3284,70 @@ impl render::Host for State { reason, } } + fn camera_status(&mut self) -> render::CameraState { + let Ok(t) = self.model_table.lock() else { + return render::CameraState { + generation: 0, + available: false, + enabled: false, + request_accepted: false, + prepared: false, + reason: render::CapabilityReason::AwaitingBackend, + cameras: Vec::new(), + main_view: None, + }; + }; + let accepted = + self.views_request_generation == Some(t.smoke_generation) && t.smoke_generation != 0; + let main_prepared = t.camera_enabled; + let cameras: Vec = if accepted { + self.views + .iter() + .map(|v| { + // The main view is the screen itself: a world frame rendered from + // it is its milestone, with no picture target of its own. + let prepared = self.views_prepared.contains(&v.id) + || (main_prepared && self.main_view == Some(v.id)); + render::CameraReadiness { + id: v.id, + request_accepted: true, + prepared, + reason: if prepared { + render::CameraReason::Ready + } else { + render::CameraReason::AwaitingFrame + }, + } + }) + .collect() + } else { + Vec::new() + }; + let prepared = cameras.iter().any(|c| c.prepared); + let reason = if t.smoke_world.is_none() { + render::CapabilityReason::AwaitingWorld + } else if !accepted { + render::CapabilityReason::NotRequested + } else if !t.camera_frame_seen { + render::CapabilityReason::AwaitingBackend + } else if !t.camera_enabled { + render::CapabilityReason::Disabled + } else if !prepared { + render::CapabilityReason::AwaitingBackend + } else { + render::CapabilityReason::Ready + }; + render::CameraState { + generation: t.smoke_generation, + available: true, + enabled: t.camera_enabled, + request_accepted: accepted, + prepared, + reason, + cameras, + main_view: self.main_view, + } + } 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 274ad1ed1..120b6fd05 100644 --- a/crates/horizon-mods/tests/sandbox.rs +++ b/crates/horizon-mods/tests/sandbox.rs @@ -297,6 +297,208 @@ fn point_lights_milestones_follow_processing_and_world_generation() { assert!(status(&mut mods).ends_with("false false false CapabilityReason::AwaitingWorld")); } +/// The picture milestone is a drawn frame, not a stored target; a resubmission, +/// a world transition or a reload waits for a new frame. +#[test] +fn camera_status_milestones_follow_drawn_frames_and_generation() { + let dir = mods_dir().join("camera_status_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("camera_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 main=None []") + ); + assert!(mods.command("view_set")); + // Stored, but no frame was noted yet: enabled stays false. + assert!( + status(&mut mods) + .ends_with("false true false CapabilityReason::AwaitingBackend main=None [7:false:CameraReason::AwaitingFrame]") + ); + mods.note_camera_frame(true, &[]); + // A frame without this camera's picture: still awaiting. + assert!( + status(&mut mods) + .ends_with("true true false CapabilityReason::AwaitingBackend main=None [7:false:CameraReason::AwaitingFrame]") + ); + let serial = mods.views().next().unwrap().0; + mods.note_camera_frame(true, &[(serial, 7)]); + assert!(status(&mut mods).ends_with( + "true true true CapabilityReason::Ready main=None [7:true:CameraReason::Ready]" + )); + assert!(mods.command("view_set")); // a resubmission is not drawn yet + assert!( + status(&mut mods) + .ends_with("true true false CapabilityReason::AwaitingBackend main=None [7:false:CameraReason::AwaitingFrame]") + ); + // The screen's own view from this camera is its milestone, without a picture target. + assert!(mods.command("view_main on")); + mods.note_camera_frame(true, &[]); + assert!(status(&mut mods).ends_with( + "true true true CapabilityReason::Ready main=Some(7) [7:true:CameraReason::Ready]" + )); + assert!(mods.command("view_main off")); + mods.note_camera_frame(false, &[]); + assert!( + status(&mut mods) + .ends_with("false true false CapabilityReason::Disabled main=None [7:false:CameraReason::AwaitingFrame]") + ); + let old = status(&mut mods) + .split_whitespace() + .next() + .unwrap() + .to_owned(); + mods.set_snapshot(snapshot("world:b")); + let next = status(&mut mods); + assert_ne!(next.split_whitespace().next().unwrap(), old); + assert!(next.ends_with("false false false CapabilityReason::NotRequested main=None []")); + assert!(mods.command("view_set")); + let serial = mods.views().next().unwrap().0; + mods.note_camera_frame(true, &[(serial, 7)]); + assert!(status(&mut mods).ends_with( + "true true true CapabilityReason::Ready main=None [7:true:CameraReason::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)); + // The new run made no request; the last noted frame's path state remains. + assert!( + status(&mut mods).ends_with("true false false CapabilityReason::NotRequested main=None []") + ); + mods.set_snapshot(Snapshot::default()); + assert!( + status(&mut mods) + .ends_with("false false false CapabilityReason::AwaitingWorld main=None []") + ); +} + +/// Two runs share the local camera id 7; each run's status reflects only its +/// own submission and main-view choice. +#[test] +fn camera_status_is_scoped_to_each_mod_run() { + let original = Package::read(&mods_dir().join("horizon_mods_test_ui_guest.hmod")) + .unwrap() + .wasm + .unwrap(); + let dir = mods_dir().join("camera_status_runs"); + std::fs::create_dir_all(&dir).unwrap(); + let one = dir.join("one.hmod"); + let two = dir.join("two.hmod"); + std::fs::write(&one, Package::write(UI_MANIFEST, &original).unwrap()).unwrap(); + let other = UI_MANIFEST + .replace("test_ui_guest", "test_ui_guest_other") + .replace("Test UI Guest", "Other UI Guest"); + std::fs::write(&two, Package::write(&other, &original).unwrap()).unwrap(); + let mut mods = Mods::load(&[one, two], |_| true, |_| false); + mods.set_snapshot(Snapshot { + world: Some("test".into()), + world_seed: Some(-987_654_321), + ..Snapshot::default() + }); + let lines = |mods: &mut Mods| { + mods.drain() + .into_iter() + .filter_map(|o| match o { + Output::Chat { name, text } if text.starts_with("camera ") => Some((name, text)), + _ => None, + }) + .collect::>() + }; + // "camera enabled accepted prepared generation reason". + fn fields(line: &str) -> (&str, &str, &str, &str) { + let f: Vec<&str> = line.split_whitespace().collect(); + assert_eq!(f.first(), Some(&"camera"), "{line}"); + (f[1], f[2], f[3], f[5]) + } + mods.tick(1); + let runs: Vec<_> = mods.views().map(|(run, view)| (run, view.id)).collect(); + assert_eq!(runs.len(), 2, "{runs:?}"); + assert_ne!(runs[0].0, runs[1].0); + assert_eq!(runs[0].1, 7); + let mut first = lines(&mut mods); + first.sort(); + assert_eq!(first.len(), 2, "{first:?}"); + // No frame noted yet: accepted, not prepared, in this world generation. + for (_, line) in &first { + assert_eq!( + fields(line), + ( + "false", + "true", + "false", + "CapabilityReason::AwaitingBackend" + ), + "{line}" + ); + } + mods.note_camera_frame(true, &[]); // a world frame: both render their main view + mods.tick(1); + let mut both = lines(&mut mods); + both.sort(); + assert_eq!(both.len(), 2, "{both:?}"); + for (_, line) in &both { + assert_eq!( + fields(line), + ("true", "true", "true", "CapabilityReason::Ready"), + "{line}" + ); + } + // Only the first run drops its main view: same local id, different readiness. + assert!(mods.command("view_main off")); + mods.note_camera_frame(true, &[]); + mods.tick(1); + let split = lines(&mut mods); + assert_eq!(split.len(), 2, "{split:?}"); + for (name, line) in &split { + let ready = fields(line) == ("true", "true", "true", "CapabilityReason::Ready"); + assert_eq!(ready, *name != "Test UI Guest", "{name}: {line}"); + } + mods.set_snapshot(Snapshot { + world: Some("test2".into()), + world_seed: Some(-987_654_321), + ..Snapshot::default() + }); + mods.tick(1); + let mut after = lines(&mut mods); + after.sort(); + assert_eq!(after.len(), 2, "{after:?}"); + for (_, line) in &after { + // A new generation: the old frame's milestones do not carry over. + assert_eq!( + fields(line), + ( + "false", + "true", + "false", + "CapabilityReason::AwaitingBackend" + ), + "{line}" + ); + } +} + /// 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() { @@ -307,7 +509,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)), - (29, Some("render.sound-sources-status")) + (30, Some("render.camera-status")) ); let mut mods = load("horizon_mods_test_ui_guest.hmod"); let snapshot = |world: &str| Snapshot { diff --git a/crates/horizon-mods/tests/ui_guest/src/lib.rs b/crates/horizon-mods/tests/ui_guest/src/lib.rs index ace79ab1f..4249d5ede 100644 --- a/crates/horizon-mods/tests/ui_guest/src/lib.rs +++ b/crates/horizon-mods/tests/ui_guest/src/lib.rs @@ -75,6 +75,8 @@ struct Guest { /// `/recipe_place ID [all] later`: placed on the first tick a crafting /// screen is open. pending: Option<(i32, bool, String)>, + /// Whether the test camera is the screen's main view (`/view_main`). + main_on: bool, } fn widgets() -> Vec { @@ -132,6 +134,10 @@ impl Mod for Guest { "quiet_many", "source", "source_keep", + "view_set", + "view_clear", + "view_main", + "camera_status", "recipes", "browser", "browser_poll", @@ -155,7 +161,13 @@ impl Mod for Guest { .register()?; Tree::new("unregistered").runs().register()?; command::set_suggestions("saves", &["a".to_string()]); - Ok((Guest { pending: None }, hooks)) + Ok(( + Guest { + pending: None, + main_on: true, + }, + hooks, + )) } fn command(&mut self, name: &str, args: &str) -> Result, String> { match name { @@ -207,6 +219,41 @@ impl Mod for Guest { radius: 8.0, }]), "point_clear" => render::set_lights(&[]), + "view_set" => render::set_views(&[render::CameraView { + id: 7, + x: 1.0, + y: 2.0, + z: 3.0, + yaw: 0.0, + pitch: 0.0, + fov: 70.0, + width: 64, + height: 64, + }]), + "view_clear" => render::set_views(&[]), + "view_main" => { + self.main_on = args == "on"; + render::set_main_view(if self.main_on { Some(7) } else { None }); + } + "camera_status" => { + let s = render::camera_status(); + let cameras: Vec = s + .cameras + .iter() + .map(|c| format!("{}:{}:{:?}", c.id, c.prepared, c.reason)) + .collect(); + chat::show(&format!( + "{} {} {} {} {} {:?} main={:?} [{}]", + s.generation, + s.available, + s.enabled, + s.request_accepted, + s.prepared, + s.reason, + s.main_view, + cameras.join(";") + )); + } "cap_status" => { let a = render::acoustics_status(); let c = render::capture_owner_status(); @@ -678,7 +725,11 @@ impl Mod for Guest { width: 64, height: 64, }]); - render::set_main_view(Some(7)); + if self.main_on { + render::set_main_view(Some(7)); + } else { + render::set_main_view(None); + } render::set_hud(&[Shape::View(render::ViewShape { view: 7, rect: Rect { @@ -689,6 +740,11 @@ impl Mod for Guest { }, mode: 0, })]); + let s = render::camera_status(); + chat::show(&format!( + "camera {} {} {} {} {:?}", + s.enabled, s.request_accepted, s.prepared, s.generation, s.reason + )); } if let Some((book, all, id)) = self.pending.take() { match recipes::place(book, all) { diff --git a/docs/api/mods-reference.md b/docs/api/mods-reference.md index 4a33d34bb..7ada47cad 100644 --- a/docs/api/mods-reference.md +++ b/docs/api/mods-reference.md @@ -811,6 +811,39 @@ API level 27: state for the calling mod and current world generation. Accepted m | `prepared` | `bool` | | | `reason` | `capability-reason` | | +### enum `camera-reason` + +| Case | | +| --- | --- | +| `awaiting-frame` | | +| `ready` | | + +### record `camera-readiness` + +One `set-views` camera's readiness in the calling run and world generation. `request-accepted` means the run's latest non-empty `set-views` stored this camera this generation. `prepared` means the renderer encoded this camera's picture into its texture target in a real frame of this generation (or the camera is the run's `set-main-view` selection and a world frame rendered from it): a host-side encoding milestone, not GPU completion, not a visible pixel. A rotating per-frame budget may skip a picture camera some frames. + +| Field | Type | | +| --- | --- | --- | +| `id` | `u32` | | +| `request-accepted` | `bool` | | +| `prepared` | `bool` | | +| `reason` | `camera-reason` | | + +### record `camera-state` + +API level 30. State of the calling run's `set-views` cameras for this world. Available means this host implements the API. Enabled means the renderer's mod-camera picture path was live in the last noted frame (a world frame, not a title screen), not that any camera was drawn. `request-accepted` and `prepared` aggregate the per-camera list: accepted means the run's latest `set-views` stored cameras this generation, prepared means at least one was drawn (or rendered as the screen's main view). `main-view` is the camera id the run last selected with `set-main-view`, if any. An empty `set-views` clears the request; a world transition or mod reload invalidates readiness. + +| Field | Type | | +| --- | --- | --- | +| `generation` | `u64` | | +| `available` | `bool` | | +| `enabled` | `bool` | | +| `request-accepted` | `bool` | | +| `prepared` | `bool` | | +| `reason` | `capability-reason` | | +| `cameras` | `list` | | +| `main-view` | `option` | | + ### record `spot-light` 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 `range`) and draws the beam as a translucent volume lit from inside: it scatters in the air (more in fog and smoke, a faint artistic one in clear air), the world hides it where it is in front, and the camera may stand inside it. The light does not look for walls: send `range` as far as the beam is free (a cast along the axis) so it stops where the land stops it. @@ -919,6 +952,7 @@ Where a capture is. | `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. | | `sound-sources-status` | `func() -> capability-state` | API level 29. State of this run's live persistent sound source changes. Prepared means their changes were applied by the host audio source manager while a live output or offline film mixer was available; it does not mean a sound asset loaded, received a voice, or was audible. Stopping all sources, a source-generation reset, world transition or mod reload invalidates it. | | `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. | +| `camera-status` | `func() -> camera-state` | The caller's `set-views` cameras and the last noted mod-camera frame. This does not inspect the GPU: prepared is the host encoding the picture, not a fence, a presented frame, or the player seeing the picture. | | `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. |