settled-reach/docs/workshops/world-generation/endgame-feature-vision.md

title, author, workshop, date, status, sources

title	author	workshop	date	status	sources
Endgame Feature Vision — World Generation	qatux (compiled from SW1-R3 agent outputs)	world-generation	2026-03-24	complete — pending PO review	gestalt-sw1r3.md nigel-sw1r3.md ozzie-sw1r3.md miri-sw1r3.md tyre-sw1r3.md sw1-interview-answers.md (including R2 follow-up)

Endgame Feature Vision — World Generation

The Settled Reach — Sub-Workshop 1 Synthesis

---

1. Vision Statement

The Settled Reach generates a galaxy of 300 canonical, authored systems and simulates it forward continuously. The world is real before the player arrives. Every room in every district of every settlement is a spatial expression of economic, cultural, and historical forces that the player can read backward from the furniture — from the bar's monthly turnover to the district's faction politics to the system's position in the Reach-wide trade network.

The economic simulation is modeled on X4: Foundations — station-level production chains, bulk commodity trade between systems, supply/demand price discovery, NPC-owned enterprises competing for resources and markets. Adapted to our 300-system scale, running on spare CPU cores as background tokio tasks. The simulation propagates events through the interconnected trade and political network so that when the player arrives anywhere, they find a situation, not a tableau.

Replayability comes from who the player is, where they go, who they know, and what they do — the background simulation amplifies and responds to player action, it doesn't replace it. The world was already there. The player shows up and finds it.

---

2. The Pipeline — 8 Layers

Layer Status Overview

Layer 1: Galaxy (300 systems)        ██████████ BUILT      — systems.db + wiki + star map
Layer 2: Location profiles           ░░░░░░░░░░ AUTHORED   — wiki pipeline, not generated
Layer 3: Planetary topography        ░░░░░░░░░░ AUTHORED   — annotated heightmaps + metadata
Layer 4: Inbound gateways            ████░░░░░░ DESIGNED   — D-093/D-095, template stamped
Layer 5: Content spidering           ████░░░░░░ ARCH BUILT — D-026 tiers + chunk streaming
Layer 6: Settlement generation       ░░░░░░░░░░ NOT BUILT  — placement on authored terrain
Layer 7: District → building         ███░░░░░░░ DATA MODEL — generator.rs, no algorithms
Layer 8: 2D → 3D rendering          ███░░░░░░░ MIGRATING  — D-148/D-149 in progress

---

Layer 1 — Galaxy (systems.db)

300+1 canonical systems. Same wormhole topology every run. Earth is border-locked. The galaxy does not regenerate; it is a place with a permanent geography that players learn over multiple runs and retain as durable knowledge.

Each system carries: economic profile (supply dependencies, distribution_index, faction roles, bulk import/export lists), industrial corridor overlay (MVG / Gate Corp / DSMC / Prometheus / Agricultural Syndic presence), cultural corridor identity (Commonwealth North, Iberian/LatAm South, East Asian East, Germanic/Scandinavian West), and a GTTR narrative entry.

Bulk import/export lists serve double duty: they drive the trade flow simulation (what moves between systems, what creates dependency relationships) and they determine what's on store shelves in every commercial district of that system. Wiki and simulation share a single source of truth. A system that imports pharmaceuticals has pharmacy stock. A system that exports ore has industrial supply shops.

The galaxy map is visible in full from minute one. Every dot is a named, storied system. The player is not discovering an unknown space — they are navigating a place that people have been living in for generations, and the guide entries prove it.

---

Layer 2 — Location Profiles (wiki)

Every planet, moon, and station in all 300 systems has an authored wiki profile. The generator reads this data; it does not generate it. The wiki is the world's canonical record.

Profile fields include: population, economic role, founding age, settlement pattern, cultural corridor, settlement trajectory, and the GTTR narrative entry (authoritative voice + statistics + art). The planetary shader generates visual screenshots (earthlike, jungle, desert, mars-like, ocean, etc.) that appear in both wiki pages and the diegetic GTTR arrival window.

LocationProfile
  ├─ location_type: Planet | Station | Moon | Orbital | AsteroidBase
  ├─ physical: gravity, atmosphere, biome_summary, terrain_reference (→ Layer 3 heightmap)
  ├─ settlement: population, economic_role[], founding_age, founding_culture
  ├─ cultural: cultural_corridor (from systems.db), heritage_persistence, industrial_corridor
  ├─ infrastructure: spaceport_class, transit_connections, district_count
  ├─ economy: industries[], power_players[], trade_imports[], trade_exports[]
  └─ narrative: gttr_entry_path, planetary_screenshot_path, arrival_type_default

