gamedev-the-steward/docs/SIMULATION_STATE_SCHEMA.md

The Steward — Simulation State Schema

Current contract

SimulationStateRecord is the versioned JSON boundary for the current simulation. Schema v1 captures:

• simulation seed, tick interval, tick count, clock remainder, and elapsed clock ticks;
• every NPC's identity, needs, attributes, task lifecycle, target, position, starvation state, and decision RNG stream;
• village resource counters;
• controlled per-NPC wander RNG streams;
• loaded ResourceNode amount, reservation, and enabled state.

The top-level identity is:

{
  "schema": "the_steward.simulation",
  "schema_version": 1
}

Unknown schema versions and structurally incomplete records are rejected. Add an explicit migration function before accepting a future version; never silently reinterpret old data as the newest layout.

Deterministic continuation

RNG seeds and internal states are encoded as decimal strings. They are signed 64-bit values and cannot safely pass through every JSON number implementation without precision loss. Converting them to ordinary JSON numbers caused a restored simulation to retain the same visible state while silently changing its future random sequence.

tests/simulation_state_serialization_test.gd protects this contract by:

1. running a fixed-seed scenario for 48 ticks without interruption;
2. running the same scenario for 24 ticks;
3. serializing and restoring into a fresh manager;
4. running the remaining 24 ticks;
5. requiring the complete final-state checksums to match.

It also verifies clock remainder, ResourceNode amount/reservation/enabled round-tripping, and rejection of unsupported schemas.

Transitional resource boundary

Schema v1 can capture and restore loaded ResourceNode state, but the scene node still owns the live amount and reservation. That is transitional support, not the final authority model.

The next architecture-gate phase moves those values into scene-independent resource records. ResourceNode will then bind to a record by stable ID and act as presentation plus an active-world interaction surface. An unloaded resource must remain simulated and serializable.

Deliberately out of scope

This phase does not yet provide:

• save-slot files, metadata, thumbnails, or atomic disk writes;
• backward migrations beyond schema v1;
• inventory, relationship, schedule, or history records;
• a player-facing load flow;
• scene-independent resource authority.

Those features should build on this boundary rather than inventing parallel serialization paths.