docs: update plans with phase progress, bug log, and current architecture state
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 frome30d208tob8752f8- 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:
+44
-24
@@ -2,7 +2,7 @@
|
||||
|
||||
> Agent-facing context for understanding the project quickly.
|
||||
>
|
||||
> Snapshot basis: repository state after commit `e30d208`, July 2026. Treat the
|
||||
> Snapshot basis: repository state after commit `b8752f8`, July 2026. Treat the
|
||||
> code as the source of truth when this document and the implementation differ.
|
||||
|
||||
## Quick orientation
|
||||
@@ -176,15 +176,17 @@ The intended loop is:
|
||||
|
||||
The current prototype implements a very early version of observe, autonomous
|
||||
task choice, physical travel, work completion, resource change, and direct
|
||||
player assistance. Its abstract task zones are explicitly transitional; the
|
||||
next world-object migration is documented in
|
||||
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
|
||||
[the ResourceNode plan](RESOURCE_NODE_MIGRATION.md).
|
||||
|
||||
## Current technology
|
||||
|
||||
- **Engine:** Godot 4.7 project configuration
|
||||
- **Renderer feature:** Forward Plus
|
||||
- **Language:** GDScript
|
||||
- **Language:** GDScript (`odig` analysis with warnings treated as errors)
|
||||
- **Main scene:** `res://main.tscn`
|
||||
- **Terrain:** Terrain3D 1.0.2 is installed and enabled
|
||||
- **Terrain compatibility floor:** Godot 4.4 according to the bundled extension
|
||||
@@ -253,6 +255,8 @@ Task states are:
|
||||
|
||||
```text
|
||||
idle -> traveling -> working -> complete -> idle
|
||||
|
|
||||
+-> navigation_failed -> wander -> idle
|
||||
```
|
||||
|
||||
NPCs currently choose among:
|
||||
@@ -293,10 +297,15 @@ The main scene contains placeholder zones for:
|
||||
The farm, forest, guard, study, rest, and food locations are represented by
|
||||
primitive geometry and a few tree assets.
|
||||
|
||||
These markers are not the intended long-term work model. Food and wood should
|
||||
first migrate to finite world `ResourceNode` instances. Storage, rest, study,
|
||||
and guard behavior should later migrate to target types that match their actual
|
||||
semantics rather than treating every usable object as a resource source.
|
||||
**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:
|
||||
- Player interaction (pressing E near farm/forest zones adds resources)
|
||||
- Non-resource NPC tasks (patrol → guard_zone, study → study_zone, rest → rest_zone, eat → food_zone)
|
||||
|
||||
Storage, rest, study, and guard behavior should later migrate to target types
|
||||
that match their actual semantics rather than treating every usable object as a
|
||||
resource source.
|
||||
|
||||
### Current UI
|
||||
|
||||
@@ -381,25 +390,32 @@ SimNPC updates needs and chooses/advances a task
|
||||
npc_task_changed signal
|
||||
|
|
||||
v
|
||||
WorldViewManager selects a task-zone marker
|
||||
WorldViewManager resolves target:
|
||||
gather_food/wood -> nearest available ResourceNode (interaction point)
|
||||
wander -> random offset from current position
|
||||
other -> task-zone marker (guard, study, rest, eat)
|
||||
|
|
||||
v
|
||||
NpcVisual navigates through the active world
|
||||
|
|
||||
v
|
||||
arrived_at_target signal
|
||||
+-- arrived_at_target signal
|
||||
| |
|
||||
| v
|
||||
| SimulationManager marks NPC as working
|
||||
| |
|
||||
| v
|
||||
| Later ticks complete work
|
||||
| |
|
||||
| v
|
||||
| ResourceNode.extract() -> village.apply_resource_delta()
|
||||
| |
|
||||
| v
|
||||
| village_changed signal updates the UI
|
||||
|
|
||||
v
|
||||
SimulationManager marks the NPC as working
|
||||
|
|
||||
v
|
||||
Later ticks complete work
|
||||
|
|
||||
v
|
||||
SimVillage applies production/consumption
|
||||
|
|
||||
v
|
||||
village_changed signal updates the UI
|
||||
+-- navigation_failed signal
|
||||
|
|
||||
v
|
||||
SimulationManager releases reservation, sets last_task, sends NPC to wander
|
||||
```
|
||||
|
||||
## Repository map
|
||||
@@ -422,6 +438,10 @@ village_changed signal updates the UI
|
||||
│ ├── SimVillage.gd
|
||||
│ └── SimulationManager.gd
|
||||
├── world/
|
||||
│ ├── resource_nodes/
|
||||
│ │ ├── ResourceNode.gd
|
||||
│ │ ├── ResourceNode.gd.uid
|
||||
│ │ └── ResourceNode.tscn
|
||||
│ ├── world_view_manager.gd
|
||||
│ └── ui/ui.gd
|
||||
├── main.tscn
|
||||
@@ -433,7 +453,7 @@ village_changed signal updates the UI
|
||||
These are expected prototype constraints, not necessarily isolated bugs:
|
||||
|
||||
- Task names and task-to-zone mappings are duplicated strings.
|
||||
- Task zones are abstract destinations rather than real usable world objects.
|
||||
- Task zones remain for non-resource tasks and player interaction; gather food/wood NPCs use ResourceNode instances instead.
|
||||
- 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.
|
||||
@@ -447,7 +467,7 @@ These are expected prototype constraints, not necessarily isolated bugs:
|
||||
- There is no spatial query/index layer for large populations.
|
||||
- Simulation, orchestration, and player-facing mutation APIs are concentrated
|
||||
in `SimulationManager`.
|
||||
- Path failure and interruption behavior is minimal.
|
||||
- Path failure and interruption emit a `navigation_failed` signal and send the NPC to wander; this is functional but not yet polished.
|
||||
- Terrain3D is enabled but not yet used by the main game scene.
|
||||
- Combat, companions, factions, politics, trade, rumours, quests, persistence,
|
||||
and regional travel do not yet exist.
|
||||
|
||||
Reference in New Issue
Block a user