This layer is the authored backbone of the cascade. Everything below derives from it.

Engineering cost: 1-2 weeks (wiki markdown → LocationProfile parser + validator). For stations and orbitals: no heightmap — module topology is authored as structured JSON.

---

Layer 3 — Topography (authored heightmaps)

Every planet and moon has an authored world map:

heightmaps/
  GJ-699/
    proxima-b/
      heightmap.png          # Grayscale 16-bit PNG. Elevation data.
      metadata.json          # Scale, origin, resolution, sea_level, units
      rivers.png             # Binary overlay: river channels
      coastlines.png         # Binary overlay: coastline boundaries
      biome_zones.json       # Named polygon regions + biome type per region
      settlements.json       # Settlement center points + approximate radius
      screenshot.png         # Planetary shader screenshot for GTTR/wiki

Topography is a hard constraint on generation. Mountains block corridors. Rivers create district boundaries. Coastlines produce port districts. Geography creates the spatial reasoning the player can exploit — the river that bisects the commercial district always bisects it. Players learn these constraints once and apply them across runs.

The heightmap feeds district placement constraints directly. Cultural geography layers on top: first-wave settlers take their preferred terrain; later settlement waves adapt. The result is a settlement pattern that is spatially and culturally legible from orbital view — a Commonwealth world's settlements cluster around institutional centers; an Iberian/LatAm world's settlements follow water and extended-family sprawl.

Engineering cost: 2-3 weeks (heightmap ingestion + constraint extraction + caching, ~50-200KB per planet in MessagePack).

---

Layer 4 — Arrival / Gateway

Arrival is contextual by transit method and diegetically rich.

Transit method	First impression
Charter flight	Port arrival — infrastructure, scale, the world's public face
Gate transit	Station interior — institutional, Commission inspection, rules before character
Smuggler route	Low orbit in the dark — overview before intimacy, geography as first fact

On every arrival, the player's insert opens an GTTR context window automatically: system stats, a planetary screenshot (from the authored heightmap + shader), and the GTTR narrative entry. The guide entry sets expectations. The world then has to cash the cheque.

Information asymmetry begins at the insert window. The player knows what the guide says. They don't yet know whether the guide's description is still true — the simulation may have moved the world significantly since the entry was written.

---

Layer 5 — Content Spidering / LOD / Simulation Tiers

The world generates on demand, in response to three kinds of triggers: player movement, social depth, and narrative events.

LOD tier	Trigger	What exists
Unvisited	In systems.db or wiki	System-level aggregate data: economic tier, faction, cultural corridor, GTTR entry
Scouted	Player arrives (GTTR insert opens)	Location profile + Phase 1 district skeletons; planetary screenshot in insert
Visited	Player enters a district	Full Phase 2 room fill; all NPCs generated with minimum bundle; simulation primitive baseline from current pressure state
Engaged	Player forms NPC relationship / recurring transaction	Full NPC profile expansion; triangle formation; NPC-driven neighborhood generation if applicable
Invested	Player owns or operates a business	Full business simulation: staff scheduling, supply chain, competitor pressure, regional prosperity coupling

Progressive generation trigger sequence:

Player Action	Generation Triggered	Latency Budget
Starts new game	Load systems.db. LocationProfiles for home system. Phase 1 + Phase 2 for starting district.	2-5 seconds (acceptable)
Enters transit to new system	LocationProfiles for destination. Phase 1 skeletons for destination + neighbors.	Hidden behind 5-30 second transit scene
Arrives at destination	Phase 2 chunk fill for destination district. Activate NPCs.	<500ms total (BSP fills a chunk in <5ms; 8-chunk radius = ~40ms)
Walks toward district boundary	Phase 2 for adjacent chunks, 2 chunks ahead.	Hidden behind walking time
Enters building	LOD 0 → LOD 1: BusinessStats derived. Staff/patron NPCs spawned if first visit.	<50ms

The player never sees a "generating..." screen after new-game startup. All subsequent generation runs during diegetic transitions that are already part of the game's pacing.

