The Steward developer index

This is the shortest reliable route into the current codebase. It describes what is implemented today, where the implementation lives, which document owns each contract, and what remains intentionally incomplete. It is written from the Godot 4.7 source and the current headless test/benchmark suite, not from the original prototype plan.

If a statement here disagrees with code or a focused test, update this index after fixing the code. Do not make this document a second implementation.

What the project is

The Steward is a deterministic, embodied village-simulation prototype set in a Jajce-inspired valley. The player, NPCs, animals, enemies, resources, storage, events, memories, relationships, situations, and commitments use the same authoritative world state. Godot scenes are optional loaded-world adapters: they provide geometry, navigation, visual feedback, and input, but they do not own persistent quantities, travel completion, or quest progress.

The long-term direction is one regional simulation containing settlements, routes, caravans, named people, aggregate cohorts, and polities. The current repository has the regional records, deterministic scheduler, one exact caravan transfer service, a production facade for one inbound Jajce route, a combined local/regional save manifest, chunked persistence, and a 20-caravan structural benchmark. It does not yet provide a complete market, settlement-growth, or kingdom gameplay loop. That distinction is important when extending the game.

Start here

Goal	Read first	Then inspect
Understand authority and module ownership	Architecture overview	`simulation/SimulationManager.gd`, `world/active_world_adapter.gd`
Add a new item, animal, enemy, resource, storage, action, situation, or dialogue intent	Authored content and definitions	`simulation/definitions/`, `simulation/animals/definitions/`, `world/presentation/catalogs/`
Add or change a player/NPC interaction	Commands, targets, and economy	`simulation/commands/`, `world/targets/`, `ActiveWorldAdapter`, `SimulationManager`
Make a world event influence memory, relationships, a situation, or dialogue	Events through dialogue	`simulation/events/`, `simulation/knowledge/`, `simulation/situations/`, `simulation/dialogue/`
Add caravans, routes, scheduled work, or regional saves	Regional simulation and persistence	`simulation/regional/`, `simulation/state/*StateRecord.gd`
Add an enemy or animal using an existing behavior	Entity families	`CombatantFactory.gd`, `AnimalFactory.gd`, shared visual roots
Change rendering or support weaker PCs	Presentation and performance	`world/jajce/jajce_world.gd`, `world/presentation/`
Author humanoid animal characters or combine clothing and body shapes	Modular character kit	`tools/CharacterWorkshop.tscn`, `CharacterAppearanceProfile.gd`, `tools/art/build_character_kit.py`
Change a saved field or migration	Save schema and migrations	`SimulationStateRecord.gd`, nested state records, `SaveSlotStore.gd`
Add a regression, benchmark, or run the gate	Testing and benchmarks	`tests/`, `tools/`, `docs/benchmarks/`

Current implementation at a glance

Area	Current implementation	Boundary to keep visible
Definitions	Transactionally validated `.tres` packs and a sorted `ContentCatalog`	New mechanics still require one explicit reusable handler; data-only combinations are the supported extension surface
Actions	Definition-backed actions, typed effects, copy-only commands/offers/results, shared activity command service	Do not let UI or a scene mutate authority directly
Targets	Context-scoped `WorldTargetRegistry` with stable IDs, capabilities, generation handles, and provider lookup	Registry handles are transient; target identity in saves remains primitive and contextual
Economy	Exact resource, inventory, storage, player-citizen, and animal-care transactions	Village pantry/woodpile are still the production economy; regional markets are not wired
World facts	`WorldEventRecord`/`WorldEventStore` plus compatibility `EconomicEventRecord`/`SimulationEventLog`	Facts are appended after successful mutation and are never quest-only substitutes
Memory/social	Bounded knowledge with provenance, one-hop communication, seven relationship dimensions, causal event IDs	Objective history and broader rumours still need retention/rollup policy at regional scale
Situations/quests	Definition-driven bounded situations, derived progress, journal metadata, commitments and idempotent outcomes	The initial Jajce slice is bounded; it is not a universal objective scripting language
Dialogue	Deterministic semantic `ConversationService`, authored intent/template resources, Dialogue Manager v3 presenter	Dialogue Manager renders planned turns; it is not an authority or save format
Entities	Shared definition → instance/state → presentation contracts for resources, animals, enemies, items, storage	New behavior profiles and genuinely new mechanics still need typed code and tests
Regional kernel	Primitive records, due-job heap, keyed random, analytical updates, caravan service, production facade, chunk/file store	One authored inbound route is live; the 20-caravan economy remains a structural fixture, not the Jajce market
Presentation	Active-world adapters, context registries, relevance cap of 40, navigation budget of 2/frame, High/Balanced/Low profiles	Hardware frame-time/VRAM evidence is still pending; structural benchmarks are not rendered claims
Persistence	Combined manifest v1 containing unchanged local schema v16 plus the canonical regional facade; regional chunk generations with recovery	No save menu/profile system; regional chunk/history generations are not yet the `SaveSlotStore` backend

The authority pipeline

player input or NPC decision
        |
        v
