Files

T

admin 3ea8f02d55 docs: mark simulation architecture gate complete

- 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

2026-07-05 17:21:23 +02:00

3.5 KiB

Raw Blame History

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

✅ Add a deterministic clock, seeded random source, and scenario runner.
✅ Introduce serializable village, NPC, and resource-state records.
✅ Bind ResourceNode presentation to resource records instead of owning authoritative amount and reservation.
✅ Move target choice and reservation coordination out of WorldViewManager into an action/target system with an active-world query adapter.
✅ Split action selection, execution, and presentation travel.
✅ Synchronize active position and prove visual unload/reload invariance.
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. Stable action/profession identity and immutable metadata are documented in the simulation definitions. System responsibilities and event flow are documented in the action system architecture.

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.

3.5 KiB Raw Blame History