NPC-driven generation hook: When the player's relationship with an NPC crosses a depth threshold, that NPC's home neighborhood generates at their stated location. The address becomes a real visitable place. The generation is invisible to the player — the place just exists, with the character that NPC's cultural and economic background would produce.

News-driven generation hook: When the Reach-wide storyteller fires a news event naming a location ("gas main explosion in a Tau Ceti settlement district"), a generation existence claim is registered. When the player travels there, the generator resolves the claim before arrival. The physical consequence (rubble, memorial, burn marks) exists because the simulation produced the event, not because the generator fabricated atmosphere.

Both hooks require a consistency buffer — a data structure recording unresolved existence claims that the generator resolves on the appropriate trigger. The simulation fires the claim; the generator resolves it; the player finds the evidence.

Transitions upward in LOD are permanent. Once a location is Visited, it remains Visited. Chunks, NPC relationship graphs, and business simulation primitives persist and continue advancing at reduced fidelity during player absence.

---

Layer 6 — Settlement Placement

Settlement placement is constraint-solving against authored topography + wiki economics. The district count and type distribution derive from the location's economic role and topographic placement constraints from the heightmap overlay data. Where settlements can plausibly go is determined by geography; what settlements look like is determined by economic profile.

Cultural geography layers the settlement pattern: early settlement waves take preferred terrain. Later waves adapt. The wave history visible in the settlement pattern is readable from above — it is not random.

---

Layer 7 — District Skeleton (Phase 1) and Room Fill (Phase 2)

Phase 1 (skeleton) produces the district's block assignment, zoning types, social sites, era cause distribution, and guarantee audit. The Phase 1 structure is shared across all zone type families (Interior, Urban, Natural) — same 4×4 block grid logic, same guarantee tiers.

Phase 2 (fill) diverges per zone type family. Each block fills its chunks with tile-level content: rooms, corridors, objects. Every room is a full simulation primitive with LOD. A visited commercial bar carries: monthly turnover, cost, employee count, current staff and visitors. These are not static values — they derive from the current pressure state of the settlement.

The cascade rule (Gestalt): Every economic axis in the system profile produces at least one visible attribute at district level, which produces at least one visible attribute at room level. If an axis doesn't cascade visibly, it isn't a generator input — it's database weight.

The canonical Commonwealth bar in a faltering settlement has the same spatial grammar as one in a prosperous settlement (culturally stable sightlines, privacy configuration, gathering orientation) but different economic primitives and NPC behavioral tells. Culture is archaeology; economics are current events.

---

Layer 8 — NPC Population

Every NPC generated at Phase 2 carries a universal minimum data bundle. There is no separate category of "filler" NPC — every NPC is sufficient to become a narrative character if the player chooses to pay attention.

Minimum bundle fields:

Field	Source	Purpose
npc_stable_id	Deterministic hash of (district_id, spawn_index)	Stable cross-session identity
cultural_corridor	Settlement corridor identity	Spatial grammar behavioral tokens
founding_culture	Settlement founding biography	Object palette selection (Layer 3 intra-corridor specificity)
economic_role	Zone function + economic_health	What they do, what pressure they're under
prosperity_tier	Inherited from district pressure state	Wealth signal, stress indicators, behavioral tells
relationship_seeds	Compact graph: workplace, ±2 family, ±3 social affiliations	Expandable into full relationship graph on depth threshold
tell_config	TellCategory + culture_id	Voice re-voicing, animation behavioral tells (D-138 voice pipeline)
biography_stub	Founding corridor + settlement trajectory tag	Coherent history generatable on demand
triangle_capacity	Boolean + prerequisite conditions	Whether and how this NPC can enter a social triangle

The ambient/narrative distinction is a simulation fidelity distinction, not a data distinction. Ambient NPCs run on background tier (game-minute tick). Narrative NPCs run on active tier (10tps). Both carry the same minimum bundle. Expansion is triggered by player attention, not by generator designation.

---

Data Flow

┌─────────────────────────────────────────────────────────────────────┐
│                        AUTHORED CONTENT                             │
│  wiki/star-systems/     ──→  systems.db (300 systems, 7 tables)     │
│  wiki/locations/        ──→  LocationProfile[] (per planet/station) │
│  heightmaps/            ──→  Terrain constraint cache (per planet)  │
│  wiki/gttr/             ──→  GTTR entries (per system)              │
└────────────────┬────────────────────────────────────────────────────┘
                 │ loaded at game start
                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     RUST SERVER (bevy_ecs)                          │
