gamedev-the-steward/docs/decisions/0002-emergent-world-content-and-narrative.md

# ADR 0002: Content and narrative project authoritative world state

- **Status:** Accepted
- **Date:** 2026-08-12

## Context

The prototype already records stable simulation identities, economy events,
knowledge, relationships, and knowledge-gated opportunities. Those foundations
produce honest cause and effect, but several extension paths still depend on
hard-coded action, item, enemy, animal, storage, interaction, and presentation
branches. The existing opportunity proof also stops before player knowledge,
commitment, generated dialogue, and regional simulation.

If content, dialogue, and quests each gain their own mutable representations of
the world, they will drift from the economy, combat, relationships, and NPC
behavior. If distant settlements depend on loaded scenes, presentation state
will change simulation outcomes. Conversely, an unrestricted reflection DSL or
premature ECS would hide gameplay rules and make validation harder.

## Decision

The Steward will use an emergent-world architecture built from five distinct
layers:

1. Typed immutable definitions grouped in validated `.tres` content packs.
2. Authored instance descriptors with stable contextual identity.
3. Versioned mutable records containing stable IDs and primitive values only.
4. Focused systems that validate commands and mutate records.
5. Replaceable presentation bindings selected by stable cue IDs.

Content packs enumerate definitions explicitly. A deterministic catalog rejects
duplicate IDs, unknown references, invalid categories, and unavailable strategy
handlers. Packs do not silently override each other. Saved worlds retain mutable
instance state and definition IDs; current-build definition values provide the
balance rules after load.

Player and NPC interactions converge on the same `ActionCommand` contract.
Targets advertise typed capabilities through context-scoped registries, while
systems revalidate range, availability, reservation, costs, permissions, and
expected revision before applying typed effects or a bounded custom handler.

Meaningful actions mutate authoritative state first and then append structured
world facts. Knowledge, relationships, situations, commitments, dialogue, and
history reference those facts by stable ID. Every generated result includes a
reason trace suitable for tests and developer inspection.

A world situation is a bounded projection of an unresolved authoritative
condition and its evidence. A quest journal stores only player discovery and
tracking metadata for that situation. Accepting help creates a social
commitment; it does not reserve the world or prevent another actor from solving
the problem. Resolution, supersession, release, and failure refer to ordinary
world events and apply idempotent economy or social consequences.

Dialogue is deterministic and offline. The simulation selects semantic intents,
topics, options, and actions from current knowledge, relationships, roles,
situations, commitments, and history. Rendered prose is derived presentation and
is never authoritative save state. Dialogue Manager v3 is isolated behind a
presenter adapter; its conditions and mutations do not own game rules.

One regional simulation owns settlements, routes, mobile groups, people,
cohorts, polities, scheduled jobs, and objective history. Loaded world scenes
are optional contexts. Distant travel and work resolve from deterministic
scheduled state; nearby visuals only interpolate or report local feasibility.
Frame budgets may defer due work but may not reorder it or alter outcomes.

Simulation relevance has four intended tiers: active detailed presentation,
local abstract individuals, distant named people/mobile groups, and aggregate
settlement cohorts. Named or causally important identities are pinned and may
not be erased by aggregation.

## Data-only extension boundary

No-code authoring is guaranteed for new combinations of registered typed
predicates, capabilities, effects, behavior profiles, dialogue intents,
situation objectives, and presentation cues. A fundamentally new mechanic adds
one explicit reusable strategy handler with focused tests. It does not add a
private script to every content instance, nor does it expand a universal
reflection-based language.

## Consequences

- Existing stable IDs remain append-only. Renames require aliases and explicit
  save migration.
- Definition, state, system, and presentation changes are reviewed separately
  even when delivered in one vertical slice.
- Headless simulation cannot load presentation catalogs or assets.
- Quest and dialogue tests assert exact causal facts and semantic options rather
  than prose alone.
- World registries become context-scoped before more locations are loaded.
- Visual travel must be replaced by simulation-time route authority before
  regional scale is considered correct.
- Global scans, unbounded history, and monolithic saves must be measured and
  replaced by indexes, scheduled work, retention/rollups, and chunking as the
  regional workload grows.
- The first proof is one complete Jajce shortage conversation and commitment;
  the first regional proof is one exact caravan transfer between Jajce and an
  abstract settlement.

## Rejected alternatives

- **Scripted quest and dialogue graphs as authority:** fast for isolated content,
  but duplicates world state and cannot guarantee systemic resolution.
- **One simulation manager and scene per settlement or caravan:** creates
  identity collisions, freezes unloaded work, and multiplies global registries.
- **Runtime free-form language generation:** non-deterministic and outside the
  offline, inspectable simulation contract.
- **Universal ECS or reflection DSL now:** too broad for the proven consumers
  and obscures validation and save compatibility.

## Staged migration

1. Add content catalogs, indexed world facts, scoped target capabilities, and
   shared action-command value contracts.
2. Complete the Jajce knowledge, situation, commitment, and generated-dialogue
   slice using ordinary economy actions.
3. Migrate enemies, animals, resources, items, storage, and presentation cues
   one record family at a time.
4. Introduce regional identity, deterministic scheduled jobs, authoritative
   routes, and one exact caravan transfer.
5. Add relevance tiers, history rollups/chunked persistence, settlement growth,
   and polity systems only behind deterministic conservation and performance
   gates.

## Revisit when

Revisit this decision only if measured vertical slices show that typed
definitions and bounded handlers cannot express recurring content safely, or if
another authority model demonstrably improves deterministic unloaded simulation,
save migration, and explainability together.