docs: mark action separation phase complete
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# The Steward — Action System Architecture
|
||||
|
||||
## Current flow
|
||||
|
||||
```text
|
||||
SimulationManager tick
|
||||
-> ActionExecutionSystem advances needs and working progress
|
||||
-> ActionSelectionSystem chooses an action when the NPC is idle
|
||||
-> SimulationManager stores the selected action
|
||||
-> npc_target_requested
|
||||
-> WorldViewManager supplies the active visual's current position
|
||||
-> ActionTargetResolver consumes simulation state + ActiveWorldAdapter facts
|
||||
-> SimulationManager stores/reserves the target
|
||||
-> npc_travel_requested
|
||||
-> WorldViewManager commands NpcVisual travel
|
||||
-> arrival/navigation failure returns to SimulationManager
|
||||
```
|
||||
|
||||
## Responsibilities
|
||||
|
||||
### ActionSelectionSystem
|
||||
|
||||
- reads NPC and village state;
|
||||
- evaluates current utility scores;
|
||||
- consumes the NPC's deterministic decision RNG;
|
||||
- returns an action ID and optional urgent-duration override;
|
||||
- does not mutate targets, navigation, or visuals.
|
||||
|
||||
### ActionExecutionSystem
|
||||
|
||||
- advances hunger, energy, starvation, death, and working progress;
|
||||
- marks an action complete when its duration elapses;
|
||||
- does not select the next action or resolve a target.
|
||||
|
||||
### ActionTargetResolver
|
||||
|
||||
- reads target metadata from ActionDefinition;
|
||||
- consumes active-world facts through ActiveWorldAdapter;
|
||||
- checks simulation-owned ResourceStateRecord availability;
|
||||
- reserves and returns stable resource target IDs;
|
||||
- returns activity or wander positions without owning presentation.
|
||||
|
||||
### ActiveWorldAdapter
|
||||
|
||||
- exposes loaded resource interaction positions;
|
||||
- maps current temporary activity markers to action IDs;
|
||||
- contains active-world query facts, not persistent mutable authority;
|
||||
- does not choose actions or reserve resources.
|
||||
|
||||
### WorldViewManager
|
||||
|
||||
- spawns and tracks NpcVisual instances;
|
||||
- supplies a visual's current position when resolution is requested;
|
||||
- applies travel commands;
|
||||
- reports arrival, navigation failure, and visual death state;
|
||||
- does not map actions, select targets, write target IDs, or mutate resources.
|
||||
|
||||
### SimulationManager
|
||||
|
||||
SimulationManager remains the orchestrator and event boundary. It owns
|
||||
simulation records, invokes the focused systems, stores selected actions and
|
||||
targets, and translates presentation callbacks into simulation transitions.
|
||||
Further decomposition should follow measured pressure rather than splitting it
|
||||
into managers for their own sake.
|
||||
|
||||
## Remaining architecture-gate gap
|
||||
|
||||
The resolver currently asks WorldViewManager for a visual's position at target
|
||||
request time. SimNPC also stores a position, but active movement is not yet
|
||||
synchronized back through an explicit authority contract.
|
||||
|
||||
The next phase must:
|
||||
|
||||
- define when active position is written to simulation state;
|
||||
- preserve the last authoritative position when a visual unloads;
|
||||
- spawn a reloaded visual from that position;
|
||||
- prove visual unload/reload does not change action, target, reservation, or
|
||||
position state.
|
||||
@@ -363,7 +363,7 @@ learning roadmap:
|
||||
- versioned serializable NPC, village, resource, clock, and RNG records; ✅
|
||||
- resource amount and reservation authority outside scene nodes; ✅
|
||||
- stable action/profession IDs and initial definitions; ✅
|
||||
- separate action selection, execution, target resolution, and visual travel;
|
||||
- separate action selection, execution, target resolution, and visual travel; ✅
|
||||
- explicit active-position synchronization.
|
||||
|
||||
Do not solve this by moving simulation ownership into `JajceWorld`. The
|
||||
|
||||
+15
-12
@@ -54,7 +54,7 @@ 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
|
||||
authoritative NPC or resource state.
|
||||
|
||||
**Current progress:** the first four architecture slices are implemented:
|
||||
**Current progress:** the first five architecture slices are implemented:
|
||||
|
||||
- `SimulationClock` advances explicit fixed ticks while preserving remainder;
|
||||
- NPC decisions and visual wander requests use controlled per-NPC random
|
||||
@@ -74,9 +74,14 @@ authoritative NPC or resource state.
|
||||
actions and professions;
|
||||
- NPC duration/preference logic, resource target metadata, generation, and
|
||||
serialized references resolve through the definition registry.
|
||||
- focused selection, execution, and target-resolution systems now own their
|
||||
respective rules;
|
||||
- ActiveWorldAdapter supplies loaded-world facts, while WorldViewManager only
|
||||
supplies visual position and executes emitted travel requests.
|
||||
|
||||
The gate remains open. Responsibility separation and NPC visual load/unload
|
||||
invariance are still required. See
|
||||
The gate remains open. Active-position synchronization and NPC visual
|
||||
load/unload invariance are still required. See
|
||||
[the action system architecture](ACTION_SYSTEM_ARCHITECTURE.md),
|
||||
[the simulation definitions](SIMULATION_DEFINITIONS.md) and
|
||||
[the simulation state schema](SIMULATION_STATE_SCHEMA.md).
|
||||
|
||||
@@ -625,19 +630,17 @@ Completed foundations:
|
||||
|
||||
The practical next sequence is:
|
||||
|
||||
1. Separate action selection, execution, target resolution, and visual travel;
|
||||
remove decision mutation from `WorldViewManager`.
|
||||
2. Define active-position synchronization and prove visual unload/reload.
|
||||
3. Pass the architecture gate's deterministic headless and unloaded-visual exit
|
||||
1. Define active-position synchronization and prove visual unload/reload.
|
||||
2. Pass the architecture gate's deterministic headless and unloaded-visual exit
|
||||
tests.
|
||||
4. Build location-based food storage, inventory, and transactions.
|
||||
5. Emit structured economic events while making one NPC visibly gather, carry,
|
||||
3. Build location-based food storage, inventory, and transactions.
|
||||
4. Emit structured economic events while making one NPC visibly gather, carry,
|
||||
store, retrieve, and eat food.
|
||||
6. Add save-slot persistence and explicit schema migrations before schedules
|
||||
5. Add save-slot persistence and explicit schema migrations before schedules
|
||||
or social state expand.
|
||||
7. Resume Terrain3D sculpting, runtime integration, and the simulation-garden
|
||||
6. Resume Terrain3D sculpting, runtime integration, and the simulation-garden
|
||||
beauty pass.
|
||||
8. Add stylized character and profession readability plus the reason
|
||||
7. Add stylized character and profession readability plus the reason
|
||||
inspector.
|
||||
|
||||
This order strengthens the simulation while regularly producing visible
|
||||
|
||||
+18
-17
@@ -409,18 +409,14 @@ The UI subscribes to village changes and formats aggregate village state.
|
||||
|
||||
```text
|
||||
SimulationManager tick
|
||||
|
|
||||
v
|
||||
SimNPC updates needs and chooses/advances a task
|
||||
|
|
||||
v
|
||||
npc_task_changed signal
|
||||
|
|
||||
v
|
||||
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)
|
||||
-> ActionExecutionSystem advances needs/work
|
||||
-> ActionSelectionSystem chooses an action for idle NPCs
|
||||
-> npc_target_requested
|
||||
-> WorldViewManager supplies the active visual position
|
||||
-> ActionTargetResolver consumes ActiveWorldAdapter facts
|
||||
-> SimulationManager stores/reserves the target
|
||||
-> npc_travel_requested
|
||||
-> WorldViewManager commands visual travel
|
||||
|
|
||||
v
|
||||
NpcVisual navigates through the active world
|
||||
@@ -465,9 +461,11 @@ NpcVisual navigates through the active world
|
||||
│ ├── SimVillage.gd
|
||||
│ ├── SimulationClock.gd
|
||||
│ ├── SimulationManager.gd
|
||||
│ ├── actions/ Selection, execution, and target resolution
|
||||
│ ├── definitions/ Stable IDs and custom definition resources
|
||||
│ └── state/ Versioned simulation-state records
|
||||
├── tests/
|
||||
│ ├── action_system_boundaries_test.gd
|
||||
│ ├── deterministic_simulation_test.gd
|
||||
│ ├── flat_map_baseline_test.gd
|
||||
│ ├── jajce_world_scaffold_test.gd
|
||||
@@ -487,6 +485,7 @@ NpcVisual navigates through the active world
|
||||
│ │ ├── ResourceNode.gd
|
||||
│ │ ├── ResourceNode.gd.uid
|
||||
│ │ └── ResourceNode.tscn
|
||||
│ ├── active_world_adapter.gd
|
||||
│ ├── world_view_manager.gd
|
||||
│ └── ui/ui.gd
|
||||
├── main.tscn
|
||||
@@ -517,8 +516,9 @@ These are expected prototype constraints, not necessarily isolated bugs:
|
||||
- NPC reasoning is logged but not presented through an in-game inspector.
|
||||
- Active navigation is used as if all agents are local; no simulation LOD exists.
|
||||
- There is no spatial query/index layer for large populations.
|
||||
- Simulation, orchestration, and player-facing mutation APIs are concentrated
|
||||
in `SimulationManager`.
|
||||
- SimulationManager still orchestrates multiple systems and player-facing
|
||||
mutation APIs, but selection, execution, target resolution, and active-world
|
||||
queries now have focused collaborators.
|
||||
- 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,
|
||||
@@ -719,7 +719,7 @@ Food and wood migration and the deliberately minimal `JajceWorld` scaffold,
|
||||
greybox, navigation spike, and stable-ID placement proof are complete. Do not
|
||||
proceed directly from that proof into open-ended beauty production.
|
||||
|
||||
The architecture gate is now the active milestone. Its first four slices are
|
||||
The architecture gate is now the active milestone. Its first five slices are
|
||||
complete:
|
||||
|
||||
- explicit fixed-step simulation clock;
|
||||
@@ -730,11 +730,12 @@ complete:
|
||||
- simulation-owned resource amount/reservation state with ResourceNode
|
||||
presentation binding and unload/rebind coverage;
|
||||
- stable StringName action/profession IDs plus validated custom definition
|
||||
resources used by simulation, targeting, generation, and persistence.
|
||||
resources used by simulation, targeting, generation, and persistence;
|
||||
- separate selection, execution, target resolution, active-world query, and
|
||||
visual travel responsibilities.
|
||||
|
||||
The remaining gate work is:
|
||||
|
||||
- separated action selection, execution, target resolution, and visual travel;
|
||||
- explicit synchronization of active NPC position.
|
||||
|
||||
The coherent visual slice can then aim for:
|
||||
|
||||
+2
-1
@@ -15,7 +15,8 @@ sources of truth.
|
||||
4. [`RESOURCE_NODE_MIGRATION.md`](RESOURCE_NODE_MIGRATION.md) is a focused
|
||||
migration plan. Phases 1–4 are complete; its Phase 5 hands world placement to
|
||||
the visual-slice plan.
|
||||
5. [`SIMULATION_DEFINITIONS.md`](SIMULATION_DEFINITIONS.md) and
|
||||
5. [`ACTION_SYSTEM_ARCHITECTURE.md`](ACTION_SYSTEM_ARCHITECTURE.md),
|
||||
[`SIMULATION_DEFINITIONS.md`](SIMULATION_DEFINITIONS.md), and
|
||||
[`SIMULATION_STATE_SCHEMA.md`](SIMULATION_STATE_SCHEMA.md) document the
|
||||
current data contracts.
|
||||
6. [`decisions/`](decisions/) contains durable architectural decisions,
|
||||
|
||||
@@ -457,7 +457,7 @@ for the initial gather-food scenario.
|
||||
|
||||
**Wood migration** ✅ complete:
|
||||
- `gather_wood` resolves loaded presentation candidates through
|
||||
`SimulationManager.acquire_resource_target()`
|
||||
`ActionTargetResolver` and `ActiveWorldAdapter`
|
||||
- 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
|
||||
|
||||
@@ -65,10 +65,10 @@ the prototype. They do not yet own:
|
||||
- completion effects;
|
||||
- interruption and failure policy;
|
||||
- reservation strategy;
|
||||
- target resolution implementation;
|
||||
- detailed target-selection policy beyond current resource/activity/free
|
||||
metadata;
|
||||
- presentation hints beyond target type.
|
||||
|
||||
Those concerns move during the next architecture phase, which separates action
|
||||
selection, execution, target resolution, and visual travel. Keeping this first
|
||||
definition contract small avoids encoding the existing manager's mixed
|
||||
responsibilities as permanent data architecture.
|
||||
Selection, execution, target resolution, and visual travel are now separate
|
||||
responsibilities. The remaining concerns should move into definitions only
|
||||
when the action-system implementations prove a stable, reusable contract.
|
||||
|
||||
@@ -48,17 +48,21 @@ random streams, and no dependency on a loaded gameplay scene.
|
||||
2. ✅ Introduce serializable village, NPC, and resource-state records.
|
||||
3. ✅ Bind `ResourceNode` presentation to resource records instead of owning
|
||||
authoritative amount and reservation.
|
||||
4. **Next:** Move target choice and reservation coordination out of
|
||||
4. ✅ Move target choice and reservation coordination out of
|
||||
`WorldViewManager` into an action/target system with an active-world query
|
||||
adapter.
|
||||
5. Split action selection, execution, and presentation travel.
|
||||
6. Add versioned save/load before inventories, schedules, or relationships
|
||||
5. ✅ Split action selection, execution, and presentation travel.
|
||||
6. **Next:** Synchronize active position and prove visual unload/reload
|
||||
invariance.
|
||||
7. Add versioned save/load before inventories, schedules, or relationships
|
||||
substantially expand mutable state.
|
||||
|
||||
Schema v1 and its deterministic continuation contract are documented in
|
||||
[the simulation state schema](../SIMULATION_STATE_SCHEMA.md).
|
||||
Stable action/profession identity and immutable metadata are documented in
|
||||
[the simulation definitions](../SIMULATION_DEFINITIONS.md).
|
||||
System responsibilities and event flow are documented in
|
||||
[the action system architecture](../ACTION_SYSTEM_ARCHITECTURE.md).
|
||||
|
||||
## Consequences
|
||||
|
||||
|
||||
Reference in New Issue
Block a user