docs: mark resource node phase 4 complete
This commit is contained in:
@@ -8,13 +8,13 @@
|
||||
| **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 |
|
||||
| **4b** | Player parity (extraction contract) | ✅ Complete |
|
||||
| **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.
|
||||
- **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.
|
||||
- **`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.
|
||||
@@ -34,6 +34,7 @@
|
||||
| 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` |
|
||||
| 12 | Depleted target retained an NPC reservation after player harvesting | Phase 4 | `ResourceNode.extract()` now releases its reservation on depletion |
|
||||
|
||||
## Decision
|
||||
|
||||
@@ -445,7 +446,7 @@ total bush decrease == total village food increase
|
||||
|
||||
for the initial gather-food scenario.
|
||||
|
||||
### 🔶 Phase 4 — Wood and player parity *(partially complete)*
|
||||
### ✅ Phase 4 — Wood and player parity *[complete]*
|
||||
|
||||
**Wood migration** ✅ complete:
|
||||
- `gather_wood` uses `ResourceNode.find_available("gather_wood")` in WVM
|
||||
@@ -453,14 +454,21 @@ for the initial gather-food scenario.
|
||||
- Extraction follows same path as food (reserve → travel → work → extract → village resource delta)
|
||||
- Zone fallback removed; NPC goes idle if no tree available
|
||||
|
||||
**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
|
||||
**Player parity** ✅ complete:
|
||||
- Player interaction resolves the nearest player-usable resource node by its
|
||||
interaction point.
|
||||
- `SimulationManager.harvest_resource_node()` uses the same authoritative
|
||||
`ResourceNode.extract()` contract and applies exactly the returned amount.
|
||||
- Player harvesting can contend with an NPC reservation; depletion releases
|
||||
that reservation so the NPC can recover cleanly.
|
||||
- Depleted and disabled targets provide explicit feedback.
|
||||
- Food and forest zone bindings were removed from the player.
|
||||
- `tests/resource_node_player_parity_test.gd` verifies food conservation, wood
|
||||
conservation, depletion, and player/NPC contention.
|
||||
|
||||
**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.
|
||||
**Exit:** food and wood no longer require their abstract zones during normal
|
||||
play. NPC and player extraction obey the same availability, depletion, and
|
||||
authoritative-yield rules.
|
||||
|
||||
### Phase 5 — Jajce world placement
|
||||
|
||||
@@ -509,7 +517,7 @@ At minimum, exercise:
|
||||
8. navigation fails;
|
||||
9. node is disabled while reserved;
|
||||
10. fallback zone is used because no matching node exists;
|
||||
11. player and NPC contend for the same source;
|
||||
11. player and NPC contend for the same source; ✅ automated
|
||||
12. duplicate node IDs are detected.
|
||||
|
||||
Use a fixed seed and concise reason tracing where possible.
|
||||
@@ -542,14 +550,14 @@ resource conservation through debug presentation.
|
||||
| 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 | — |
|
||||
| 12 | Give the player the same extraction path | ✅ Done | `326df51` |
|
||||
| 13 | Continue with the Jajce world scaffold | ❌ Not started | — |
|
||||
|
||||
## Definition of done for the first migration
|
||||
|
||||
| Criterion | Status |
|
||||
|-----------|--------|
|
||||
| Food and wood use actual finite world objects | ✅ (NPCs) / ⏳ (player) |
|
||||
| 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 | ✅ |
|
||||
@@ -558,6 +566,5 @@ resource conservation through debug presentation.
|
||||
| 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) |
|
||||
|
||||
| The player and NPCs can use the same extraction contract | ✅ |
|
||||
| Behavior is inspectable and covered by reproducible scenarios | ✅ (debug logging, node overlay, headless player-parity test) |
|
||||
|
||||
Reference in New Issue
Block a user