diff --git a/docs/ACTION_SYSTEM_ARCHITECTURE.md b/docs/ACTION_SYSTEM_ARCHITECTURE.md index 991454c..2fcdcae 100644 --- a/docs/ACTION_SYSTEM_ARCHITECTURE.md +++ b/docs/ACTION_SYSTEM_ARCHITECTURE.md @@ -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. diff --git a/docs/BUILD_IN_PUBLIC_PLAN.md b/docs/BUILD_IN_PUBLIC_PLAN.md index 5d1938b..02558ce 100644 --- a/docs/BUILD_IN_PUBLIC_PLAN.md +++ b/docs/BUILD_IN_PUBLIC_PLAN.md @@ -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: diff --git a/docs/LEARNING_ROADMAP.md b/docs/LEARNING_ROADMAP.md index 306cb61..d328dd9 100644 --- a/docs/LEARNING_ROADMAP.md +++ b/docs/LEARNING_ROADMAP.md @@ -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 diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md index d2e5eb5..69ca223 100644 --- a/docs/PROJECT_CONTEXT.md +++ b/docs/PROJECT_CONTEXT.md @@ -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: diff --git a/docs/SIMULATION_STATE_SCHEMA.md b/docs/SIMULATION_STATE_SCHEMA.md index 2064a4a..e58978b 100644 --- a/docs/SIMULATION_STATE_SCHEMA.md +++ b/docs/SIMULATION_STATE_SCHEMA.md @@ -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 diff --git a/docs/decisions/0001-simulation-authority-boundary.md b/docs/decisions/0001-simulation-authority-boundary.md index 28ebe39..fb59c4e 100644 --- a/docs/decisions/0001-simulation-authority-boundary.md +++ b/docs/decisions/0001-simulation-authority-boundary.md @@ -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