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.