Sim::step phase timing and the CPU-profile bench driver (#147 step 3.1)

Mod side: Sim::step times plan_step, adapt, step_drones, step_moves,
update_sight, step_sams and record, plus the whole step and its untimed
remainder, through sim::profile. The simulation stays SDK-independent (also
built as airdef-core): the adapter installs the host monotonic clock
(game.monotonic-nanos) in init, native tests use std::time::Instant. The
counters are fixed-size, per-thread, read no randomness and change no
decision; /airdef stats reports them as PROFILE chat lines, reset per world.

Driver: raid_bench gains --scheduler in-frame|server-thread (the two
single-player paths, measured separately), HORIZON_MOD_CPU_PROFILE=1, the
per-tick mod-path spans joined to the frame trace (per-frame totals, >25/33 ms
counts, what the worst CPU frames carry), and the mod phase profile read at
idle and battle end with the battle delta. report.json carries mod_cpu,
mod_cpu_ticks, mod_phases_* and the derived correlation. Tests for the new
helpers.

Engine gitlink: mod-path CPU spans + game.monotonic-nanos (API level 32).

Co-Authored-By: Kimi Code <noreply@moonshot.ai>
This commit is contained in:
2026-11-21 12:29:22 +03:00
parent c08b737296
commit 92c058f606
6 changed files with 368 additions and 28 deletions
+28 -15
View File
@@ -1229,6 +1229,8 @@ impl AirDef {
let shader = self.sim.shader;
let seed = game::get_clock().map_or(0x5eed, |c| c.game_time.wrapping_mul(2654435761) ^ 0x9e37);
self.sim = Sim::new(seed);
// A fresh world's CPU profile starts from zero (#147 step 3.1).
sim::profile::reset();
self.next_save = 0;
self.sim.shader = shader;
self.ground = Ground::default();
@@ -1916,6 +1918,10 @@ fn help() -> String {
impl Mod for AirDef {
fn init() -> Result<(Self, Registration), String> {
// The CPU profile's clock (#147 step 3.1): the host's monotonic import.
// Native tests keep the process clock (the import is a wasm-only stub).
#[cfg(target_arch = "wasm32")]
sim::profile::set_clock(game::monotonic_nanos);
let seed = game::get_clock().map_or(0x5eed, |c| c.game_time.wrapping_mul(2654435761) ^ 0x9e37);
let mut me = AirDef {
sim: Sim::new(seed),
@@ -2798,21 +2804,28 @@ impl Mod for AirDef {
}
None
}
["stats"] => Some(format!(
"В воздухе: {}, ракет: {}, ПВО: {}, сбито: {}, поражений: {}, разбились о препятствия: {}; удары по ПУ: пущено {}, уничтожено {}, подавлено {}, промахов {}, сбито ПВО {}; {}",
self.sim.drones.iter().filter(|d| d.alive()).count(),
self.sim.missiles.len(),
self.sim.sams.len(),
self.sim.kills,
self.sim.hits,
self.sim.crashes,
self.sim.strikes.fired,
self.sim.strikes.destroyed,
self.sim.strikes.stunned,
self.sim.strikes.missed,
self.sim.strikes.shot_down,
world_view::text(&self.ground.world)
)),
["stats"] => {
// The CPU profile's per-phase wall time (#147 step 3.1), as its
// own chat lines so the bench can read them from the log.
for l in sim::profile::report() {
say(&l);
}
Some(format!(
"В воздухе: {}, ракет: {}, ПВО: {}, сбито: {}, поражений: {}, разбились о препятствия: {}; удары по ПУ: пущено {}, уничтожено {}, подавлено {}, промахов {}, сбито ПВО {}; {}",
self.sim.drones.iter().filter(|d| d.alive()).count(),
self.sim.missiles.len(),
self.sim.sams.len(),
self.sim.kills,
self.sim.hits,
self.sim.crashes,
self.sim.strikes.fired,
self.sim.strikes.destroyed,
self.sim.strikes.stunned,
self.sim.strikes.missed,
self.sim.strikes.shot_down,
world_view::text(&self.ground.world)
))
}
_ => return Err(help()),
};
self.emit(out);
+12 -8
View File
@@ -41,6 +41,7 @@ pub mod outcome;
mod units;
pub mod why;
pub mod world;
pub mod profile;
#[cfg(test)]
mod balance;
#[cfg(test)]
@@ -1752,25 +1753,27 @@ impl Sim {
});
}
/// One game tick.
/// One game tick. The named phases are timed for the CPU profile (#147 step
/// 3.1); the timing reads no randomness and changes no decision.
pub fn step(&mut self, ground: &mut Ground, player: Option<DVec3>, out: &mut Out) {
profile::begin_step();
self.tick += 1;
self.plan_step(Some(&mut *ground), out);
self.adapt();
profile::time(profile::PLAN, || self.plan_step(Some(&mut *ground), out));
profile::time(profile::ADAPT, || self.adapt());
self.step_refresh(out);
self.step_settling(ground);
self.release_queue(ground, out);
self.begin_recording_if_active();
self.step_drones(ground, player, out);
profile::time(profile::DRONES, || self.step_drones(ground, player, out));
self.step_recon(out);
self.step_later(ground, player, out);
self.step_moves(ground, out);
profile::time(profile::MOVES, || self.step_moves(ground, out));
self.step_supply(out);
self.step_ew(out);
self.update_sight(ground);
profile::time(profile::SIGHT, || self.update_sight(ground));
self.step_lights(ground, out);
self.prepare_ground_strikes(out);
self.step_sams(ground, out);
profile::time(profile::SAMS, || self.step_sams(ground, out));
self.step_missiles(ground, out);
self.step_strikes(ground, player, out);
self.step_fx(ground, out);
@@ -1779,9 +1782,10 @@ impl Sim {
self.step_wrecks(out);
self.step_fires(ground, out);
self.report_wave(out);
self.record();
profile::time(profile::RECORD, || self.record());
let now = self.tick;
self.blasts.retain(|b| now - b.start < b.life as u64);
profile::end_step();
}
// ------------------------------------------------ drones
+149
View File
@@ -0,0 +1,149 @@
//! Per-phase wall time of `Sim::step` (#147 step 3.1): observation only, never
//! a combat input. The simulation stays SDK-independent (it is also built as
//! `airdef-core`), so the adapter installs the host clock
//! (`game.monotonic-nanos`, API level 32) with [`set_clock`] before the first
//! tick; native tests fall back to `std::time::Instant`. The counters are
//! fixed-size and per-thread (a mod instance is single-threaded); timing reads
//! no randomness and changes no decision, so the ordered combat trace is
//! identical with or without it.
use std::cell::RefCell;
/// The named phases of `Sim::step`, as indices into the counters.
pub const PLAN: usize = 0;
pub const ADAPT: usize = 1;
pub const DRONES: usize = 2;
pub const MOVES: usize = 3;
pub const SIGHT: usize = 4;
pub const SAMS: usize = 5;
pub const RECORD: usize = 6;
const NAMED: usize = 7;
/// The phases' report names, in index order.
const NAMES: [&str; NAMED] = ["plan", "adapt", "drones", "moves", "sight", "sams", "record"];
#[derive(Default)]
struct Prof {
total_ns: [u64; NAMED],
max_ns: [u64; NAMED],
steps: u64,
step_ns: u64,
step_max_ns: u64,
other_ns: u64,
other_max_ns: u64,
cur_start: u64,
cur_named: u64,
}
thread_local! {
static PROF: RefCell<Prof> = const { RefCell::new(Prof {
total_ns: [0; NAMED],
max_ns: [0; NAMED],
steps: 0,
step_ns: 0,
step_max_ns: 0,
other_ns: 0,
other_max_ns: 0,
cur_start: 0,
cur_named: 0,
}) };
}
/// The clock the adapter installs (the host's monotonic import); none in native
/// tests, which use the process clock below.
static CLOCK: std::sync::OnceLock<fn() -> u64> = std::sync::OnceLock::new();
/// Installs the monotonic clock, once, before the first timed step.
pub fn set_clock(f: fn() -> u64) {
let _ = CLOCK.set(f);
}
fn now_ns() -> u64 {
match CLOCK.get() {
Some(f) => f(),
None => native_now_ns(),
}
}
#[cfg(not(target_arch = "wasm32"))]
fn native_now_ns() -> u64 {
use std::time::Instant;
static EPOCH: std::sync::OnceLock<Instant> = std::sync::OnceLock::new();
EPOCH.get_or_init(Instant::now).elapsed().as_nanos() as u64
}
/// Only reached if the adapter never installed a clock; the mod always does in
/// `init`, so the counters stay zero rather than reading an unsupported clock.
#[cfg(target_arch = "wasm32")]
fn native_now_ns() -> u64 {
0
}
/// Marks the start of one `Sim::step`.
pub fn begin_step() {
let start = now_ns();
PROF.with(|p| {
let p = &mut *p.borrow_mut();
p.cur_start = start;
p.cur_named = 0;
});
}
/// Times one named phase: its wall time joins the phase's counters and the
/// step's named sum, so `end_step` can derive the untimed remainder.
pub fn time<T>(phase: usize, f: impl FnOnce() -> T) -> T {
let start = now_ns();
let out = f();
let dt = now_ns().saturating_sub(start);
PROF.with(|p| {
let p = &mut *p.borrow_mut();
p.total_ns[phase] += dt;
p.max_ns[phase] = p.max_ns[phase].max(dt);
p.cur_named += dt;
});
out
}
/// Marks the end of one `Sim::step`: the whole step and its untimed remainder.
pub fn end_step() {
let end = now_ns();
PROF.with(|p| {
let p = &mut *p.borrow_mut();
let total = end.saturating_sub(p.cur_start);
let other = total.saturating_sub(p.cur_named);
p.steps += 1;
p.step_ns += total;
p.step_max_ns = p.step_max_ns.max(total);
p.other_ns += other;
p.other_max_ns = p.other_max_ns.max(other);
});
}
/// Clears the counters (a new world opens).
pub fn reset() {
PROF.with(|p| *p.borrow_mut() = Prof::default());
}
/// Parseable chat lines for `/airdef stats`: each `PROFILE key=value ...` with
/// millisecond totals and per-step maxima (three decimals) and the step count.
/// `other` is the whole step minus the named phases. Split to stay under the
/// game's 256-character chat line; the bench merges every `PROFILE` line.
pub fn report() -> Vec<String> {
PROF.with(|p| {
let p = p.borrow();
let ms = |ns: u64| ns as f64 / 1e6;
let phase = |i: usize| {
format!(
"{}_ms={:.3} {}_max_ms={:.3}",
NAMES[i], ms(p.total_ns[i]), NAMES[i], ms(p.max_ns[i]),
)
};
vec![
format!(
"PROFILE steps={} step_ms={:.3} step_max_ms={:.3} other_ms={:.3} other_max_ms={:.3}",
p.steps, ms(p.step_ns), ms(p.step_max_ns), ms(p.other_ns), ms(p.other_max_ns),
),
format!("PROFILE {} {} {} {}", phase(0), phase(1), phase(2), phase(3)),
format!("PROFILE {} {} {}", phase(4), phase(5), phase(6)),
]
})
}
+1 -1
Submodule horizon updated: 3428a571bd...d073783f55
+124 -4
View File
@@ -76,6 +76,8 @@ BENCH_SECONDS = {"idle_cold": 4, "idle_warm": 6, "battle": 10, "replay": 12}
SETTLE_TICKS = 500 # 25 с: LOD сходится, как в методике #126
REPLAY_WARM_TICKS = 100 # 5 с записи до окна замера
STATS_RE = re.compile(r"В воздухе: (\d+), ракет: (\d+), ПВО: (\d+), сбито: (\d+), поражений: (\d+)")
# The mod's per-phase CPU profile lines (#147 step 3.1): `PROFILE key=value ...`.
PROFILE_RE = re.compile(r"(\w+)=(-?\d+(?:\.\d+)?)")
class BenchError(RuntimeError):
@@ -114,6 +116,96 @@ def frame_summary(raw):
return out
def parse_profile(lines):
"""Merge the mod's `PROFILE key=value` chat lines into one dict (#147 3.1)."""
out = {}
for line in lines:
if "PROFILE" not in line:
continue
for key, val in PROFILE_RE.findall(line):
out[key] = float(val) if "." in val else int(val)
return out
def profile_delta(base, battle):
"""Battle phase work = cumulative-at-battle-end minus cumulative-at-idle.
Totals and the step count subtract; per-step maxima are kept from the battle
reading (the peak almost always falls in the battle, not the idle warm-up).
"""
if not base or not battle:
return None
out = {}
for key, val in battle.items():
if key.endswith("_max_ms"):
out[key] = val
elif key in base:
out[key] = round(val - base[key], 3) if isinstance(val, float) else val - base[key]
else:
out[key] = val
return out
# The mod-path spans, in the order the engine records them per tick.
MOD_SPANS = ("ground_ms", "world_ms", "snapshot_ms", "wasm_ms", "models_ms", "output_ms", "total_ms")
def mod_cpu_frames(window):
"""Join the per-tick mod-path spans to the frame trace (#147 step 3.1).
A frame may run several game ticks; their spans sum into that frame's index
(`frame` in each record is the index into the raw frame arrays). Returns the
per-frame mod-path total's percentiles, the >25/33 ms frame counts, and what
the worst CPU frames carry — so the mod peaks can be checked against the
frame-time peaks. None when no spans were recorded.
"""
ticks = window.get("mod_cpu_ticks") or []
frames = window.get("frame_ms") or []
if not ticks or not frames:
return None
n = len(frames)
per = [[0.0] * len(MOD_SPANS) for _ in range(n)]
seen = set()
for t in ticks:
f = int(t.get("frame", 0))
if 0 <= f < n:
seen.add(f)
for j, key in enumerate(MOD_SPANS):
per[f][j] += t.get(key, 0.0)
total = [row[MOD_SPANS.index("total_ms")] for row in per]
wasm = [row[MOD_SPANS.index("wasm_ms")] for row in per]
world = [row[MOD_SPANS.index("world_ms")] for row in per]
models = [row[MOD_SPANS.index("models_ms")] for row in per]
out = {
"ticks": len(ticks),
"frames_with_ticks": len(seen),
"per_frame_total_ms": {
"p50_ms": percentile(total, 0.5),
"p95_ms": percentile(total, 0.95),
"p99_ms": percentile(total, 0.99),
"max_ms": max(total),
},
"frames_mod_over_25ms": sum(1 for v in total if v > 25.0),
"frames_mod_over_33ms": sum(1 for v in total if v > 33.0),
}
cpu = window.get("cpu_ms") or []
if cpu:
# The worst 1% of frames by CPU time: how much mod-path work they carry.
order = sorted(range(len(cpu)), key=lambda i: cpu[i], reverse=True)
worst = order[:max(1, len(order) // 100)]
m = len(worst)
out["worst_cpu_frames"] = {
"count": m,
"avg_cpu_ms": sum(cpu[i] for i in worst) / m,
"avg_mod_total_ms": sum(total[i] for i in worst if i < n) / m,
"avg_wasm_ms": sum(wasm[i] for i in worst if i < n) / m,
"avg_world_ms": sum(world[i] for i in worst if i < n) / m,
"avg_models_ms": sum(models[i] for i in worst if i < n) / m,
"with_mod_tick": sum(1 for i in worst if i in seen),
}
return out
def git_sha(cwd):
r = subprocess.run(["git", "rev-parse", "HEAD"], cwd=cwd, capture_output=True, text=True)
return r.stdout.strip() if r.returncode == 0 else None
@@ -127,7 +219,8 @@ def git_branch(cwd):
class Driver:
"""Одна игра на своём сокете; команды horizon-ctl и ожидание по тикам."""
def __init__(self, out, game, resources, mod, extra_env, width, height):
def __init__(self, out, game, resources, mod, extra_env, width, height,
scheduler="in-frame"):
self.out = Path(out).resolve()
self.home = self.out / "home"
self.sock = self.out / "c.sock"
@@ -137,6 +230,8 @@ class Driver:
self.mod = Path(mod).resolve()
self.extra_env = dict(extra_env)
self.width, self.height = width, height
# #147 step 3.1: the two single-player schedulers, measured separately.
self.scheduler = scheduler
self.t0 = None
# --- запуск ---
@@ -163,6 +258,7 @@ class Driver:
"HORIZON_NO_AUDIO": "1",
"HORIZON_LAUNCHER_NO_SELF_UPDATE": "1",
"HORIZON_MOD_FUEL_PROFILE": "1",
"HORIZON_MOD_CPU_PROFILE": "1",
"HORIZON_HD_SCALE": "1",
"HORIZON_SPIKES": "0",
})
@@ -174,8 +270,12 @@ class Driver:
self.sock.unlink()
cmd = [str(CTL), "--socket", str(self.sock), "launch",
"--world", "Polygon", "--creative", "--offscreen", "--wait",
"--in-frame", "--width", str(self.width), "--height", str(self.height),
"--width", str(self.width), "--height", str(self.height),
"--game", str(self.game), "--resources", str(self.resources)]
# in-frame: the window ticks the world itself; server-thread (the default
# players run): the integrated server on its own thread, the window a client.
if self.scheduler == "in-frame":
cmd.append("--in-frame")
with open(self.log, "w") as log:
r = subprocess.run(cmd, text=True, env=self.env(),
cwd=self.home, timeout=600, stdout=log, stderr=subprocess.STDOUT)
@@ -231,6 +331,12 @@ class Driver:
def stats(self, raw=True):
return self.ctl_json("stats", "raw" if raw else "", timeout=120.0)
def mod_profile(self):
"""The mod's cumulative per-phase CPU profile (`/airdef stats` chat lines)."""
self.chat("/airdef stats")
time.sleep(0.3)
return parse_profile(self.chat_log(20))
def bench(self, seconds):
"""bench N: сброс счётчиков, окно N секунд, summary + сырые времена."""
self.ctl("bench", str(seconds), timeout=seconds + 120.0)
@@ -315,7 +421,8 @@ def static_parity(args):
env = dict(kv.split("=", 1) for kv in args.env)
env.update({"HORIZON_HD_TAA": "0", "HORIZON_HD_WIND": "0",
"HORIZON_HD_CLOUDS": "0", "HORIZON_HD_VOLFOG": "0"})
d = Driver(args.out, args.game, args.resources, args.mod, env, args.width, args.height)
d = Driver(args.out, args.game, args.resources, args.mod, env, args.width, args.height,
scheduler=args.scheduler)
d.prepare()
d.launch()
out = Path(args.out).resolve()
@@ -345,11 +452,14 @@ def static_parity(args):
def run(args):
d = Driver(args.out, args.game, args.resources, args.mod,
dict(kv.split("=", 1) for kv in args.env), args.width, args.height)
dict(kv.split("=", 1) for kv in args.env), args.width, args.height,
scheduler=args.scheduler)
d.prepare()
d.launch()
report = {
"issue": 147,
"step": "3.1",
"scheduler": args.scheduler,
"label": args.label,
"timestamp": datetime.datetime.now().isoformat(timespec="seconds"),
"git": {
@@ -382,10 +492,16 @@ def run(args):
"pending_chunks": d.status().get("pending_chunks"),
"lod": d.status().get("lod"),
}
# Cumulative mod phase profile before the battle (the idle baseline).
report["mod_phases_idle"] = d.mod_profile()
# Бой по фиксированным тикам; окно замера в середине боя (в потоке).
fingerprints = d.battle(report)
report["battle_fingerprints"] = fingerprints
# Cumulative mod phase profile after the battle; the delta isolates it.
report["mod_phases_battle"] = d.mod_profile()
report["mod_phases_battle_delta"] = profile_delta(
report["mod_phases_idle"], report["mod_phases_battle"])
# Та же запись в обоих путях, один процесс: бой записан один раз, replay
# проигрывает его идентично в каждом окне. Межпроцессные бои расходятся
@@ -456,6 +572,7 @@ def run(args):
for name, window in report["windows"].items():
raw = {k: window.get(k) for k in ("frame_ms", "cpu_ms", "gpu_ms")}
window["derived"] = frame_summary(raw)
window["derived"]["mod_cpu_frames"] = mod_cpu_frames(window)
print(f"{name}: frames={window.get('frames')} "
f"cpu p95={window['derived']['cpu_ms']['p95_ms']} "
f"p99={window['derived']['cpu_ms']['p99_ms']}")
@@ -554,6 +671,9 @@ def main():
help="подготовленные ресурсы 26.3 (или HORIZON_RESOURCES)")
p.add_argument("--mod", help="собранный airdef.hmod (один и тот же в A/B)")
p.add_argument("--env", action="append", default=[], metavar="КЛЮЧ=ЗНАЧЕНИЕ")
p.add_argument("--scheduler", choices=("in-frame", "server-thread"), default="in-frame",
help="single-player scheduler: in-frame (window ticks the world) или "
"server-thread (интегрированный сервер на своём потоке, путь по умолчанию)")
p.add_argument("--width", type=int, default=1280)
p.add_argument("--height", type=int, default=720)
p.add_argument("--compare", nargs="+", metavar="REPORT",
+54
View File
@@ -63,5 +63,59 @@ class Battle(unittest.TestCase):
self.assertIsNone(rb.STATS_RE.search("ВОЗДУШНАЯ ТРЕВОГА"))
class CpuProfile(unittest.TestCase):
def test_parse_profile_merges_lines_and_skips_others(self):
lines = [
"В воздухе: 40, ракет: 12, ПВО: 14, сбито: 3, поражений: 1",
"PROFILE steps=200 step_ms=100.500 step_max_ms=6.250 other_ms=10.000 other_max_ms=1.500",
"[AirDef] PROFILE plan_ms=40.000 plan_max_ms=4.500 adapt_ms=2.000 adapt_max_ms=0.500 "
"drones_ms=20.000 drones_max_ms=2.000 moves_ms=5.000 moves_max_ms=1.000",
"PROFILE sight_ms=15.000 sight_max_ms=3.000 sams_ms=8.000 sams_max_ms=2.000 "
"record_ms=10.500 record_max_ms=1.250",
]
p = rb.parse_profile(lines)
self.assertEqual(p["steps"], 200)
self.assertEqual(p["step_ms"], 100.5)
self.assertEqual(p["plan_max_ms"], 4.5)
self.assertEqual(p["record_ms"], 10.5)
self.assertNotIn("воздухе", p)
def test_profile_delta_subtracts_totals_keeps_max(self):
base = {"steps": 100, "plan_ms": 10.0, "plan_max_ms": 2.0, "step_ms": 50.0}
battle = {"steps": 300, "plan_ms": 90.0, "plan_max_ms": 6.0, "step_ms": 250.0}
d = rb.profile_delta(base, battle)
self.assertEqual(d["steps"], 200)
self.assertEqual(d["plan_ms"], 80.0)
self.assertEqual(d["step_ms"], 200.0)
self.assertEqual(d["plan_max_ms"], 6.0) # max kept, not subtracted
self.assertIsNone(rb.profile_delta({}, battle))
def test_mod_cpu_frames_joins_ticks_to_frames(self):
# Two frames; frame 0 runs two ticks, frame 1 one tick.
window = {
"frame_ms": [16.0, 40.0],
"cpu_ms": [10.0, 35.0],
"mod_cpu_ticks": [
{"frame": 0, "tick": 1, "wasm_ms": 5.0, "world_ms": 1.0, "models_ms": 1.0, "total_ms": 8.0},
{"frame": 0, "tick": 2, "wasm_ms": 6.0, "world_ms": 1.0, "models_ms": 1.0, "total_ms": 9.0},
{"frame": 1, "tick": 3, "wasm_ms": 20.0, "world_ms": 2.0, "models_ms": 3.0, "total_ms": 26.0},
],
}
a = rb.mod_cpu_frames(window)
self.assertEqual(a["ticks"], 3)
self.assertEqual(a["frames_with_ticks"], 2)
self.assertEqual(a["per_frame_total_ms"]["max_ms"], 26.0) # frame 1
self.assertEqual(a["frames_mod_over_25ms"], 1)
self.assertEqual(a["frames_mod_over_33ms"], 0)
# The worst CPU frame (index 1) carries the 26 ms mod tick.
self.assertEqual(a["worst_cpu_frames"]["avg_mod_total_ms"], 26.0)
self.assertEqual(a["worst_cpu_frames"]["avg_wasm_ms"], 20.0)
self.assertEqual(a["worst_cpu_frames"]["with_mod_tick"], 1)
def test_mod_cpu_frames_empty(self):
self.assertIsNone(rb.mod_cpu_frames({}))
self.assertIsNone(rb.mod_cpu_frames({"frame_ms": [1.0], "mod_cpu_ticks": []}))
if __name__ == "__main__":
unittest.main()