IdleSpectator harness reference

Architecture

scripts/harness-run.sh
  -> starts WorldBox if needed
  -> writes IdleSpectator/.harness/commands.jsonl
  -> touches reset + auto-dismiss
AgentHarness.Update() (in-game)
  -> executes commands on Unity main thread
  -> writes results.jsonl + last-result.json
  -> logs [HARNESS]/[ASSERT]/[SNAP]

Why not OS input?

Wayland makes xdotool/ydotool unreliable. Truth lives in engine state (MoveCamera, tips, settings), so drive the mod API directly.

Hard-won failure modes

Symptom	Cause	Fix
Welcome closes, idle never starts	commands.jsonl rewritten same length; offset at EOF	runner writes `offset=0` + `reset`
Steps run before world ready	`wait_world` requeued to back	`RequeueFront`
Tip says crab, focus is angle	watch fell back to nearest unit	require matching asset; use `pick_unit`/`asset=auto`
Spawn then "no unit for asset"	miracle spawns die on bad tiles	prefer `pick_unit` for critical paths
Flaky health/no_bad mid-scenario	ambient retarget while harness busy	`InterestDirector` returns early when `AgentHarness.Busy`
Steam hang after tests	`Application.Quit`	leave game running

Useful asserts

health - idle + focus + power bar hidden + bad==0
tip_matches_unit - tip asset equals focus unit asset; if tip starts with New species:, label species must match
no_bad - StateProbe bad counter is zero
enabled - mod setting enabled bool

Extending scenarios

Edit IdleSpectator/HarnessScenarios.cs:

Add steps with Step(id, action, ...).
Register name in Build.
Run ./scripts/harness-run.sh <name> then --repeat 3 critical_smoke.

Keep critical_smoke deterministic:

dismiss_windows / wait_world first
pick_unit before tip/focus asserts
reset_counters after spectator+focus before health
simulate_input last for manual-exit coverage

1.9 KiB Raw Blame History