│  ┌──────────────────┐    ┌──────────────────────────────────┐       │
│  │ Galaxy Graph      │    │ Background Pressure Sim (tokio)  │       │
│  │ 300 system nodes  │◄──►│ X4-style: trade flows, industry  │       │
│  │ gate topology     │    │ Social: satisfaction, tension    │       │
│  └────────┬─────────┘    │ Updates every game-minute        │       │
│           │               └──────────────┬───────────────────┘       │
│           ▼                              ▼                           │
│  ┌──────────────────────────────────────────────────────────┐       │
│  │               GENERATOR PIPELINE                          │       │
│  │  LocationProfile + TerrainConstraints + PressureState     │       │
│  │       ├─→ Settlement placement (Layer 6)                  │       │
│  │       ├─→ DistrictSkeleton (Phase 1)                      │       │
│  │       └─→ Chunk tile data (Phase 2)                       │       │
│  └────────────────────┬──────────────────────────────────────┘       │
│  ┌────────────────────┼──────────────────────────────────────┐       │
│  │    ENTITY SIMULATION (D-026 tiers)                         │       │
│  │  Active (80 NPCs) ◄── tile data + NPC spawns               │       │
│  │  Background (2K)   ◄── state machine updates from pressure │       │
│  │  State-saved (10K+)◄── skeleton data only                  │       │
│  └────────────────────┼──────────────────────────────────────┘       │
│                       │ ObserverSnapshot (MessagePack)               │
└─────────────────────────────────────────────────────────────────────┘
                        │ IPC (MessagePack, D-020)
                        ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     GODOT CLIENT                                    │
│  ObserverSnapshot ──→ WorldRenderer ──→ GridMap (3D tiles)          │
│                   ──→ EntityRenderer ──→ CharacterCompositor (3D)   │
│                   ──→ FogRenderer ──→ Fog shader                    │
│                   ──→ UIRenderer ──→ Insert HUD, galaxy map, GTTR   │
└─────────────────────────────────────────────────────────────────────┘

---

3. Cultural Cascade

(From Miri — SW1-R3. Full specification in miri-sw1r3.md.)

The 7 abstract heritage roots (Frost/Stone/Tide/Vine/Dust/Iron/Salt) are superseded — clean break. The real-world cultural corridor system is canonical:

• North Reach: Commonwealth (British/Australian/Canadian/South African/Indian/Nigerian)
• South Reach: Iberian/Latin American + Southern African
• East Reach: East Asian + South/Southeast Asian
• West Reach: Northern/Central European + Central/Eastern European

Cultural data is authored per-system in systems.db (system_culture table: cultural_corridor, founding_culture, heritage_persistence, ambient_anxiety, silence_threshold).

The 7-level cascade

Level	Input	Output
Galaxy	4 cultural corridors + 5 industrial corridors	Corridor probability weights per region
System	cultural_corridor, founding_culture, heritage_persistence, industrial_corridor, exception_archetype	System cultural identity
Settlement	Corridor × preferred terrain bias	Settlement placement pattern readable from orbit
District (Phase 1)	3 numeric targets per corridor: open_space_ratio_target, building_proximity_weight, gathering_infrastructure_weight	District skeleton with cultural spatial character
Room (Phase 2)	Three-layer token system (see below)	Culturally differentiated room fill
Heritage attenuation	Hop distance × heritage_persistence	Living (≤4 hops) / Structural (5-7) / Archaeological (8+)
Exception archetypes	6 types: Early Arrival, Corporate Reset, Refugee Colony, Idealist Exception, Gate Silence Survivor, Perpetual Founder Stamp	Override room grammar with exception-specific character

Room grammar: three token layers

Layer 1 — Spatial grammar tokens (zero asset cost, derived from corridor identity): privacy_default, gathering_orientation, threshold_character, sightline_character

Layer 2 — Social pattern tokens (zero asset cost, drives NPC behavior): stranger_distance, group_size_prior, noise_level_prior, eye_contact_norm × attenuation tier

Layer 3 — Object selection (asset cost, 4 categories):

1. Identity markers (cultural corridor, always present)
2. Social infrastructure (cultural × prosperity)
3. Material vocabulary (cultural × prosperity)
4. Commodity objects (import/export lists × zone type × simulation state — derived from economic data, not heritage)

