From 4f9dc842fd5f97ae37d674fdaf4d62b9b5cae375 Mon Sep 17 00:00:00 2001 From: Rijad Zuzo Date: Sun, 5 Jul 2026 14:17:57 +0200 Subject: [PATCH] docs: mark action separation phase complete --- docs/ACTION_SYSTEM_ARCHITECTURE.md | 78 +++++++++++++++++++ docs/BUILD_IN_PUBLIC_PLAN.md | 2 +- docs/LEARNING_ROADMAP.md | 27 ++++--- docs/PROJECT_CONTEXT.md | 35 +++++---- docs/README.md | 3 +- docs/RESOURCE_NODE_MIGRATION.md | 2 +- docs/SIMULATION_DEFINITIONS.md | 10 +-- .../0001-simulation-authority-boundary.md | 10 ++- 8 files changed, 127 insertions(+), 40 deletions(-) create mode 100644 docs/ACTION_SYSTEM_ARCHITECTURE.md diff --git a/docs/ACTION_SYSTEM_ARCHITECTURE.md b/docs/ACTION_SYSTEM_ARCHITECTURE.md new file mode 100644 index 0000000..991454c --- /dev/null +++ b/docs/ACTION_SYSTEM_ARCHITECTURE.md @@ -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. diff --git a/docs/BUILD_IN_PUBLIC_PLAN.md b/docs/BUILD_IN_PUBLIC_PLAN.md index 838802f..5d1938b 100644 --- a/docs/BUILD_IN_PUBLIC_PLAN.md +++ b/docs/BUILD_IN_PUBLIC_PLAN.md @@ -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 diff --git a/docs/LEARNING_ROADMAP.md b/docs/LEARNING_ROADMAP.md index 73236b8..306cb61 100644 --- a/docs/LEARNING_ROADMAP.md +++ b/docs/LEARNING_ROADMAP.md @@ -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 diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md index e1f8def..d2e5eb5 100644 --- a/docs/PROJECT_CONTEXT.md +++ b/docs/PROJECT_CONTEXT.md @@ -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: diff --git a/docs/README.md b/docs/README.md index 8f677c0..e8ccff5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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, diff --git a/docs/RESOURCE_NODE_MIGRATION.md b/docs/RESOURCE_NODE_MIGRATION.md index 3cc03f3..c9fc747 100644 --- a/docs/RESOURCE_NODE_MIGRATION.md +++ b/docs/RESOURCE_NODE_MIGRATION.md @@ -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 diff --git a/docs/SIMULATION_DEFINITIONS.md b/docs/SIMULATION_DEFINITIONS.md index 3a5285e..b752c80 100644 --- a/docs/SIMULATION_DEFINITIONS.md +++ b/docs/SIMULATION_DEFINITIONS.md @@ -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. diff --git a/docs/decisions/0001-simulation-authority-boundary.md b/docs/decisions/0001-simulation-authority-boundary.md index 0dfef9e..28ebe39 100644 --- a/docs/decisions/0001-simulation-authority-boundary.md +++ b/docs/decisions/0001-simulation-authority-boundary.md @@ -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