Refactoring the Statecraft Simulation Foundation
A look at the architectural decisions behind Statecraft's simulation layer — deterministic time, typed transitions, and why we rebuilt the foundation.
When we first began prototyping Statecraft, our primary goal was to get a basic political and economic loop running as quickly as possible. That early architecture served its purpose—it proved that our core concepts were engaging—but as we layered on complexity, cracks began to show. The interactions between systems became unpredictable, saving and loading complex states became brittle, and debugging emergent behaviors felt like chasing ghosts.
Recognizing these limitations early, we made the decision to rebuild the simulation layer from the ground up. This article explores the architectural decisions behind the new Statecraft simulation foundation and why these technical choices are critical for the game's long-term viability.
The Need for Deterministic Time
In a complex simulation, time cannot simply be tied to the real-world clock or the frame rate of the rendering engine. If the simulation relies on wall-clock time, minor fluctuations in hardware performance can lead to wildly different outcomes.
To ensure consistency, we implemented a strictly deterministic time system. The Statecraft simulation advances in discrete, predictable "ticks." A given initial state, processed through a specific number of ticks with identical inputs, will always result in the exact same final state, regardless of the hardware it runs on.
This determinism is foundational. It makes automated testing possible, it simplifies debugging by allowing us to reliably reproduce complex systemic interactions, and it guarantees that a player's experience is governed by the rules of the simulation, not the speed of their processor.
Persistence: Reliable Save and Restore
A simulation as deep as Statecraft generates an enormous amount of state data—economic ledgers, relationship networks, demographic shifts, and individual actor memories. The legacy architecture handled serialization in a piecemeal fashion, which occasionally led to corrupted saves or "amnesiac" actors upon reloading.
The new foundation treats the entire world state as a single, cohesive data structure. By ensuring that our core state tree is strictly serializable, we can take perfect snapshots of the simulation at any given tick. This means players can save their game with total confidence, knowing that the intricate web of systemic consequences they've set in motion will be restored precisely as they left it.
Atomic Transactions
In a living world, actions rarely happen in isolation. If an actor purchases a business, several things must happen simultaneously: currency must be deducted from the buyer, ownership must be transferred, and the seller must receive the funds. If a bug occurs halfway through this process, the simulation could end up in an invalid state—say, the money is gone but the ownership never transferred.
To prevent this, world state changes in the new architecture are handled via atomic transactions. A transition is proposed, evaluated, and then either fully applied or fully rolled back. There are no partial updates. This transactional approach guarantees the integrity of the simulation data, preventing the kind of "leaky" economies or phantom assets that plague many complex simulation games.
Modelling Long-Running Commitments
Not all actions resolve in a single tick. Education, employment contracts, political terms, and infrastructure construction are all long-running commitments that span multiple time steps.
Our legacy system handled these with ad-hoc timers scattered throughout the codebase. The new foundation introduces a unified scheduling and commitment system. When an actor enrolls in a university, a formal commitment is registered with the simulation engine. The engine manages the progression of this commitment over time, handling intermediate state changes and final resolution without the actor entity needing to constantly check its own status. This dramatically simplifies the logic for autonomous actors and reduces overhead.
Typed World Transitions
To further bulletproof the simulation, we implemented strongly typed world transitions. Rather than allowing arbitrary modifications to the state tree, every possible change to the world—a transaction, a movement, an attitude shift—must be instantiated as a specific, typed transition object.
This type system acts as a strict set of guardrails. It defines exactly what constitutes a valid state change before it is ever processed by the transactional engine. By catching invalid transitions at compile time or during initial validation, we significantly reduce runtime bugs and make the behavior of the simulation vastly more predictable for our engineers.
Integrating Autonomous Actors
With the transactional foundation in place, integrating autonomous actors became much cleaner. Instead of directly manipulating the world state, NPCs now observe the state and submit proposed transitions to the engine.
During a simulation tick, the engine processes actor decision-making logic, gathers their proposed actions, resolves conflicts (e.g., two actors trying to buy the same property), and then applies the successful transactions. This separation of "decision" and "execution" ensures that the simulation rules are applied fairly and consistently to both the player and the AI.
Why This Matters
To a player, a game's architecture is largely invisible—until it fails. Bad architecture creates visible bugs, economic exploits, inconsistent AI, and hard limitations on future features.
The decision to refactor the Statecraft simulation foundation was not made lightly, but it was necessary. By establishing a robust system of deterministic time, atomic transactions, and typed transitions, we have built a stable platform. This work is foundational; it gives us the confidence to implement increasingly complex social and economic systems, knowing that the underlying engine can handle the weight.