Industrial corridor overlay (MVG, Gate Corp, DSMC, Prometheus, Agricultural Syndic) modifies all three layers — a west_reach Germanic bar with MVG contract labor dynamics reads differently from one without.

Layers 1+2 together cost nothing and deliver the essential cultural read. A player who walks into a Commonwealth bar should feel the procedural formality before they see a single object. Layer 3 adds richness progressively per corridor as authoring bandwidth allows.

---

4. Replayability Architecture

(From Nigel — SW1-R3)

Replayability operates at three tiers. They are not interchangeable.

Tier 1 — Player Agency (primary)

Two runs diverge primarily because two players made different decisions.

The axes of agency:

• Character creation. Who you are determines starting position, starting knowledge, starting access. A dock logistics worker and a Commission field officer begin in the same canonical galaxy with completely different social maps.
• Where you go. 300+ systems. No optimal route. Exploration sequence is a durable creative choice. Every sequence produces different first impressions, different economic states on arrival, different relationships formed.
• Who you know. Social connections are the content selector. Every meaningful relationship determines what part of the world gets generated in detail. The player's social map writes the world.
• What you do economically. Buying a business, building trade relationships, triggering corporate or political pressure — all tweak core dials that propagate through the network. The player participates in the economy; they don't observe it.

Tier 2 — Simulation Trajectory (secondary)

The background simulation runs independently. Economic pressures build, trade flows shift, political balances tip. The simulation produces a different state at every location every time the player arrives — not because the world was seeded differently, but because time has passed and things have happened.

Equilibrium is signal. Stability tells the player something: nothing significant has happened here, or the pressures have balanced, or this system is controlled tightly enough to absorb shocks. A stable system is information, not dead air.

Events are entropy injection. Corporate disasters. Portal closings. Political shifts. Development successes. Each tweaks core dials on one or more systems and propagates through the trade/political network.

The player as perturbation. Player actions introduce the same perturbations through the same propagation model. The player who builds a successful logistics business changes the system's economic dial. They are an event source among many — with the unique property that they can observe what they caused.

X4 attractor note (Nigel): X4-style production chain economics with stable attractor states will tend to produce similar faction outcomes regardless of player action if left unchecked. The background sim workshop must explicitly address disruption injection mechanisms — the storyteller's event injection is the primary defense against convergence. Invariants (topology, cultural geography) vs variables (economic health, faction control) must be separated in the design spec. Without that separation, the simulation cannot be tuned for meaningful replayability across runs.

Tier 3 — Generation Hooks (tertiary)

NPC-driven generation and news-driven generation create world content unique per run because it is responsive to what the player specifically did. The player's social map, the simulation's event history, and the storyteller's news system together determine which parts of the world exist in detail in any given playthrough.

What stays fixed vs what varies

Fixed (invariants — learnable)	Varies (driven by simulation and player)
Galaxy topology — 300+1 systems, wormhole routes	Economic health per system and settlement
Authored topography — world maps, geographic features	Faction territorial control
Cultural geography — corridor identities per system	NPC relationship states
GTTR entries — authored narrative per system	District condition and era character
Canonical starting state — faction standings and economic structure	Which neighborhoods exist in detail
	Which locations have recent notable history
	State of player-owned assets

The fixed layer is learnable — a feature. A player on their fifth run navigates with earned geographic and cultural competence. Their knowledge doesn't tell them what's happening right now.

---

5. Player Experience Beats

(From Ozzie — SW1-R3)

