From fa04137a04d1f465369a856ce0ee8dac3815a78c Mon Sep 17 00:00:00 2001 From: Rijad Zuzo Date: Wed, 12 Aug 2026 19:57:02 +0200 Subject: [PATCH] docs: define emergent world architecture --- AGENTS.md | 41 ++++++ docs/ARCHITECTURE_OVERVIEW.md | 24 ++++ ...02-emergent-world-content-and-narrative.md | 130 ++++++++++++++++++ 3 files changed, 195 insertions(+) create mode 100644 docs/decisions/0002-emergent-world-content-and-narrative.md diff --git a/AGENTS.md b/AGENTS.md index 1fad24a..3aee22c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/docs/ARCHITECTURE_OVERVIEW.md b/docs/ARCHITECTURE_OVERVIEW.md index d3ac55c..9eb71b6 100644 --- a/docs/ARCHITECTURE_OVERVIEW.md +++ b/docs/ARCHITECTURE_OVERVIEW.md @@ -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 diff --git a/docs/decisions/0002-emergent-world-content-and-narrative.md b/docs/decisions/0002-emergent-world-content-and-narrative.md new file mode 100644 index 0000000..85c5526 --- /dev/null +++ b/docs/decisions/0002-emergent-world-content-and-narrative.md @@ -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.