gamedev-the-steward/docs/ACTION_SYSTEM_ARCHITECTURE.md

The Steward — Action System Architecture

Current flow

SimulationManager tick
    -> ActionExecutionSystem advances needs and working progress
    -> SimulationPopulationView refreshes transient living/starving indexes
    -> VillageOpportunitySystem re-derives the current capable helper
    -> 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;
• queries RelationshipSystem after personal survival/schedule overrides, so a trusted starving acquaintance can redirect ordinary work toward food gathering while the pantry is low;
• consumes the manager's current SimulationPopulationView for that social query instead of rebuilding an all-NPC lookup for each idle decision;
• accepts the current ephemeral OpportunityHelperResult and, only for its matching NPC, selects the reported ordinary gather/deposit action after urgent self-care and sleep/meal schedule branches;
• evaluates current utility scores;
• consumes the NPC's deterministic decision RNG;
• returns an action ID, optional urgent-duration override, branch reason, compared utility scores, and definition-backed rejection reasons;
• 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;
• skips full-capacity activity sites based on authoritative NPC target claims;
• returns typed activity-site, storage, or wander positions without owning presentation.

ActiveWorldAdapter

• exposes loaded resource interaction positions;
• exposes loaded storage and activity-site interaction positions;
• exposes activity-site capacity as an active-world fact;
• 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 owns one disposable SimulationPopulationView, rebuilt at tick start and refreshed after each NPC advances so interleaved decision semantics remain unchanged. The manager publishes the latest ActionSelectionResult for presentation; the UI does not recompute decisions. Each idle selection re-derives the capable helper instead of consulting persisted assignment state. At completion it atomically pays any definition-backed stored-resource cost before applying the action effect. A late shortfall suppresses the effect and records a task_blocked fact. The manager also captures actor/nearby knowledge before forwarding newly recorded events into RelationshipSystem. When an NPC arrives beside a worker at the same non-storage activity site, the manager may transfer one direct known fact and applies its consequence only to that newly informed listener. An open opportunity's exact trigger receives bounded priority in that conversation before normal lasting/recent ranking. It exposes knowledge, provenance, relationship, and cause queries without moving social authority into UI. After consequences are known, it protects current causal facts, enforces the recent-memory cap, and runs age review from authoritative simulation ticks.

VillageEconomy

• owns storage and NPC-inventory transfer operations;
• keeps village.food and village.wood synchronized as aggregate views;
• validates and pays definition-backed completion costs;
• emits completed transaction facts without owning their history.

SimulationEventLog

• owns ordered economic and narrative event identity;
• answers recent-history, actor-history, and consumption-rate queries;
• restores persisted history without performing or replaying transactions.

EventKnowledgeSystem

• stores stable (knower_id, event_id) references separately from objective history;
• initially observes successful food-deposit events for the actor and living NPCs within a fixed proximity radius;
• preserves first acquisition as performed, witnessed, communicated, or legacy, with a stable source NPC ID for direct communication;
• permits one performed/witnessed fact to cross one co-located social hop, but does not relay communicated or ambiguous legacy facts;
• tries the active opportunity trigger first when the speaker directly knows it, then orders remaining communication by lasting relationship relevance and acquisition recency;
• retains current relationship causes and at most three other recent facts per NPC, expiring day-old recent facts at deterministic review boundaries;
• captures evidence only when the event happens, never from current positions during restore;
• answers deterministic known-event and knower queries without formatting prose or choosing actions.

RelationshipSystem

• owns directed familiarity/trust records and stable relationship queries;
• applies a bounded trust gain when a hungry familiar NPC knows about a contributor's successful food-deposit event;
• stores the exact event ID as the trust cause and ignores replayed or older events;
• selects trusted starving subjects deterministically for action selection;
• uses a supplied per-tick population view when available, with a compatibility fallback for isolated callers;
• does not choose actions, perform transactions, or format presentation text.

These collaborators are RefCounted rule services, not additional scene-tree managers. Further decomposition should follow measured pressure and a proven gameplay consumer.

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.