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, optional urgent-duration override, branch reason, and compared utility scores;
• 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. It also publishes the latest ActionSelectionResult for presentation; the UI does not recompute decisions. 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.