From f95f03c08ec2916a0e5bd3b2d4a2a790e7937b47 Mon Sep 17 00:00:00 2001 From: chexit Date: Tue, 3 Nov 2026 11:06:44 +0300 Subject: [PATCH] Add optional mod test fuel profiling Co-authored-by: Codex --- crates/cargo-horizon-mod/src/main.rs | 18 ++++++++++++++--- crates/horizon-mods/src/runtime.rs | 30 ++++++++++++++++++++++++++++ crates/horizon-mods/src/testing.rs | 10 ++++++++++ crates/horizon-mods/tests/sandbox.rs | 21 +++++++++++++++++++ docs/mods.md | 2 ++ 5 files changed, 78 insertions(+), 3 deletions(-) diff --git a/crates/cargo-horizon-mod/src/main.rs b/crates/cargo-horizon-mod/src/main.rs index ff4ab663b..79294b643 100644 --- a/crates/cargo-horizon-mod/src/main.rs +++ b/crates/cargo-horizon-mod/src/main.rs @@ -6,7 +6,7 @@ //! `assets/` and `data/`; a folder without `Cargo.toml` is content only. //! - `run [--game ] [-- ]`: build, then play with //! the mod; run `build` again and the game reloads it. -//! - `test [--debug] [--hmod ] []`: build, then run the mod's +//! - `test [--debug] [--hmod ] [--fuel-profile] []`: build, then run the mod's //! `tests/*.toml` scripts in the sandbox, with no game. //! - `check [--json]`: what the registry checks of a submission //! (`.hmod`, `.hpack`, resource pack `.zip`), with a trial run for a mod. @@ -52,7 +52,7 @@ fn main() -> ExitCode { Some("test" | "check" | "registry") => { Err("this cargo-horizon-mod was built without trial runs (feature `full`)".into()) } - _ => Err("usage: cargo horizon-mod new [--template code|content] | build [--debug] | run [--game ] [-- ] | test [--debug] [--hmod ] [] | check [--kind ] [--key --signature ] [--json] | registry build|review|check|list".into()), + _ => Err("usage: cargo horizon-mod new [--template code|content] | build [--debug] | run [--game ] [-- ] | test [--debug] [--hmod ] [--fuel-profile] [] | check [--kind ] [--key --signature ] [--json] | registry build|review|check|list".into()), }; match result { Ok(()) => ExitCode::SUCCESS, @@ -328,7 +328,19 @@ fn test(args: &[String]) -> Result<(), String> { .and_then(|text| Script::parse(&text)) .and_then(|script| { let mut game = TestGame::load(&hmod)?; - script.run(&mut game)?; + if args.iter().any(|a| a == "--fuel-profile") { + game.enable_fuel_profile(); + } + let result = script.run(&mut game); + if let Some(profile) = game.fuel_profile() { + for ((id, callback), p) in profile { + println!( + "fuel {id} {callback}: calls={} max={} budget={} failures={}", + p.calls, p.max_used, p.budget, p.failures + ); + } + } + result?; Ok(script.steps.len()) }); match result { diff --git a/crates/horizon-mods/src/runtime.rs b/crates/horizon-mods/src/runtime.rs index d8058f291..89d83500d 100644 --- a/crates/horizon-mods/src/runtime.rs +++ b/crates/horizon-mods/src/runtime.rs @@ -597,9 +597,28 @@ pub struct Mods { /// Moves on whenever a mod starts or stops: the game resends the server /// mods' commands to players when it changes. generation: u64, + fuel_profile: Option>, +} + +/// Observed guest fuel for one mod and callback. Host work is not metered. +#[derive(Clone, Debug, Default)] +pub struct FuelProfile { + pub calls: u64, + pub max_used: u64, + pub budget: u64, + pub failures: u64, } impl Mods { + /// Enable bounded per-callback fuel profiling. + pub fn enable_fuel_profile(&mut self) { + self.fuel_profile = Some(Default::default()); + } + pub fn fuel_profile( + &self, + ) -> Option<&std::collections::BTreeMap<(String, String), FuelProfile>> { + self.fuel_profile.as_ref() + } /// Changes whenever the running mods (so their commands) change. pub fn generation(&self) -> u64 { self.generation @@ -1017,6 +1036,17 @@ impl Mods { run.store.data_mut().storage_budget = STORAGE_WRITE_BUDGET; let started = Instant::now(); let result = run.store.set_fuel(fuel).and_then(|()| f(run)); + if let Some(profile) = &mut self.fuel_profile + && let Ok(remaining) = run.store.get_fuel() + { + let p = profile + .entry((run.store.data().id.clone(), callback.to_owned())) + .or_default(); + p.calls += 1; + p.max_used = p.max_used.max(fuel.saturating_sub(remaining)); + p.budget = fuel; + p.failures += u64::from(result.is_err()); + } // An average over about the last 64 calls. entry.cost = (entry.cost * 63 + started.elapsed()) / 64; let data = run.store.data_mut(); diff --git a/crates/horizon-mods/src/testing.rs b/crates/horizon-mods/src/testing.rs index 137b38d0c..e62404f77 100644 --- a/crates/horizon-mods/src/testing.rs +++ b/crates/horizon-mods/src/testing.rs @@ -257,6 +257,16 @@ impl TestGame { ..Snapshot::default() }); } + /// Enable recording guest fuel peaks for this run. + pub fn enable_fuel_profile(&mut self) { + self.mods.enable_fuel_profile(); + } + pub fn fuel_profile( + &self, + ) -> Option<&std::collections::BTreeMap<(String, String), crate::FuelProfile>> { + self.mods.fuel_profile() + } + /// Whether the mod is a server mod. pub fn server(&self) -> bool { self.mods.runs_server() diff --git a/crates/horizon-mods/tests/sandbox.rs b/crates/horizon-mods/tests/sandbox.rs index 6920db79a..d75f3bf8d 100644 --- a/crates/horizon-mods/tests/sandbox.rs +++ b/crates/horizon-mods/tests/sandbox.rs @@ -1589,3 +1589,24 @@ fn test_script_rejects_unexpected_command_error() { "{error}" ); } + +#[test] +fn test_game_fuel_profile_measures_guest_calls_and_traps() { + let path = mods_dir().join("horizon_mods_test_guest.hmod"); + let mut game = TestGame::load(&path).unwrap(); + assert!(game.fuel_profile().is_none()); + game.enable_fuel_profile(); + game.tick(2); + assert!(game.command("spin")); + let profile = game.fuel_profile().unwrap(); + let tick = &profile[&("test_guest".into(), "tick".into())]; + assert_eq!(tick.calls, 2); + assert!(tick.max_used > 0 && tick.max_used < tick.budget); + let command = &profile[&("test_guest".into(), "command".into())]; + assert_eq!(command.calls, 1); + assert_eq!(command.failures, 1); + assert!(command.max_used > 0 && command.max_used <= command.budget); + assert!( + matches!(&game.drain()[0], Output::Stopped { reason, .. } if reason == "it exceeded its execution limit") + ); +} diff --git a/docs/mods.md b/docs/mods.md index aad279866..c3ccedf42 100644 --- a/docs/mods.md +++ b/docs/mods.md @@ -248,6 +248,8 @@ key> --signature .minisig`. ### Testing a mod +For a fuel diagnostic, add `--fuel-profile`: each script reports callback call counts, peak guest fuel, budget and failures, even when the script fails. Host work and rendering are not measured; a reload resets the profile. + `cargo horizon-mod test` builds the mod, then runs each `tests/.toml` in the sandbox the game uses, with no game and no window: the test plays the game's part (the player and the clock the mod reads, ticks, frames, chat lines,