gamedev-the-steward/docs/ACTION_SYSTEM_ARCHITECTURE.md

The Steward — Action System Architecture

Current flow

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.