admin/gamedev-the-steward
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs: update plans with phase progress, bug log, and current architecture state

Browse Source 
RESOURCE_NODE_MIGRATION.md:
- Add progress overview table with per-phase completion status
- Document key divergences from original plan (zone fallback removal,
  navigation_failed signal, stale-path prevention, duplicate detection)
- Add bug log table (11 bugs found and fixed during implementation)
- Mark completed phases 1-3 with checkmarks
- Split phase 4 into 4a (wood, done) and 4b (player parity, not started)
- Replace flat implementation order with checkable table
- Update definition-of-done with per-criterion status

PROJECT_CONTEXT.md:
- Advance snapshot commit reference from e30d208 to b8752f8
- Note that gather_food/gather_wood now use ResourceNode instances
- Explain zone marker status (player use only, NPCs use nodes)
- Update runtime flow diagram with navigation_failed pathway
- Add resource_nodes/ to repository map
- Update technical debt entries to reflect current state
This commit is contained in:
Rijad Zuzo
2026-07-04 19:31:43 +02:00
parent b8752f8835
commit f5e7326d49
2 changed files with 127 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/RESOURCE_NODE_MIGRATION.md
+83 -37
View File
@@ -1,5 +1,40 @@
# The Steward — ResourceNode Migration Plan
## Progress Overview
| Phase | Description | Status |
|-------|-------------|--------|
| **1** | ResourceNode scene + registration | ✅ Complete |
| **2** | Food target selection + reservation | ✅ Complete |
| **3** | Authoritative extraction on completion | ✅ Complete |
| **4a** | Wood target selection (NPC) | ✅ Complete |
| **4b** | Player parity (extraction contract) | ⏳ Not started |
| **5** | Jajce world placement | ❌ Not started |
| **6** | Remove remaining zone model | ❌ Not started |
### 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. The zone markers are still available for player interaction.
- **`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.
### Bugs found and fixed
| # | Bug | Phase found | Fix |
|---|-----|-------------|-----|
| 1 | Navigation failure: empty path caused NPC to idle permanently | Phase 3 stump | `_report_arrival_once()` on empty path (later replaced by `navigation_failed` signal) |
| 2 | Unavailable-target deadlock: replan didn't trigger `npc_task_changed` | Phase 3 | Set `current_task = ""` so tick detects task change and emits signal |
| 3 | Zone fallback broke conservation (fixed during Phase 4 removal) | Phase 3 | Removed zone fallback for gather tasks; NPC stays idle if no node available |
| 4 | NPC collision blocking: NPCs physically blocked each other at shared destinations | Phase 3 | `collision_layer=2`, `collision_mask=1` on NpcVisual; `arrival_distance` 0.6→1.5 (later reverted to 0.6 after navigation_failed signal) |
| 5 | Repetitive task selection: NPC chose same task every tick | Phase 3 | `last_task` tracking with -1.5 score penalty when same task repeats |
| 6 | Wander didn't wander: wandered to rest marker instead of random offset | Phase 3 | Random ±6 unit offset from current position |
| 7 | `:=` infers from Variant: warnings treated as errors from `odig` | Phase 2-3 | Use `=` instead of `:=` for calls returning `Variant` |
| 8 | `Variant as StringName`: invalid cast | Phase 2-3 | Check for `null` on Dictionary `.get()` instead of casting |
| 9 | Empty-path re-entrancy: immediate arrival report caused re-entrant signal chain | Phase 4 | Defer to `stuck_counter`/`stuck_time` in `_physics_process` instead |
| 10 | Stale async path: `await physics_frame` result used after target or death changed | Phase 4 | `path_request_id`/`path_pending` guard |
| 11 | Stolen extraction: NPC extracted from node after reservation was lost | Phase 4 | Guard extraction with `node.reserved_by == npc.id` |
## Decision
The current task zones are temporary prototype scaffolding.
@@ -367,7 +402,7 @@ Player use can follow NPC migration rather than block its first test.
## Migration phases
### Phase 1 — ResourceNode scene and registration
### ✅ Phase 1 — ResourceNode scene and registration *[complete]*
- create `ResourceNode.gd` and `ResourceNode.tscn`;
- create a `ResourceNodes` parent in `main.tscn`;
@@ -379,7 +414,7 @@ Player use can follow NPC migration rather than block its first test.
**Exit:** nodes register, validate IDs, change amount, deplete, and update debug
presentation without involving NPC logic.
### Phase 2 — Food target selection and reservation
### ✅ Phase 2 — Food target selection and reservation *[complete]*
- migrate only `gather_food`;
- find nearest available bush;
@@ -387,12 +422,13 @@ presentation without involving NPC logic.
- store its ID on the NPC;
- navigate to its interaction point;
- release on interruption and death;
- retain `FarmZone` fallback with a visible warning.
- ~~retain `FarmZone` fallback with a visible warning~~ *(removed in Phase 4,
see divergences above)*
**Exit:** two NPCs do not select the same single-user bush, and an NPC can
replan when its chosen bush becomes unavailable.
### Phase 3 — Authoritative completion
### ✅ Phase 3 — Authoritative completion *[complete]*
- extract only after work duration completes;
- return actual extracted amount;
@@ -409,15 +445,22 @@ total bush decrease == total village food increase
for the initial gather-food scenario.
### Phase 4 — Wood and player parity
### 🔶 Phase 4 — Wood and player parity *(partially complete)*
- migrate `gather_wood`;
- configure tree visuals and yields;
- route player interaction through the same extraction contract;
- add clear feedback for unavailable or depleted targets.
**Wood migration** ✅ complete:
- `gather_wood` uses `ResourceNode.find_available("gather_wood")` in WVM
- Tree_01 (15 wood, yield 3.0) and Tree_02 (12 wood, yield 3.0) placed
- Extraction follows same path as food (reserve → travel → work → extract → village resource delta)
- Zone fallback removed; NPC goes idle if no tree available
**Exit:** food and wood no longer require their abstract zones during normal
play. NPC and player extraction obey the same availability and depletion rules.
**Player parity** ⏳ not started:
- Player currently still uses zone-marker interaction in `player.gd`
- Player should use `ResourceNode.extract()` via proximity detection or raycast
- Player interaction bypasses reservation (player presses E at a node → extract if available)
- `PlayerInteraction.gd` exists as an empty stub
**Updated exit:** food and wood no longer require their abstract zones during
normal play *for NPCs*. Player parity is required to fully exit this phase.
### Phase 5 — Jajce world placement
@@ -484,34 +527,37 @@ The migration naturally creates strong short-form demonstrations:
Show the beautiful result first, then reveal target selection, reservation, and
resource conservation through debug presentation.
## Immediate implementation order
## Implementation status
1. Create `world/resource_nodes/ResourceNode.gd`.
2. Create `world/resource_nodes/ResourceNode.tscn`.
3. Add `Main/ResourceNodes`.
4. Place `BerryBush_01`, `BerryBush_02`, `Tree_01`, and `Tree_02`.
5. Add stable IDs and registration validation.
6. Verify extraction and depletion manually.
7. Add target ID to `SimNPC`.
8. Migrate `gather_food` target selection.
9. Add reservation and cleanup.
10. Apply actual extracted yield on completion.
11. Add fixed-seed regression scenarios.
12. Migrate wood.
13. Give the player the same extraction path.
14. Continue with the Jajce world scaffold.
| # | Task | Status | Commits |
|---|------|--------|---------|
| 1 | Create `ResourceNode.gd` and `ResourceNode.tscn` | ✅ Done | `9cd38a1` |
| 2 | Add `Main/ResourceNodes` | ✅ Done | `9cd38a1` |
| 3 | Place BerryBush_01, BerryBush_02, Tree_01, Tree_02 | ✅ Done | `9cd38a1` |
| 4 | Add stable IDs and registration validation | ✅ Done | `9cd38a1`, `1837bc0` |
| 5 | Verify extraction and depletion manually | ✅ Done | `9cd38a1` |
| 6 | Add target ID to `SimNPC` | ✅ Done | `9cd38a1` |
| 7 | Migrate `gather_food` target selection | ✅ Done | `9cd38a1`, `c6033b6` |
| 8 | Add reservation and cleanup | ✅ Done | `9cd38a1`, `b8752f8` |
| 9 | Apply actual extracted yield on completion | ✅ Done | `c6033b6` |
| 10 | Add navigation failure handling (replaces regression scenarios) | ✅ Done | `b8752f8` |
| 11 | Migrate wood | ✅ Done | `c6033b6`, `8049c52` |
| 12 | Give the player the same extraction path | ⏳ Not started | — |
| 13 | Continue with the Jajce world scaffold | ❌ Not started | — |
## Definition of done for the first migration
- Food and wood use actual finite world objects.
- NPCs select available targets and reserve them.
- NPC state stores stable target IDs rather than nodes or scene paths.
- Active visuals navigate to explicit interaction points.
- Work duration completes before extraction.
- Village resources increase only by the amount actually extracted.
- Depletion changes availability and presentation.
- Failure, interruption, and death release reservations.
- Old food and forest zones remain only as logged fallbacks.
- The player and NPCs can use the same extraction contract.
- Behavior is inspectable and covered by reproducible scenarios.
| Criterion | Status |
|-----------|--------|
| Food and wood use actual finite world objects | ✅ (NPCs) / ⏳ (player) |
| NPCs select available targets and reserve them | ✅ |
| NPC state stores stable target IDs rather than nodes or scene paths | ✅ |
| Active visuals navigate to explicit interaction points | ✅ |
| Work duration completes before extraction | ✅ |
| Village resources increase only by the amount actually extracted | ✅ |
| Depletion changes availability and presentation | ✅ |
| Failure, interruption, and death release reservations | ✅ |
| Old food and forest zone fallbacks are no longer used by NPCs | ✅ (fallback removed by design) |
| The player and NPCs can use the same extraction contract | ⏳ (player side not started) |
| Behavior is inspectable and covered by reproducible scenarios | ✅ (debug logging, debug overlay on nodes) |