docs: define emergent world architecture

2026-08-12 19:57:02 +02:00
parent 34428d836a
commit fa04137a04
3 changed files with 195 additions and 0 deletions
@@ -77,6 +77,47 @@ Preserve the simulation/presentation boundary.
 When adding a system, first prove the contract with one real gameplay use case.
 Do not extract generic frameworks before multiple real consumers justify them.
 ## Emergent-world doctrine
 The game world is the source of narrative truth. Dialogue, tasks, quests, and
 visible happenings must arise from ordinary simulation state and events rather
 than maintaining parallel scripted copies.
 - Keep immutable definitions, authored instance placement, mutable state,
  systems, and presentation as separate layers.
 - Persist stable IDs and primitive data only. Saved state must never contain
  scripts, nodes, `NodePath`s, callables, or resource paths.
 - Mutate authoritative state before recording the fact that describes the
  mutation. Facts may reference exact causes; they may not stand in for a
  missing world change.
 - Treat dialogue prose as presentation. Semantic intents, selected response
  IDs, action commands, commitments, and their causal world events are the
  authoritative contract.
 - Treat quests as player-facing projections of real unresolved situations.
  Never create quest-only enemies, items, damage, relationships, resources, or
  completion facts.
 - Route player and NPC interactions through the same authoritative action and
  capability contracts. Presentation can suggest or submit a command, but the
  simulation must revalidate it.
 - Loaded visuals must not decide whether travel, work, growth, or distant
  conflict completes. Presentation interpolates authoritative state and may
  report local feasibility or obstruction.
 - Every generated action, situation, helper, dialogue intent, or consequence
  must expose a concise reason trace with the definition and causal fact IDs
  that justified it.
 - “Data-only content” means new combinations of existing typed predicates,
  capabilities, effects, behavior profiles, and presentation cues. A genuinely
  new mechanic adds one bounded reusable handler and tests; it does not add one
  script per item, creature, quest, or conversation.
 - Prefer typed Godot resources, composition, deterministic registries, and
  explicit strategy handlers. Do not introduce a universal reflection DSL or
  rewrite the project as a full ECS.
 The intended extension path is therefore definition plus content pack, optional
 presentation cue, and authored placement or simulation spawn. A berry, bear,
 caravan, shortage, or conversation topic should reuse the same state, action,
 event, and presentation contracts that existing content uses.
 ## Resource and target rules
 Do not reintroduce abstract food/wood task-zone fallbacks.
@@ -5,6 +5,30 @@ Serializable simulation records are authoritative; loaded Godot nodes present
 that state and contribute active-world facts such as positions and navigation
 results.
 ## Emergent content and narrative boundary
 Definitions, authored placements, mutable records, systems, and presentation
 are separate layers. New content is registered through deterministic typed
 content packs and stable definition IDs. World targets expose capabilities in an
 active-context registry; player and NPC actors submit the same authoritative
 action commands. Presentation catalogs resolve stable cue IDs without entering
 headless simulation or saved state.
 World events describe completed authoritative mutations. Knowledge,
 relationships, unresolved situations, commitments, dialogue topics, and quest
 journal entries reference those exact facts instead of creating parallel quest
 state. Dialogue planning owns semantic intents and options; rendered prose and
 the Dialogue Manager balloon are replaceable presentation. Every generator
 returns its definition, causal references, and rejection/selection reason so a
 developer can trace why the world produced an outcome.
 Regional expansion uses one simulation authority. Locations, settlements,
 routes, mobile groups, people, cohorts, and polities are data records; loaded
 scenes are optional presentation contexts. Scheduled simulation-time work owns
 distant travel and completion, while visuals interpolate nearby state. This
 direction is governed by
 [ADR 0002](decisions/0002-emergent-world-content-and-narrative.md).
 ## Runtime flow
 ```text
@@ -0,0 +1,130 @@
 # 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.