Beat	What happens	What the player feels
Galaxy map	300 named, storied dots — full info, every dot pre-loaded with heard names, rumors, GTTR data	Anticipation — a universe worth exploring because it's already been told about
GTTR arrival	Warm arrival through scouting window + contextual landing by transit method	Expectation formed, then walked into reality
GTTR-as-contract	Guide was true then; simulation has moved since the entry was written	History — the gap between the guide and the present is legible archaeology
Environmental archaeology	Real simulation traces — event (rubble, memorial, construction) and social (bartender's history with the woman in the corner)	This world is real. Someone was actually here.
NPC-driven generation	Visiting where your person is from; their neighborhood generated from their data	Wonder — the simulation knew them before you did; the place fits them
Return visits	NPC drift + consequence echo; the world ran while you were gone; your actions propagated proportionally	Time passed. The world ran without me. My choices mattered.
Scale drop	Physical (vantage point) + social (someone mentions a week's travel) + navigational (galaxy map zoom out) — all three registers ideally at once	One person. An enormous place. Worth exploring because it extends in every direction, lived-in by people with their own reasons.

The GTTR cashes its check at Stage 3 of the arrival cascade: the first three seconds on the ground. The guide said this place has collective labor culture. You step out and the first thing you notice is either: the lack of branding, workers moving in groups — or: corporate signage, security checkpoints, workers with heads down. Either way, you already have a story.

The test (Ozzie): At a place where simulation has produced significant drift from the guide's description, the player should be able to identify the cause from observation alone — without asking an NPC, without reading a newspaper. The space should tell the story. Spatial legibility is the gold standard.

X4 production chain note (Ozzie): X4-style production chains are natural trace-generators for environmental archaeology. When a supply chain disrupts, physical evidence accumulates automatically: half-empty shelves, mothballed machinery, logistics workers reassigned to different zones. The economic model produces the archaeology without authored events. This is the X4 adaptation earning its keep at room level.

---

6. Background Simulation Design Brief

The background simulation is not a nice-have — it is the mechanism by which every other system in this document works. Without it: replayability collapses to player agency only; environmental archaeology has no events to record; the GTTR has no gap to compare against; NPC-driven generation has no simulation state to paint neighborhoods with.

Economic Model

X4: Foundations, adapted to 300-system scale. Station-level production chains, bulk commodity trade between systems, supply/demand price discovery, NPC-owned enterprises competing for resources and markets. Running on spare CPU cores as background tokio tasks.

The X4 model maps naturally to the architecture decisions already in place: systems.db bulk import/export lists are the commodity flow graph; corporate facility presence drives production chain anchors; faction influence drives market access; the wormhole topology constrains trade routes.

Tyre note: The detailed X4 production chain → Settled Reach data mapping (what maps to what in our systems.db schema, Rust data structures, how the economic tick computes one game-minute of production chain activity) is explicitly deferred to the background sim workshop. The architecture decisions below are confirmed. The production chain implementation spec requires its own design session.

Two-Layer Architecture

The simulation runs on two independent layers:

Layer	Scope	Data Model	Execution	Clock
Entity Simulation	Per-NPC: movement, perception, dialogue, routines	bevy_ecs World (Components on Entities)	Main tick thread, 10 tps	SimulationTime (tick counter)
Pressure Simulation	Per-system, per-settlement: economics, faction balance, social tension, trade flows	Standalone structs (not ECS)	tokio thread pool, capped	Game-minute clock (deterministic)

An ECS is the wrong tool for system-level economic modeling. The two layers share a channel interface: the main sim reads pressure snapshots; the pressure sim applies player-action deltas.

Conceptual Rust Architecture

// Conceptual structure — not final API

struct PressureSimRuntime {
    runtime: tokio::runtime::Runtime,  // Capped: N = available_cores - 2
    state: Arc<RwLock<PressureState>>,
    result_rx: crossbeam::channel::Receiver<PressureDelta>,
    snapshot_tx: crossbeam::channel::Sender<PressureSnapshot>,
}

struct PressureState {
    systems: BTreeMap<SystemId, SystemPressure>,
    trade_flows: BTreeMap<(SystemId, SystemId), TradeFlow>,
    faction_influence: BTreeMap<(FactionId, SystemId), f64>,
    // All collections BTreeMap for D-010 determinism
}

struct SystemPressure {
    economic_health: ProsperityLevel,  // Prosperous/Growing/Stable/Faltering/Declining
    industries: BTreeMap<IndustryId, IndustryHealth>,
    social_satisfaction: f64,
    political_stability: f64,
    trade_imports: Vec<TradeGood>,
    trade_exports: Vec<TradeGood>,
    recent_events: Vec<PressureEvent>,
}

Game-Minute Clock — Determinism Guarantee

Main sim tick (100ms real-time at 10 tps)
  ├─ Every 10 ticks (= 1 game-minute):
  │    ├─ Snapshot PressureState → PressureSnapshot → send to tokio
  │    └─ Collect completed PressureDelta from previous minute
  │         └─ Apply deltas in fixed order (system_id ascending)
  │
  tokio runtime:
  ├─ Trade flow propagation (bulk imports/exports between connected systems)
  ├─ Industry health updates (supply availability, demand, corporate events)
  ├─ Social pressure calculation (from economic health + political stability)
  ├─ Faction influence shifts (leverage, events, player actions)
  └─ Event injection (storyteller: corporate disasters, portal closings, political shifts)

Determinism: Each task is internally deterministic (BTreeMap iteration, seeded where needed). Deltas applied in fixed order at game-minute boundary. Slower machines accrue sim debt but produce identical outcomes. D-010 compliant.

Generation Mandate Queue

Both NPC-driven and news-driven hooks feed into a unified mandate queue:

┌─────────────────────────────────────────────────────────┐
│                   GENERATION MANDATE QUEUE              │
│  Sources:                                               │
│  ├─ Player exploration (progressive generation)         │
│  ├─ NPC-driven hook (deep interaction with distant NPC) │
│  ├─ News-driven hook (simulation event at a location)   │
│  └─ Storyteller (narrative-paced world expansion)       │
│  Consumer: Generator pipeline (background tokio tasks)  │
└─────────────────────────────────────────────────────────┘

NPC-driven: Player forms deep relationship → GenerationMandate created with constraints derived from NPC's cultural/economic presentation → background processing → NPC's home exists when player arrives. Phase 1 + Phase 2 for one district < 1 second even worst-case.

News-driven: Pressure simulation produces event at a specific location → ChunkMutation (damage overlay) applied to Phase 1 skeleton if it exists, or pre-baked into new mandate → news ticker reports event → player travels to find physical evidence.

Architecture Decision

Background simulation runs as tokio async tasks outside the bevy_ecs main loop. It operates on aggregate data — per-system and per-settlement pressure dials. It does not query per-entity ECS state. An ECS is the wrong tool for system-level economic modeling.

Deterministic game-minute clock. Simulation advances in discrete game-minute steps regardless of CPU availability. Variable CPU speed produces simulation debt (slower machines fall behind) not variable world states (slower machines don't produce different outcomes). D-010 compliant.

The pressure state model

For each settlement, the background simulation maintains four core dials:

Dial	Range	Driven by
economic_health	Prosperous / Stable / Faltering / Declining	Trade flow balance, import/export dependencies, corporate facility presence
faction_dominance	Per-faction influence score	Political pressure, economic investment, player actions
social_tension	Low / Elevated / High / Critical	Distribution_index, economic_health trajectory, faction conflict
development_trajectory	Growing / Stable / Stagnating / Declining	Investment flows, population change, infrastructure state

Event propagation cascade

Event fires in System A (corporate disaster, portal closure, political shift, development success)
  → System A's core dials shift
  → Trade network rebalances (adjacent systems: supply/demand shifts, prices adjust)
  → Faction influence adjusts across connected systems
  → Settlement economic health shifts
  → District character updates (condition degrades/improves, faction signage, construction)
  → Room simulation primitives update (turnover, staff count, stock quality)
  → Environmental evidence accumulates (closed shops, repurposed storefronts, memorials)

Propagation strength decays with network distance. The Reach's wormhole topology is not just travel infrastructure — it is the economic and information nervous system of the world. Gate topology shapes what events propagate where.

Mandatory agenda items for the dedicated background sim design workshop

Item	Why mandatory
X4 production chain mapping — how X4 station-level economics adapt to 300-system scale; bulk import/export lists as commodity flow graph; corporate facility presence as production chain anchors; what each X4 concept maps to in systems.db	The economic model is confirmed X4-style. The workshop must produce an implementation spec, not a conceptual outline.
Invariants vs variables — which aspects are designed to be stable reference points and which resist equilibrium; disruption injection mechanisms to prevent X4-style attractor convergence	Without separating these, the simulation cannot be tuned for meaningful replayability. These require different implementation approaches.
Propagation network architecture — how do events that tweak core dials propagate through the trade/political network? Bulk import/export lists per system must feed both simulation (trade flows) and content (store shelves).	"Set up propagation properly and emergence follows naturally." The central engineering challenge.
Consistency buffer for generation hooks — how do existence claims (NPC-driven, news-driven) get registered and resolved before player arrival?	NPC and news hooks are callable from social and narrative layers — not just player movement. The buffer is a new pipeline component.
Pre-play simulation strategy — what state is the world in at the player's first move?	Load-bearing for environmental archaeology. Options: pristine canonical, fast-forward, pre-authored canonical events, or hybrid.
Exception community resilience — refugee colonies, Perpetual Founder Stamp systems, Gate Silence survivors must be resilient against simulated normalization.	These settlement histories are what give room grammar its distinctiveness. Must be a design constraint, not an emergent property.

---

7. Open Questions

Three questions remain unresolved after the R2 follow-up interview:

#	Question	Why load-bearing
Q1	What must be generated at Phase 2 (eager) vs expanded on demand (lazy) in the NPC minimum data bundle? tell_config must be eager (required by D-138 voice pipeline). What else?	Determines Phase 2 generation cost per NPC and save file size per district.
Q2	Does NPC-driven generation produce canonical neighborhoods (same for all players who reach that depth with a contact from that system) or seeded-per-run neighborhoods?	Canonical = consistent with reader-and-filler architecture + shared player reference points. Seeded = unique personal worlds per run but architectural divergence.
Q3	What is the pre-play simulation strategy — how much background sim has run before the player's first move?	Load-bearing for environmental archaeology at game start. Must be answered in background sim workshop brief.
Q4 (D2 — Miri)	Does the industrial corridor overlay modify room physical character AND NPC composition, or NPC composition only?	Changes authoring scope significantly. Miri has asserted "both" (full spec in miri-sw1r3.md). PO confirmation required before room grammar authoring begins.

---

8. Stale D-Records to Supersede

D-record	Status	Action required
D-104	Superseded — heritage root grammar overlays	File supersession D-record. Replace with corridor-to-room-grammar mapping D-record (pending Miri wiki cross-check).
D-105	Superseded — heritage root grammar overlays	File supersession D-record (same new record as D-104 replacement).
D-101	Superseded — ZonePalette modifier axis A = HeritageRoot	File supersession D-record. PaletteModifier axis A remaps to cultural_corridor + founding_culture.
D-107	Superseded — references heritage roots	Audit and file supersession.

All four supersessions confirmed by PO in R1 and R2 follow-up interview answers ("clean break — the 7 abstract roots are retired"). New D-records required from Miri's R3 (to be filed after Miri's wiki cross-check with Paula/Mellanie):

• D-NNN: Four-Corridor Cultural Framework — canonical cultural inputs replacing the 7 abstract roots
• D-NNN: Room Grammar Three-Layer System — spatial tokens (L1), social pattern tokens (L2), object selection tokens (L3), each parameterised per corridor
• D-NNN: Heritage Attenuation Tiers — Living/Structural/Archaeological with hop × persistence thresholds
• D-NNN: Six Exception Archetypes — room grammar consequences per archetype

---

9. Future Workshop Topics

Workshop	Scope	Priority
Background Simulation Design	X4-style pressure model spec: production chain architecture (X4 adapted to 300-system scale), bulk trade flows, corporate facility dependencies, political pressure, disaster injection, propagation network. Must separate invariants from variables. Must address X4 attractor convergence prevention. Design brief on file.	CRITICAL — blocks replayability, archaeology, NPC evolution, and pressure-painted generation
Sub-Workshop 2: Zone Types	Phase 2 fill specification per zone type family (Interior / Urban / Natural). Implementation detail deferred from SW1.	High — gates full generation capability
Sub-Workshop 3: NPC Generation Depth	Full NPC expansion pipeline: relationship graph generation, biographical history, triangle assignment, on-demand expansion protocol.	High — gates NPC-driven generation hook
Cultural Cascade Authoring	Corridor-to-room-grammar mapping document (Miri's R2 draft + wiki cross-check with Paula/Mellanie). Attenuation tier parameterisation. Industrial corridor overlay modifier specification.	Medium — gates culturally differentiated room fill
Authored Content Pipeline	Heightmap authoring tooling, wiki location profile expansion (300+ planets/moons), GTTR enhancement with stats and art, planetary shader for screenshots.	Medium — gates layers 2-3 of the cascade

---

Document status: complete. All 5 R3 outputs incorporated. Full Miri cascade spec (with all corridor parameters, exception archetypes, and attenuation tiers) in miri-sw1r3.md. Full Tyre pipeline spec (with LOD economic primitives, detailed cost estimates, critical path) in tyre-sw1r3.md. Q4 (industrial corridor physical vs NPC-only) pending PO confirmation.

— Qatux, 2026-03-24