admin
3ea8f02d55
- Update ACTION_SYSTEM_ARCHITECTURE.md to describe the active-position contract and visual lifecycle proof - Mark BUILD_IN_PUBLIC_PLAN.md systems-gate section complete - Mark LEARNING_ROADMAP.md architecture-gate section complete and renumber post-gate implementation sequence - Update PROJECT_CONTEXT.md immediate-milestone section to reflect completed gate and next food-loop milestone - Update SIMULATION_STATE_SCHEMA.md with NPCStateRecord v2 details - Update ADR 0001 checklist to mark active-position sync done
85 lines
3.2 KiB
Markdown
85 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
## Active-position contract
|
|
|
|
NpcVisual emits active position changes after successful movement.
|
|
WorldViewManager forwards those facts through
|
|
`SimulationManager.synchronize_npc_position()`. Arrival, navigation failure,
|
|
and visual unload also perform a final synchronization.
|
|
|
|
SimNPC stores both authoritative position and the resolved travel destination.
|
|
The destination is versioned simulation state, so reloading a visual resumes
|
|
the same route request without rerolling wander, resolving another resource, or
|
|
changing a reservation.
|
|
|
|
`tests/npc_visual_lifecycle_test.gd` proves that visual unload/reload preserves
|
|
action, target ID, travel destination, resource reservation, position, and
|
|
state checksum.
|
|
|
|
Unloaded NPCs do not yet resolve abstract travel time; they remain in their
|
|
current task state until an active visual or a future simulation-LOD travel
|
|
system advances them.
|