ActionCommand / domain service
        |
        v
validate actor, target, capability, range, revision, cost, permission
        |
        v
mutate authoritative records atomically
        |
        +--> append WorldEventRecord / EconomicEventRecord
        |         |
        |         +--> knowledge and relationship consequences
        |         +--> SituationSystem and derived journal progress
        |         +--> SocialCommitmentSystem outcomes
        |         +--> semantic ConversationService context
        |
        v
signals and copied results to presentation

The important ordering rule is mutation first, fact second, projection last. A situation, journal entry, conversation line, HUD card, or visual cue may explain an event, but it may not manufacture the inventory, damage, enemy, relationship, or reward that the event claims happened.

Repository map

Authoritative simulation

simulation/SimulationManager.gd — scene-tree facade and tick boundary; coordinates the current Jajce simulation and exposes player/NPC-facing APIs.
simulation/SimNPC.gd, simulation/SimVillage.gd — local person and settlement state used by the playable slice.
simulation/SimulationClock.gd — fixed-step simulation time, speed, and capped catch-up.
simulation/actions/ — utility selection, progress, and target resolution.
simulation/commands/ — command values, typed effects, activity handler, catalog interaction offers, and transactional effect planning.
simulation/economy/ — exact inventory/storage transfers and routing.
simulation/animals/ and simulation/conflict/ — reusable animal and enemy domain systems.
simulation/events/, knowledge/, relationships/, situations/, and dialogue/ — causal history and emergent narrative layers.
simulation/state/ — versioned primitive records and validation.
simulation/persistence/ — combined quicksave manifest and atomic slot replacement, plus regional chunk codecs and generations.
simulation/regional/ — production facade, regional records, scheduler, caravan transaction, retention planning, and scale contracts.

Loaded world and presentation

world/active_world_adapter.gd — context identity, target registry, loaded geometry, and spatial query boundary.
world/targets/ — stable target descriptors, capabilities, and transient generation-checked handles.
world/resource_nodes/, world/storage/, world/activity/, and world/animals/ — reusable interaction providers bound to simulation state.
world/creatures/creature_visual.gd — shared navigation/death visual root; world/combat/HostileCombatant.gd specializes it for enemies.
world/dialogue/ — player dialogue mode and the Dialogue Manager adapter.
world/presentation/ — cue catalog, relevance selection, and path-request budget.
world/jajce/ — authored Terrain3D valley, environment, grass, clusters, day/night, and quality profiles.
world/ui/, world/world_view_manager.gd, and player/ — presentation and input only; they query copied results/signals from authority.

Definitions and authored resources

simulation/definitions/ contains action, item, resource, storage, profession, enemy, event, social-consequence, situation, dialogue, and pack resources. world/presentation/catalogs/ contains visual cue mappings. A .tres file must never be treated as a mutable save record; current-build definition values are used when an existing save is loaded.

Extension workflow

Decide whether the request is a new combination of existing capabilities and effects or a genuinely new mechanic.
For a data-only combination, create a typed definition resource, add it to a pack, validate the catalog, and add a focused headless test.
Give placed instances contextual stable IDs and register them with the active adapter. Do not add a process-global registry or a scene-path lookup.
For a new mechanic, add one bounded typed handler/strategy, its validation, reason trace, save semantics, and a real consumer test. Do not add a script per item, quest, animal, or enemy.
If the action changes meaningful state, append an exact world fact after the mutation and connect any knowledge, relationship, situation, or commitment projection to that fact.
If state changes, update SimulationStateRecord and its nested migration, checksum, tamper, and continuation tests before wiring presentation.
If loaded geometry is involved, prove loaded and abstract execution use the same authority and that unload/reload does not alter the checksum.
Update the narrow feature guide and this index, then run the changed gate and full gate before committing.

Current next work

The following are deliberately not claimed as complete:

integrate event retention/rollups/chunked history into one atomic, lazily loaded long-horizon save;
run 20 real caravan trades across five settlement economies with atomic cargo/stock ledgers;
replace local unloaded travel freezes with authoritative route-time work;
add settlement projects, cohort promotion/demotion, offices, diplomacy, armies, campaigns, and aggregate conflict;
add visual relevance streaming to the live world view rather than only the pure policy/benchmark contract;
record weak-PC High/Low gameplay-camera CPU/GPU frame-time, draw-call, memory, and VRAM captures.

See the regional contract, the roadmap, and the performance guide before starting one of these slices.

Documentation authority

Code and focused tests define current behavior.
ADR 0001 and ADR 0002 define durable architectural decisions.
Architecture overview defines ownership and dependency boundaries.
The focused contracts define their module: definitions, state, actions, and regional simulation.
The learning roadmap and build-in-public plan describe sequencing and presentation goals; they do not override current code behavior.

Verification commands

./tools/quality.sh --changed
./tools/quality.sh
git diff --check

For a focused test, use the Godot binary configured by the local quality scripts and pass the test script through the repository's isolated profile. The complete test and benchmark map is in Testing and benchmarks.

13 KiB Raw Blame History