admin
3ea8f02d55
- Update ACTION_SYSTEM_ARCHITECTURE.md to describe the active-position contract and visual lifecycle proof - Mark BUILD_IN_PUBLIC_PLAN.md systems-gate section complete - Mark LEARNING_ROADMAP.md architecture-gate section complete and renumber post-gate implementation sequence - Update PROJECT_CONTEXT.md immediate-milestone section to reflect completed gate and next food-loop milestone - Update SIMULATION_STATE_SCHEMA.md with NPCStateRecord v2 details - Update ADR 0001 checklist to mark active-position sync done
83 lines
3.5 KiB
Markdown
83 lines
3.5 KiB
Markdown
# ADR 0001: Serializable simulation state is authoritative
|
|
|
|
- **Status:** Accepted
|
|
- **Date:** 2026-07-04
|
|
|
|
## Context
|
|
|
|
The prototype correctly separates `SimNPC` from `NpcVisual`, but authority is
|
|
still split across simulation records and scene nodes:
|
|
|
|
- `ResourceNode` owns remaining amount and reservations;
|
|
- `WorldViewManager` resolves targets and writes the chosen target ID onto an
|
|
NPC;
|
|
- `SimulationManager` combines time, orchestration, action completion, player
|
|
commands, and event publication;
|
|
- the visual position of an active NPC can diverge from its stored simulation
|
|
position.
|
|
|
|
This is workable for one loaded flat map. It does not support reliable
|
|
save/load, unloaded locations, deterministic replay, simulation fidelity
|
|
changes, or a large data-only population.
|
|
|
|
## Decision
|
|
|
|
Persistent mutable gameplay state will move into versioned, serializable
|
|
records owned by a `WorldState`-style simulation model.
|
|
|
|
- Definitions contain immutable action, profession, need, item, and location
|
|
data.
|
|
- State records contain people, resources, inventories, reservations,
|
|
locations, current actions, and later relationships and history.
|
|
- Systems are the only layer that authoritatively mutates those records.
|
|
- Godot world nodes present records and provide active-world facts such as
|
|
interaction transforms, navigation results, collision, and animation.
|
|
- Presentation adapters may submit commands and query results, but may not
|
|
choose actions or directly author persistent state.
|
|
- References between records use stable IDs, never `Node`, `NodePath`, or scene
|
|
ownership.
|
|
- Active-world position must synchronize through an explicit adapter so
|
|
unloading a visual does not erase or redefine the NPC's location.
|
|
|
|
The simulation core must be runnable headlessly with a fixed clock, controlled
|
|
random streams, and no dependency on a loaded gameplay scene.
|
|
|
|
## Staged migration
|
|
|
|
1. ✅ Add a deterministic clock, seeded random source, and scenario runner.
|
|
2. ✅ Introduce serializable village, NPC, and resource-state records.
|
|
3. ✅ Bind `ResourceNode` presentation to resource records instead of owning
|
|
authoritative amount and reservation.
|
|
4. ✅ Move target choice and reservation coordination out of
|
|
`WorldViewManager` into an action/target system with an active-world query
|
|
adapter.
|
|
5. ✅ Split action selection, execution, and presentation travel.
|
|
6. ✅ Synchronize active position and prove visual unload/reload
|
|
invariance.
|
|
7. Add save-slot persistence before schedules or relationships
|
|
substantially expand mutable state.
|
|
|
|
Schema v1 and its deterministic continuation contract are documented in
|
|
[the simulation state schema](../SIMULATION_STATE_SCHEMA.md).
|
|
Stable action/profession identity and immutable metadata are documented in
|
|
[the simulation definitions](../SIMULATION_DEFINITIONS.md).
|
|
System responsibilities and event flow are documented in
|
|
[the action system architecture](../ACTION_SYSTEM_ARCHITECTURE.md).
|
|
|
|
## Consequences
|
|
|
|
- Some current prototype APIs are transitional and should not be generalized
|
|
as final architecture.
|
|
- The Jajce scaffold may proceed far enough to validate terrain, navigation,
|
|
and world-object placement, but beauty production pauses at the architecture
|
|
gate.
|
|
- New persistent features must define their state record and save behavior.
|
|
- Headless scenarios become the preferred regression surface for simulation
|
|
rules.
|
|
|
|
## Revisit when
|
|
|
|
Revisit this decision only if measured prototype work shows that a different
|
|
authority model materially simplifies deterministic persistence and simulation
|
|
LOD without coupling rules to loaded scenes.
|