Rijad Zuzo
92 lines
4.4 KiB
Markdown
92 lines
4.4 KiB
Markdown
# The Steward — Architecture Overview
|
|
|
|
This project is organized around gameplay ownership, not scene-tree location.
|
|
Serializable simulation records are authoritative; loaded Godot nodes present
|
|
that state and contribute active-world facts such as positions and navigation
|
|
results.
|
|
|
|
## Runtime flow
|
|
|
|
```text
|
|
SimulationClock
|
|
-> SimulationManager orchestrates one deterministic tick
|
|
-> ActionExecutionSystem advances needs and work
|
|
-> ActionSelectionSystem chooses an action
|
|
-> ActionTargetResolver resolves a stable target ID
|
|
-> VillageEconomy performs inventory/storage transactions
|
|
-> SimulationEventLog records completed facts
|
|
-> WorldViewManager presents travel and NPC state
|
|
-> ActiveWorldAdapter supplies loaded-world positions/capacity
|
|
-> NpcVisual performs local navigation and animation
|
|
```
|
|
|
|
`SimulationManager` is the scene-tree façade for the simulation. It owns the
|
|
tick lifecycle, authoritative NPC/village/resource records, reservations, and
|
|
the signals consumed by presentation. Focused collaborators own rules that
|
|
would otherwise obscure that lifecycle:
|
|
|
|
- `simulation/actions/` owns selection, progress, and target resolution;
|
|
- `simulation/economy/VillageEconomy.gd` owns storage/inventory transactions
|
|
and keeps village resource summaries synchronized;
|
|
- `simulation/events/SimulationEventLog.gd` owns ordered event identity,
|
|
history queries, and rate calculations;
|
|
- `simulation/persistence/` owns save-slot file safety;
|
|
- `simulation/state/` owns versioned serialized record contracts;
|
|
- `simulation/definitions/` owns stable IDs and immutable action/profession
|
|
definitions.
|
|
|
|
The manager deliberately remains a façade instead of being split into a
|
|
collection of scene-tree manager nodes. A new collaborator is justified when
|
|
one cohesive rule set has several real consumers or makes the tick lifecycle
|
|
hard to read.
|
|
|
|
## Folder ownership
|
|
|
|
| Path | Responsibility |
|
|
| --- | --- |
|
|
| `simulation/` | Headless-capable orchestration and core models |
|
|
| `simulation/actions/` | Action decisions, execution, and target queries |
|
|
| `simulation/economy/` | Authoritative inventory and storage transactions |
|
|
| `simulation/events/` | Immutable event history and derived event queries |
|
|
| `simulation/state/` | Versioned, serializable mutable records |
|
|
| `simulation/definitions/` | Stable IDs and immutable gameplay definitions |
|
|
| `simulation/persistence/` | Validated local save-file storage |
|
|
| `world/` | Loaded-world interaction geometry and presentation adapters |
|
|
| `world/resource_nodes/` | Finite resource presentation bound by stable ID |
|
|
| `world/storage/` | Storage interaction geometry, never stored quantities |
|
|
| `world/activity/` | Rest/study/patrol interaction sites and capacity facts |
|
|
| `player/` | Player input, camera, and active NPC presentation |
|
|
| `tests/` | Deterministic headless gameplay scenarios |
|
|
|
|
Top-level core model scripts keep their stable paths because Godot's global
|
|
class cache records `class_name` locations. Moving them solely for cosmetic
|
|
nesting can break editor and headless startup for existing workspaces without
|
|
improving ownership.
|
|
|
|
## Dependency rules
|
|
|
|
- Simulation code must run without `main.tscn` or loaded world nodes.
|
|
- Persistent references are stable IDs, never `Node`, `NodePath`, or scene
|
|
ownership.
|
|
- Presentation may report facts and submit commands; it does not choose NPC
|
|
actions or own resource, storage, inventory, event, or reservation state.
|
|
- Resource changes go through `ResourceStateRecord`, NPC inventory, and
|
|
`VillageEconomy`; `village.food` and `village.wood` are synchronized views.
|
|
- New mutable features define serialization and deterministic continuation at
|
|
the same time as their first gameplay use.
|
|
- Prefer one tested vertical behavior over a generic framework with no proven
|
|
consumers.
|
|
|
|
## Where new code goes
|
|
|
|
Put a rule beside the state it governs. A relationship consequence belongs in
|
|
a focused simulation system plus serialized relationship records; its icon or
|
|
animation belongs in presentation. Add a world node only when the behavior
|
|
needs loaded-world geometry. Add a stable ID or definition when content must be
|
|
referenced across saves, scenes, or unloaded simulation.
|
|
|
|
The architectural decision and detailed contracts live in
|
|
[ADR 0001](decisions/0001-simulation-authority-boundary.md),
|
|
[the action system architecture](ACTION_SYSTEM_ARCHITECTURE.md), and
|
|
[the simulation state schema](SIMULATION_STATE_SCHEMA.md).
|