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
This commit is contained in:
2026-07-05 17:21:23 +02:00
parent a8ae331f51
commit 3ea8f02d55
6 changed files with 52 additions and 35 deletions
+16 -10
View File
@@ -63,16 +63,22 @@ targets, and translates presentation callbacks into simulation transitions.
Further decomposition should follow measured pressure rather than splitting it
into managers for their own sake.
## Remaining architecture-gate gap
## Active-position contract
The resolver currently asks WorldViewManager for a visual's position at target
request time. SimNPC also stores a position, but active movement is not yet
synchronized back through an explicit authority contract.
NpcVisual emits active position changes after successful movement.
WorldViewManager forwards those facts through
`SimulationManager.synchronize_npc_position()`. Arrival, navigation failure,
and visual unload also perform a final synchronization.
The next phase must:
SimNPC stores both authoritative position and the resolved travel destination.
The destination is versioned simulation state, so reloading a visual resumes
the same route request without rerolling wander, resolving another resource, or
changing a reservation.
- define when active position is written to simulation state;
- preserve the last authoritative position when a visual unloads;
- spawn a reloaded visual from that position;
- prove visual unload/reload does not change action, target, reservation, or
position state.
`tests/npc_visual_lifecycle_test.gd` proves that visual unload/reload preserves
action, target ID, travel destination, resource reservation, position, and
state checksum.
Unloaded NPCs do not yet resolve abstract travel time; they remain in their
current task state until an active visual or a future simulation-LOD travel
system advances them.
+6 -2
View File
@@ -352,7 +352,7 @@ river, and waterfall silhouettes plus a temporary baked navigation loop. The
Terrain3D seed remains flat; sculpt refinement and the final bake resume only
after the architecture gate.
### Systems gate — Harden simulation authority 🔶 in progress
### Systems gate — Harden simulation authority ✅ complete
After the scaffold, greybox, and navigation spike prove the world shape, pause
visual production and complete the mandatory architecture gate from the
@@ -364,7 +364,7 @@ learning roadmap:
- resource amount and reservation authority outside scene nodes; ✅
- stable action/profession IDs and initial definitions; ✅
- separate action selection, execution, target resolution, and visual travel; ✅
- explicit active-position synchronization.
- explicit active-position synchronization.
Do not solve this by moving simulation ownership into `JajceWorld`. The
environment remains a presentation and active-world query surface.
@@ -375,6 +375,10 @@ The same scenario produces the same result without `main.tscn`; unloading a
visual does not change authoritative state; current resource and movement
behavior still pass regression tests.
Completed with deterministic continuation, simulation-owned resources,
definition-backed IDs, separated action responsibilities, active position
synchronization, and visual unload/reload invariance tests.
### Phase 3 — Establish the beauty baseline
Add only the highest-value presentation:
+11 -11
View File
@@ -54,7 +54,7 @@ The gate is complete when the same scenario produces the same checksum without
loading `main.tscn`, and loading or unloading a visual does not change
authoritative NPC or resource state.
**Current progress:** the first five architecture slices are implemented:
**Status: complete.** All architecture-gate slices are implemented:
- `SimulationClock` advances explicit fixed ticks while preserving remainder;
- NPC decisions and visual wander requests use controlled per-NPC random
@@ -78,9 +78,12 @@ authoritative NPC or resource state.
respective rules;
- ActiveWorldAdapter supplies loaded-world facts, while WorldViewManager only
supplies visual position and executes emitted travel requests.
- active movement synchronizes into authoritative NPC position state;
- persisted travel destinations let visuals unload/reload without changing
actions, targets, reservations, positions, RNG state, or checksums.
The gate remains open. Active-position synchronization and NPC visual
load/unload invariance are still required. See
The fixed-seed scenario runs without `main.tscn`, and visual lifecycle
invariance is covered headlessly. See
[the action system architecture](ACTION_SYSTEM_ARCHITECTURE.md),
[the simulation definitions](SIMULATION_DEFINITIONS.md) and
[the simulation state schema](SIMULATION_STATE_SCHEMA.md).
@@ -630,17 +633,14 @@ Completed foundations:
The practical next sequence is:
1. Define active-position synchronization and prove visual unload/reload.
2. Pass the architecture gate's deterministic headless and unloaded-visual exit
tests.
3. Build location-based food storage, inventory, and transactions.
4. Emit structured economic events while making one NPC visibly gather, carry,
1. Build location-based food storage, inventory, and transactions.
2. Emit structured economic events while making one NPC visibly gather, carry,
store, retrieve, and eat food.
5. Add save-slot persistence and explicit schema migrations before schedules
3. Add save-slot persistence and explicit schema migrations before schedules
or social state expand.
6. Resume Terrain3D sculpting, runtime integration, and the simulation-garden
4. Resume Terrain3D sculpting, runtime integration, and the simulation-garden
beauty pass.
7. Add stylized character and profession readability plus the reason
5. Add stylized character and profession readability plus the reason
inspector.
This order strengthens the simulation while regularly producing visible
+12 -10
View File
@@ -469,6 +469,7 @@ NpcVisual navigates through the active world
│ ├── deterministic_simulation_test.gd
│ ├── flat_map_baseline_test.gd
│ ├── jajce_world_scaffold_test.gd
│ ├── npc_visual_lifecycle_test.gd
│ ├── resource_node_player_parity_test.gd
│ ├── simulation_definitions_test.gd
│ └── simulation_state_serialization_test.gd
@@ -515,6 +516,8 @@ These are expected prototype constraints, not necessarily isolated bugs:
goals, or social knowledge.
- NPC reasoning is logged but not presented through an in-game inspector.
- Active navigation is used as if all agents are local; no simulation LOD exists.
- Unloaded traveling NPCs preserve their state but do not yet advance through
abstract travel time.
- There is no spatial query/index layer for large populations.
- SimulationManager still orchestrates multiple systems and player-facing
mutation APIs, but selection, execution, target resolution, and active-world
@@ -715,12 +718,8 @@ visual milestone should support or reveal actual simulation state.
## Immediate milestone: scaffold, architecture gate, then simulation garden
Food and wood migration and the deliberately minimal `JajceWorld` scaffold,
greybox, navigation spike, and stable-ID placement proof are complete. Do not
proceed directly from that proof into open-ended beauty production.
The architecture gate is now the active milestone. Its first five slices are
complete:
Food and wood migration, the minimal `JajceWorld` proof, and the mandatory
architecture gate are complete:
- explicit fixed-step simulation clock;
- seeded per-NPC decision and wander random streams;
@@ -732,11 +731,14 @@ complete:
- stable StringName action/profession IDs plus validated custom definition
resources used by simulation, targeting, generation, and persistence;
- separate selection, execution, target resolution, active-world query, and
visual travel responsibilities.
visual travel responsibilities;
- authoritative active position and persisted travel destinations;
- checksum-invariant NPC visual unload/reload with reservation preservation.
The remaining gate work is:
- explicit synchronization of active NPC position.
The next systems milestone is a complete location-based food loop: storage,
inventory, carrying, depositing, withdrawing, and eating through transactions.
Bounded Terrain3D look-development can resume, but runtime terrain integration
should remain coordinated with that visible systems slice.
The coherent visual slice can then aim for:
+5
View File
@@ -52,6 +52,11 @@ It also verifies clock remainder, resource amount/reservation/enabled
round-tripping, presentation unload/rebind, and rejection of unsupported
schemas.
NPCStateRecord v2 adds the resolved travel destination and whether it is
active. Nested v1 NPC records migrate explicitly with no invented active
destination. This allows a reloaded visual to resume travel without changing
target selection or deterministic RNG state.
## Resource authority
`SimulationManager` owns `ResourceStateRecord` instances independently of the
@@ -52,9 +52,9 @@ random streams, and no dependency on a loaded gameplay scene.
`WorldViewManager` into an action/target system with an active-world query
adapter.
5. ✅ Split action selection, execution, and presentation travel.
6. **Next:** Synchronize active position and prove visual unload/reload
6. Synchronize active position and prove visual unload/reload
invariance.
7. Add versioned save/load before inventories, schedules, or relationships
7. Add save-slot persistence before schedules or relationships
substantially expand mutable state.
Schema v1 and its deterministic continuation contract are documented in