gamedev-the-steward/docs/DEVELOPER_INDEX.md

# 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](ARCHITECTURE_OVERVIEW.md) | `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](FEATURE_CONTENT_AND_AUTHORED_DATA.md) | `simulation/definitions/`, `simulation/animals/definitions/`, `world/presentation/catalogs/` |
| Add or change a player/NPC interaction | [Commands, targets, and economy](FEATURE_COMMANDS_TARGETS_AND_ECONOMY.md) | `simulation/commands/`, `world/targets/`, `ActiveWorldAdapter`, `SimulationManager` |
| Make a world event influence memory, relationships, a situation, or dialogue | [Events through dialogue](FEATURE_EVENTS_KNOWLEDGE_SITUATIONS_DIALOGUE.md) | `simulation/events/`, `simulation/knowledge/`, `simulation/situations/`, `simulation/dialogue/` |
| Add caravans, routes, scheduled work, or regional saves | [Regional simulation and persistence](FEATURE_REGIONAL_SIMULATION_AND_PERSISTENCE.md) | `simulation/regional/`, `simulation/state/*StateRecord.gd` |
| Add an enemy or animal using an existing behavior | [Entity families](FEATURE_ENTITIES_COMBAT_ANIMALS.md) | `CombatantFactory.gd`, `AnimalFactory.gd`, shared visual roots |
| Change rendering or support weaker PCs | [Presentation and performance](FEATURE_PRESENTATION_PERFORMANCE.md) | `world/jajce/jajce_world.gd`, `world/presentation/` |
| Author humanoid animal characters or combine clothing and body shapes | [Modular character kit](../assets/characters/README.md) | `tools/CharacterWorkshop.tscn`, `CharacterAppearanceProfile.gd`, `tools/art/build_character_kit.py` |
| Change a saved field or migration | [Save schema and migrations](FEATURE_SAVE_SCHEMA_AND_MIGRATIONS.md) | `SimulationStateRecord.gd`, nested state records, `SaveSlotStore.gd` |
| Add a regression, benchmark, or run the gate | [Testing and benchmarks](FEATURE_TESTING_AND_BENCHMARKS.md) | `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

```text
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

1. Decide whether the request is a new combination of existing capabilities
   and effects or a genuinely new mechanic.
2. For a data-only combination, create a typed definition resource, add it to a
   pack, validate the catalog, and add a focused headless test.
3. 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.
4. 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.
5. 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.
6. If state changes, update `SimulationStateRecord` and its nested migration,
   checksum, tamper, and continuation tests before wiring presentation.
7. If loaded geometry is involved, prove loaded and abstract execution use the
   same authority and that unload/reload does not alter the checksum.
8. 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](REGIONAL_SIMULATION.md), [the roadmap](LEARNING_ROADMAP.md),
and [the performance guide](FEATURE_PRESENTATION_PERFORMANCE.md) before
starting one of these slices.

## Documentation authority

1. Code and focused tests define current behavior.
2. [ADR 0001](decisions/0001-simulation-authority-boundary.md) and
   [ADR 0002](decisions/0002-emergent-world-content-and-narrative.md) define
   durable architectural decisions.
3. [Architecture overview](ARCHITECTURE_OVERVIEW.md) defines ownership and
   dependency boundaries.
4. The focused contracts define their module: [definitions](SIMULATION_DEFINITIONS.md),
   [state](SIMULATION_STATE_SCHEMA.md), [actions](ACTION_SYSTEM_ARCHITECTURE.md),
   and [regional simulation](REGIONAL_SIMULATION.md).
5. The [learning roadmap](LEARNING_ROADMAP.md) and [build-in-public plan](BUILD_IN_PUBLIC_PLAN.md)
   describe sequencing and presentation goals; they do not override current
   code behavior.

## Verification commands

```bash
./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](FEATURE_TESTING_AND_BENCHMARKS.md).