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:
@@ -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.
|
||||||
|
|||||||
@@ -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
@@ -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;
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user