ue5-deterministic-sim-tests

Deterministic Simulation and Evidence

"The code is written" is not evidence. Neither is "it compiles", "it looks right", or a screenshot of the editor. For agent-driven development this matters more than usual, because the agent cannot see the game and the human is not watching every run.

The cheapest evidence in a vehicle-combat game is a seeded headless match: run twenty full AI matches in seconds, with no rendering, and assert every one terminated with a legal winner. That single test catches AI stalls, unclosable endgames, scoring bugs, and match-flow regressions at once — and it costs nothing to re-run on every change.

Establish the determinism contract first

Determinism is not a feature you add later. It is a set of constraints you either adopt at the start or pay dearly to retrofit.

1. Fixed logic timestep. Gameplay state advances on a fixed step, accumulated from real time. Rendering interpolates. Anything gameplay-authoritative that integrates with a variable DeltaTime is non-deterministic by construction.
2. Seeded streams, one per subsystem, all derived from a single match seed. Never a global RNG. See references/determinism-rules.md.
3. No gameplay reads from presentation. Physics-driven visual motion, particle state, and animation must not influence outcomes. This is the rule that makes headless running possible at all.
4. No frame-rate-dependent smoothing in gameplay code — time constants, never per-frame lerp factors.
5. Iteration order must be stable. Iterating a hash map whose order varies between runs silently breaks determinism in a way that is very hard to find.
6. Simulation must link without rendering. Enforced by module boundaries — see ue5-project-context.
7. Decide the tolerance. Bit-exact is achievable if you are careful with floating point; "same winner, same seed" is much cheaper and usually sufficient. Pick one and state it, because it determines how strict every assertion must be.