docs: update architecture gate progress

BUILD_IN_PUBLIC_PLAN.md:
- Mark systems gate items deterministic clock and headless checksum
  as complete; remaining gate work stays flagged as in-progress
- Rename TaskZone references to ActivityMarkers for consistency

LEARNING_ROADMAP.md:
- Add architecture gate progress note: first deterministic slice
  (SimulationClock, seeded streams, headless checksum) is implemented
- Update recommended implementation order to reflect shifted priorities

PROJECT_CONTEXT.md:
- Note that farm and forest markers have been deleted from main.tscn
- Update activity marker description (4 remaining: guard/study/rest/food)
- Add SimulationClock.gd and deterministic_simulation_test.gd to repo map
- Update technical debt: randomness is now seeded but RNG state is not
  yet serialized; clock is explicit but orchestration still lives on scene tree
- Gate status updated with completed first-slice summary

RESOURCE_NODE_MIGRATION.md:
- Mark Phase 4b (player parity) complete
- Phase 6 renamed from 'remove zone model' to 'replace activity markers'
  with progress note: TaskZone container and FarmZone/ForestZone deleted
- Update divergences to note farm/forest scene nodes have been removed
This commit is contained in:
2026-07-05 11:23:19 +02:00
parent 37610242bf
commit c690937afa
4 changed files with 73 additions and 45 deletions
+9 -8
View File
@@ -41,7 +41,8 @@ Do not redo these tasks:
- hunger, energy, starvation, death, task scoring, and task duration; - hunger, energy, starvation, death, task scoring, and task duration;
- task-change and village-change signals; - task-change and village-change signals;
- visual NPC navigation and arrival reporting; - 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; - aggregate village UI;
- initial tree assets; - initial tree assets;
- a baked navigation region for the current flat test area. - a baked navigation region for the current flat test area.
@@ -61,7 +62,7 @@ Main
├── SimulationManager ├── SimulationManager
├── WorldViewManager ├── WorldViewManager
├── ActiveNPCs ├── ActiveNPCs
├── TaskZone markers ├── ActivityMarkers
├── WorldEnvironment ├── WorldEnvironment
└── UI └── UI
``` ```
@@ -93,7 +94,7 @@ Main
│ │ └── ResourceNodes │ │ └── ResourceNodes
│ │ ├── BerryBush instances │ │ ├── BerryBush instances
│ │ └── Tree instances │ │ └── Tree instances
│ ├── LegacyTaskMarkers temporary non-resource activities │ ├── LegacyActivityMarkers temporary non-resource activities
│ │ ├── FoodZone │ │ ├── FoodZone
│ │ ├── GuardZone │ │ ├── GuardZone
│ │ ├── StudyZone │ │ ├── StudyZone
@@ -290,7 +291,7 @@ Create `world/jajce/JajceWorld.tscn` with:
- placeholder `VillageRoot`; - placeholder `VillageRoot`;
- placeholder `FoliageRoot`; - placeholder `FoliageRoot`;
- a navigation region; - a navigation region;
- resource-node containers plus temporary fallback markers; - resource-node containers plus temporary activity markers;
- lighting and environment. - lighting and environment.
Create `JajceLookdev.tscn` that instances `JajceWorld` and adds a temporary 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 Terrain3D seed remains flat; sculpt refinement and the final bake resume only
after the architecture gate. 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 After the scaffold, greybox, and navigation spike prove the world shape, pause
visual production and complete the mandatory architecture gate from the visual production and complete the mandatory architecture gate from the
learning roadmap: learning roadmap:
- deterministic clock and seeded randomness; - deterministic clock and seeded randomness;
- fixed-seed headless scenarios and final-state checksum; - fixed-seed headless scenarios and final-state checksum;
- versioned serializable NPC, village, and resource records; - versioned serializable NPC, village, and resource records;
- resource amount and reservation authority outside scene nodes; - resource amount and reservation authority outside scene nodes;
- stable action/profession IDs and initial definitions; - 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 3. Place or move bushes and trees under
`JajceWorld/WorldObjects/ResourceNodes` while preserving stable IDs. `JajceWorld/WorldObjects/ResourceNodes` while preserving stable IDs.
4. Reconnect only remaining non-resource activity markers under 4. Reconnect only remaining non-resource activity markers under
`JajceWorld/LegacyTaskMarkers`. `JajceWorld/LegacyActivityMarkers`.
5. Bake navigation for the new walkable area. 5. Bake navigation for the new walkable area.
6. Test each existing task from multiple spawn positions. 6. Test each existing task from multiple spawn positions.
7. Verify task arrival still transitions from traveling to working. 7. Verify task arrival still transitions from traveling to working.
+14 -2
View File
@@ -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 loading `main.tscn`, and loading or unloading a visual does not change
authoritative NPC or resource state. 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 ## Three vertical slices
The long-term vision contains three major risks. Validate them separately before The long-term vision contains three major risks. Validate them separately before
@@ -599,8 +611,8 @@ Completed foundations:
The practical next sequence is: The practical next sequence is:
1. Begin the architecture gate with deterministic clock/randomness, a headless 1. Add versioned serializable NPC, village, and resource state records,
scenario runner, final-state checksums, and serializable state records. including enough clock and RNG state for deterministic continuation.
2. Move resource amount/reservation authority out of `ResourceNode` scenes. 2. Move resource amount/reservation authority out of `ResourceNode` scenes.
3. Replace free-form task and profession strings with stable IDs and 3. Replace free-form task and profession strings with stable IDs and
definitions. definitions.
+35 -28
View File
@@ -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 task choice, physical travel, work completion, resource change, and direct
player assistance. NPC `gather_food` and `gather_wood` tasks now use finite player assistance. NPC `gather_food` and `gather_wood` tasks now use finite
world `ResourceNode` instances (berry bushes and trees) rather than abstract world `ResourceNode` instances (berry bushes and trees) rather than abstract
zone markers. The zone markers remain only for player interaction and zone markers. The obsolete farm and forest markers have been removed. Separate
non-resource tasks. The migration is documented in temporary activity markers remain for eating, rest, study, and patrol. The
migration is documented in
[the ResourceNode plan](RESOURCE_NODE_MIGRATION.md). [the ResourceNode plan](RESOURCE_NODE_MIGRATION.md).
## Current technology ## Current technology
@@ -214,7 +215,8 @@ plugin content, not game architecture.
follow/focus behavior. follow/focus behavior.
- Pressing `E` near a berry bush or tree extracts its configured yield into the - Pressing `E` near a berry bush or tree extracts its configured yield into the
village through the same `ResourceNode` contract used by NPCs. 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. - `Escape` releases captured mouse input.
### Village simulation ### Village simulation
@@ -288,24 +290,20 @@ result only when the task duration completes.
Starvation can reduce productivity and eventually kill an NPC. Dead visuals Starvation can reduce productivity and eventually kill an NPC. Dead visuals
stop moving, change appearance, and no longer collide. 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; **Migration status:** NPC `gather_food` and `gather_wood` target `ResourceNode`
- forest; instances (berry bushes and trees), with no marker fallback. The remaining
- guard duty; markers are direct transitional targets for non-resource NPC tasks:
- study;
- rest;
- food.
The farm, forest, guard, study, rest, and food locations are represented by - patrol → guard marker;
primitive geometry and a few tree assets. - study → study marker;
- rest → rest marker;
**Migration status:** NPC `gather_food` and `gather_wood` no longer use the - eat → food marker.
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)
The player also harvests food and wood directly from nearby `ResourceNode` The player also harvests food and wood directly from nearby `ResourceNode`
instances. Extraction returns the actual amount removed, updates the village by instances. Extraction returns the actual amount removed, updates the village by
@@ -465,8 +463,10 @@ NpcVisual navigates through the active world
├── simulation/ ├── simulation/
│ ├── SimNPC.gd │ ├── SimNPC.gd
│ ├── SimVillage.gd │ ├── SimVillage.gd
│ ├── SimulationClock.gd
│ └── SimulationManager.gd │ └── SimulationManager.gd
├── tests/ ├── tests/
│ ├── deterministic_simulation_test.gd
│ ├── flat_map_baseline_test.gd │ ├── flat_map_baseline_test.gd
│ ├── jajce_world_scaffold_test.gd │ ├── jajce_world_scaffold_test.gd
│ └── resource_node_player_parity_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: These are expected prototype constraints, not necessarily isolated bugs:
- Task names and task-to-zone mappings are duplicated strings. - Task names and task-to-activity-marker mappings are duplicated strings.
- Task zones remain for non-resource activities; NPC and player food/wood - Temporary activity markers remain for eating, rest, study, and patrol; NPC
gathering use `ResourceNode` instances. and player food/wood gathering use `ResourceNode` instances with no fallback.
- Mutable simulation state is not serializable through a defined save schema. - Mutable simulation state is not serializable through a defined save schema.
- Randomness is not seeded for deterministic replay. - Simulation randomness is seeded and split into controlled per-NPC streams,
- Simulation time depends on `_process` and a scene-tree node. but RNG state is not yet part of a serializable save record.
- Automated coverage currently contains one headless player-parity and - An explicit fixed-step clock converts frame delta into simulation ticks, but
resource-contention scenario; broader simulation coverage is still missing. 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 - Resources are global floating-point counters rather than items in locations
and inventories. and inventories.
- NPCs do not have homes, schedules, possessions, memories, relationships, - 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 greybox, navigation spike, and stable-ID placement proof are complete. Do not
proceed directly from that proof into open-ended beauty production. 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; - versioned serializable NPC, village, and resource state;
- data-defined action and profession IDs; - data-defined action and profession IDs;
- separated action selection, execution, target resolution, and visual travel; - separated action selection, execution, target resolution, and visual travel;
+15 -7
View File
@@ -10,11 +10,11 @@
| **4a** | Wood target selection (NPC) | ✅ Complete | | **4a** | Wood target selection (NPC) | ✅ Complete |
| **4b** | Player parity (extraction contract) | ✅ Complete | | **4b** | Player parity (extraction contract) | ✅ Complete |
| **5** | Jajce world placement | 🔶 Scaffold/navigation proof 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 ### 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. - **`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. - **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. - **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 depletion, and task completion without terrain and navigation changes happening
at the same time. at the same time.
The old zones remain only as a temporary fallback while actions are migrated. The old resource zones have been removed. Temporary activity markers remain
They are not part of the target architecture. 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 ## Why this is the next systems step
@@ -172,7 +173,7 @@ Main
│ ├── BerryBush_02 │ ├── BerryBush_02
│ ├── Tree_01 │ ├── Tree_01
│ └── Tree_02 │ └── Tree_02
└── TaskZone temporary fallback └── ActivityMarkers temporary eat/rest/study/patrol targets
``` ```
When `JajceWorld` is integrated, move or recreate the world-object instances 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 **Exit:** the existing food and wood loops work after moving from the flat map
to Terrain3D. 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. This is not part of the first ResourceNode implementation.
@@ -513,7 +514,14 @@ Remove each old zone only when its replacement has:
- debug visibility; - debug visibility;
- save representation. - 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 ## Test scenarios