perf: harden runtime for weaker hardware

2026-08-12 10:02:45 +02:00
parent cd29da95e0
commit 34428d836a
47 changed files with 2164 additions and 243 deletions
@@ -0,0 +1,53 @@
+# Simulation scaling baseline 03
+
+This is the first reviewed capture of benchmark workload schema 2,
+`full_fidelity_combatant_headless_arrival_v2`. Unlike baselines 01 and 02, the
+fixture now gives every synthetic NPC exactly one authoritative combatant
+record and rejects missing, duplicate, orphaned, or mismatched coverage. It
+also exercises the current state-schema 14 conflict tick.
+
+The machine-readable samples are in
+[`simulation_scaling_baseline_03.json`](simulation_scaling_baseline_03.json).
+They were captured on the same `Apple_M1_Max_64_GB` host label with Godot 4.7,
+seed 8088, 10 warmup ticks, 200 measured ticks, and three samples per case.
+
+## Results
+
+| Case | NPCs | Seeded history | Median us/tick | Ticks/s | Simulated realtime | Arrival share | End JSON |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| Population 6 | 6 | 0 | 114.42 | 8,740.11 | 10,488.1x | 3.4% | 0.06 MiB |
+| Population 60 | 60 | 0 | 904.73 | 1,105.30 | 1,326.4x | 3.0% | 0.58 MiB |
+| Population 600 | 600 | 0 | 11,033.58 | 90.63 | 108.8x | 2.8% | 5.83 MiB |
+| History 600 | 60 | 600 | 992.78 | 1,007.28 | 1,208.7x | 2.8% | 0.72 MiB |
+| History 6,000 | 60 | 6,000 | 1,667.58 | 599.67 | 719.6x | 1.7% | 2.06 MiB |
+
+Every sample in every case produced the same final checksum. The 600-person
+fixture sustains about 90.6 ticks per second—well above the 50-tick local
+reference—while updating all 600 combatants. Indexed manager callbacks reduce
+the deterministic immediate-arrival phase to 2.8% of that case; cached
+combatant ID ordering separately bounds work inside the simulation phase.
+
+## Versioning decision
+
+Do not compare baseline-03 checksums or timings directly with baselines 01/02.
+Those reports predate combat and accidentally retained only the manager's six
+initial combatants after replacing the synthetic population. The workload ID
+and schema are bumped so this semantic change is explicit. Baselines 01/02
+remain useful historical evidence for the population-view optimization, but
+baseline 03 is the valid comparison point for future full-fidelity simulation
+changes.
+
+This still excludes world scenes, rendering, navigation, and `NpcVisual`.
+High/low gameplay-camera frame-time and GPU/memory captures on representative
+weak hardware remain a separate presentation ledger task; the data-only result
+does not claim rendered 600-NPC support.
+
+## Capture command
+
+```bash
+/Applications/Godot.app/Contents/MacOS/Godot \
+  --headless --path "$PWD" \
+  --script res://tools/benchmark_simulation_scaling.gd -- \
+  --host-label=Apple_M1_Max_64_GB \
+  --output=res://docs/benchmarks/simulation_scaling_baseline_03.json
+```