71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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.
|