diff --git a/docs/BUILD_IN_PUBLIC_PLAN.md b/docs/BUILD_IN_PUBLIC_PLAN.md index 3ee07e5..fbc8cdf 100644 --- a/docs/BUILD_IN_PUBLIC_PLAN.md +++ b/docs/BUILD_IN_PUBLIC_PLAN.md @@ -41,7 +41,8 @@ Do not redo these tasks: - hunger, energy, starvation, death, task scoring, and task duration; - task-change and village-change signals; - visual NPC navigation and arrival reporting; -- farm, forest, food, guard, study, and rest markers; +- finite berry/tree ResourceNodes plus food, guard, study, and rest activity + markers; - aggregate village UI; - initial tree assets; - a baked navigation region for the current flat test area. @@ -61,7 +62,7 @@ Main ├── SimulationManager ├── WorldViewManager ├── ActiveNPCs -├── TaskZone markers +├── ActivityMarkers ├── WorldEnvironment └── UI ``` @@ -93,7 +94,7 @@ Main │ │ └── ResourceNodes │ │ ├── BerryBush instances │ │ └── Tree instances -│ ├── LegacyTaskMarkers temporary non-resource activities +│ ├── LegacyActivityMarkers temporary non-resource activities │ │ ├── FoodZone │ │ ├── GuardZone │ │ ├── StudyZone @@ -290,7 +291,7 @@ Create `world/jajce/JajceWorld.tscn` with: - placeholder `VillageRoot`; - placeholder `FoliageRoot`; - a navigation region; -- resource-node containers plus temporary fallback markers; +- resource-node containers plus temporary activity markers; - lighting and environment. Create `JajceLookdev.tscn` that instances `JajceWorld` and adds a temporary @@ -351,14 +352,14 @@ 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 ⏭ next +### Systems gate — Harden simulation authority 🔶 in progress After the scaffold, greybox, and navigation spike prove the world shape, pause visual production and complete the mandatory architecture gate from the learning roadmap: -- deterministic clock and seeded randomness; -- fixed-seed headless scenarios and final-state checksum; +- deterministic clock and seeded randomness; ✅ +- fixed-seed headless scenarios and final-state checksum; ✅ - versioned serializable NPC, village, and resource records; - resource amount and reservation authority outside scene nodes; - stable action/profession IDs and initial definitions; @@ -406,7 +407,7 @@ Once the world composition is stable: 3. Place or move bushes and trees under `JajceWorld/WorldObjects/ResourceNodes` while preserving stable IDs. 4. Reconnect only remaining non-resource activity markers under - `JajceWorld/LegacyTaskMarkers`. + `JajceWorld/LegacyActivityMarkers`. 5. Bake navigation for the new walkable area. 6. Test each existing task from multiple spawn positions. 7. Verify task arrival still transitions from traveling to working. diff --git a/docs/LEARNING_ROADMAP.md b/docs/LEARNING_ROADMAP.md index b29dce9..cf30951 100644 --- a/docs/LEARNING_ROADMAP.md +++ b/docs/LEARNING_ROADMAP.md @@ -54,6 +54,18 @@ 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 deterministic slice is implemented: + +- `SimulationClock` advances explicit fixed ticks while preserving remainder; +- NPC decisions and visual wander requests use controlled per-NPC random + streams derived from an exported simulation seed; +- a headless scenario verifies same-seed equality, different-seed divergence, + and a final-state checksum without loading `main.tscn`. + +The gate remains open. Versioned state records, scene-independent resource +authority, stable definitions, responsibility separation, and visual +load/unload invariance are still required. + ## Three vertical slices The long-term vision contains three major risks. Validate them separately before @@ -599,8 +611,8 @@ Completed foundations: The practical next sequence is: -1. Begin the architecture gate with deterministic clock/randomness, a headless - scenario runner, final-state checksums, and serializable state records. +1. Add versioned serializable NPC, village, and resource state records, + including enough clock and RNG state for deterministic continuation. 2. Move resource amount/reservation authority out of `ResourceNode` scenes. 3. Replace free-form task and profession strings with stable IDs and definitions. diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md index 315e4df..6c015b4 100644 --- a/docs/PROJECT_CONTEXT.md +++ b/docs/PROJECT_CONTEXT.md @@ -180,8 +180,9 @@ The current prototype implements a very early version of observe, autonomous task choice, physical travel, work completion, resource change, and direct player assistance. NPC `gather_food` and `gather_wood` tasks now use finite world `ResourceNode` instances (berry bushes and trees) rather than abstract -zone markers. The zone markers remain only for player interaction and -non-resource tasks. The migration is documented in +zone markers. The obsolete farm and forest markers have been removed. Separate +temporary activity markers remain for eating, rest, study, and patrol. The +migration is documented in [the ResourceNode plan](RESOURCE_NODE_MIGRATION.md). ## Current technology @@ -214,7 +215,8 @@ plugin content, not game architecture. follow/focus behavior. - Pressing `E` near a berry bush or tree extracts its configured yield into the village through the same `ResourceNode` contract used by NPCs. -- Guard, study, and food interactions still use their temporary task zones. +- Guard, study, rest, and food interactions still use temporary activity + markers. - `Escape` releases captured mouse input. ### Village simulation @@ -288,24 +290,20 @@ result only when the task duration completes. Starvation can reduce productivity and eventually kill an NPC. Dead visuals stop moving, change appearance, and no longer collide. -### Current task zones +### Current activity markers -The main scene contains placeholder zones for: +The main scene contains placeholder activity markers for guard duty, study, +rest, and food. The former farm and forest zones and their decorative geometry +have been deleted. -- farm; -- forest; -- guard duty; -- study; -- rest; -- food. +**Migration status:** NPC `gather_food` and `gather_wood` target `ResourceNode` +instances (berry bushes and trees), with no marker fallback. The remaining +markers are direct transitional targets for non-resource NPC tasks: -The farm, forest, guard, study, rest, and food locations are represented by -primitive geometry and a few tree assets. - -**Migration status:** NPC `gather_food` and `gather_wood` no longer use the -farm and forest zones. They target `ResourceNode` instances (berry bushes and -trees) instead. The zone markers remain for: -- Non-resource NPC tasks (patrol → guard_zone, study → study_zone, rest → rest_zone, eat → food_zone) +- patrol → guard marker; +- study → study marker; +- rest → rest marker; +- eat → food marker. The player also harvests food and wood directly from nearby `ResourceNode` instances. Extraction returns the actual amount removed, updates the village by @@ -465,8 +463,10 @@ NpcVisual navigates through the active world ├── simulation/ │ ├── SimNPC.gd │ ├── SimVillage.gd +│ ├── SimulationClock.gd │ └── SimulationManager.gd ├── tests/ +│ ├── deterministic_simulation_test.gd │ ├── flat_map_baseline_test.gd │ ├── jajce_world_scaffold_test.gd │ └── resource_node_player_parity_test.gd @@ -493,14 +493,17 @@ NpcVisual navigates through the active world These are expected prototype constraints, not necessarily isolated bugs: -- Task names and task-to-zone mappings are duplicated strings. -- Task zones remain for non-resource activities; NPC and player food/wood - gathering use `ResourceNode` instances. +- Task names and task-to-activity-marker mappings are duplicated strings. +- Temporary activity markers remain for eating, rest, study, and patrol; NPC + and player food/wood gathering use `ResourceNode` instances with no fallback. - Mutable simulation state is not serializable through a defined save schema. -- Randomness is not seeded for deterministic replay. -- Simulation time depends on `_process` and a scene-tree node. -- Automated coverage currently contains one headless player-parity and - resource-contention scenario; broader simulation coverage is still missing. +- Simulation randomness is seeded and split into controlled per-NPC streams, + but RNG state is not yet part of a serializable save record. +- An explicit fixed-step clock converts frame delta into simulation ticks, but + orchestration still lives on the scene-tree `SimulationManager`. +- Automated coverage includes deterministic same-seed checksum, + player-parity/resource-contention, flat-map, and Jajce scaffold scenarios; + broader gameplay coverage is still missing. - Resources are global floating-point counters rather than items in locations and inventories. - NPCs do not have homes, schedules, possessions, memories, relationships, @@ -710,10 +713,14 @@ 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: +The architecture gate is now the active milestone. Its first slice is complete: + +- explicit fixed-step simulation clock; +- seeded per-NPC decision and wander random streams; +- headless fixed-seed scenario with a final-state checksum. + +The remaining gate work is: -- deterministic clock and controlled random source; -- fixed-seed headless scenarios with final-state checksums; - versioned serializable NPC, village, and resource state; - data-defined action and profession IDs; - separated action selection, execution, target resolution, and visual travel; diff --git a/docs/RESOURCE_NODE_MIGRATION.md b/docs/RESOURCE_NODE_MIGRATION.md index d9fd718..f5dfd9b 100644 --- a/docs/RESOURCE_NODE_MIGRATION.md +++ b/docs/RESOURCE_NODE_MIGRATION.md @@ -10,11 +10,11 @@ | **4a** | Wood target selection (NPC) | ✅ Complete | | **4b** | Player parity (extraction contract) | ✅ Complete | | **5** | Jajce world placement | 🔶 Scaffold/navigation proof complete | -| **6** | Remove remaining zone model | ❌ Not started | +| **6** | Replace remaining activity markers | 🔶 Resource zones removed; activity targets pending | ### Key divergences from the original plan -- **Zone fallback removed** (Phase 3): `gather_food`/`gather_wood` no longer fall back to `FarmZone`/`ForestZone` markers when no resource node is available. The original plan called for a logged fallback; instead, the NPC goes idle (via `navigation_failed` → wander) to guarantee resource conservation. Player harvesting also uses resource nodes; remaining zones serve only non-resource activities. +- **Zone fallback removed** (Phase 3): `gather_food`/`gather_wood` no longer fall back to `FarmZone`/`ForestZone` markers when no resource node is available. The original plan called for a logged fallback; instead, the NPC goes idle (via `navigation_failed` → wander) to guarantee resource conservation. The obsolete farm and forest scene nodes have now also been deleted. The remaining markers are temporary targets for eating, rest, study, and patrol—not resource fallbacks. - **`navigation_failed` signal** (discovered during Phase 4): Added a separate signal pathway to distinguish genuine arrival from navigation failure. The original plan treated all "arrivals" uniformly. - **Stale-path prevention** (discovered during Phase 4): Added `path_request_id` + `path_pending` to reject async path results that arrive after a new target was set or the NPC died. - **Duplicate node_id detection** (discovered during Phase 4): Added startup validation that disables nodes with duplicate IDs and pushes an error. @@ -58,8 +58,9 @@ environment is integrated. It is easier to debug target selection, reservation, depletion, and task completion without terrain and navigation changes happening at the same time. -The old zones remain only as a temporary fallback while actions are migrated. -They are not part of the target architecture. +The old resource zones have been removed. Temporary activity markers remain +only for actions whose real target type does not exist yet. They are not +fallbacks and are not part of the target architecture. ## Why this is the next systems step @@ -172,7 +173,7 @@ Main │ ├── BerryBush_02 │ ├── Tree_01 │ └── Tree_02 -└── TaskZone temporary fallback +└── ActivityMarkers temporary eat/rest/study/patrol targets ``` When `JajceWorld` is integrated, move or recreate the world-object instances @@ -493,7 +494,7 @@ deferred until after the architecture gate, so this phase is not yet complete. **Exit:** the existing food and wood loops work after moving from the flat map to Terrain3D. -### Phase 6 — Remove the remaining zone model +### Phase 6 — Replace the remaining activity-marker model This is not part of the first ResourceNode implementation. @@ -513,7 +514,14 @@ Remove each old zone only when its replacement has: - debug visibility; - save representation. -**Exit:** `TaskZone` and task-to-marker mapping are deleted, not merely unused. +**Progress:** the `TaskZone` container and obsolete `FarmZone`/`ForestZone` +nodes have been deleted from `main.tscn`. The surviving nodes live under +`ActivityMarkers` to make their transitional role explicit. Task-to-marker +mapping still exists for eating, rest, study, and patrol, so this phase is not +complete. + +**Exit:** temporary activity markers and task-to-marker mapping are deleted, +not merely unused. ## Test scenarios