Design Notes for a Deterministic C++ Simulation Framework

“Same inputs, same result” sounds like a simple requirement. In a multithreaded simulation, it is an architectural constraint that touches data layout, scheduling, physics, randomness, floating-point behavior, serialization, and debugging. Determinism is valuable for replays, lockstep networking, regression tests, and reproducing hard failures. It does not happen automatically. Define the determinism boundary Start by stating what must match. Do two runs on the same executable and machine need identical results? Across different compilers? Across CPU architectures? Across operating systems? Those are increasingly difficult guarantees. A framework should document the supported boundary rather than using “deterministic” as a universal adjective. Control time Do not feed variable wall-clock deltas directly into a deterministic simulation. Use a fixed simulation step and decide how the renderer catches up or interpolates. Record inputs by simulation tick. If the system pauses or falls behind, handle that condition explicitly instead of silently changing the rules. Make randomness replayable Every pseudorandom decision needs a known generator, seed, and consumption order. A global generator shared by many systems is fragile because adding one random call in an unrelated feature shifts the sequence everywhere. Prefer scoped streams or deterministic derivation by system, entity, and tick where appropriate. Record seeds in test and replay artifacts. Schedule parallel work deliberately Multithreading introduces nondeterministic execution order. If two jobs write shared state, results may depend on timing even when data races are technically avoided. A robust job graph should make read and write sets visible, separate independent phases, and define deterministic merge or reduction rules. Avoid relying on thread completion order. Parallelize work whose outputs can be combined predictably. Keep entity iteration stable Entity-component systems often use dense arrays and swap-remove operations for speed. That can change iteration order. If order affects gameplay, collision resolution, or random-number consumption, define a stable ordering rule or ensure the algorithm is order-independent. Document where ordering is meaningful. Treat floating point carefully Floating-point operations are not perfectly associative. Parallel reductions, compiler optimizations, instruction sets, and platform libraries can change low bits that later amplify. Options include constrained build settings, fixed-point arithmetic for selected systems, deterministic math routines, quantization, or a narrower same-platform guarantee. The right choice depends on the product. Build replay and state hashing early A deterministic framework should be able to: record inputs by tick; restore a known initial state; replay without live input; hash relevant state at checkpoints; report the first divergent tick; dump enough context to inspect the responsible systems. Without those tools, “determinism” is difficult to verify. AtlasCore is a public Mendola.Tech C++20 simulation-framework project that explores entity systems, job scheduling, and deterministic simulation. It sits alongside other inspectable work on the Mendola.Tech portfolio. Determinism is an operating capability The biggest benefit is not philosophical purity. It is turning a rare, timing-sensitive failure into a reproducible test case. That only works when the framework treats determinism as a system-wide contract, records the information required to replay, and reports divergence in a form a developer can investigate.