jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(decisions): split DECISIONS.md into domain-scoped files

Browse Source 
Replace monolithic 474-line DECISIONS.md with 7 domain files under
decisions/: architecture, perception, content, scope, process,
questions, rejected. Each file owns its decisions with cross-reference
hyperlinks. Root DECISIONS.md becomes a redirect with domain index.

Reduces per-agent context load by ~70-80% (80-150 lines vs 474).
Taxonomy: architecture (D-008..D-031), perception (D-011..D-019),
content (D-023..D-029), scope (D-001..D-027), process (D-004..D-022),
questions (Q-001..Q-011), rejected (R-001..R-010).

Restores D-002 original text (was a tombstone referencing D-005).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-11 09:28:57 +01:00
co-authored by Claude Opus 4.6
parent ab5f84ab15
commit 4f5ee0274b
9 changed files with 574 additions and 474 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DECISIONS.md
+17 -474
View File
@@ -1,474 +1,17 @@
# The Settled Reach - Decisions Log
This document tracks confirmed decisions, open questions, and rejected alternatives for **The Settled Reach** project (formerly "Commonwealth Game").
---
## CONFIRMED DECISIONS
### D-001: Build a custom game, not a mod
- **Date:** 2026-02-08
- **Decision:** We are building a standalone game, not a Stellaris mod.
- **Rationale:** No existing game provides the right combination of character-driven dynasty play, wormhole-centric space map, and deep internal politics that the Commonwealth universe demands. Stellaris gets the map right but characters wrong. CK3 gets characters right but the map wrong. Neither supports wormhole-as-infrastructure as a core mechanic.
- **Raised by:** Team Leader (Jeroen), after team debate across Rounds 1-3.
- **Dissent:** None. Team unanimously supports after discussion.
### D-002: SUPERSEDED by D-005
### D-003: Commonwealth is the first campaign, not the only possible one
- **Date:** 2026-02-08
- **Decision:** Build a character-driven space grand strategy *framework/engine*, with the Commonwealth universe as the first campaign/scenario.
- **Rationale:** Avoids locking into one IP. The framework has broader value. The Commonwealth provides a rich, opinionated first use case that forces good design decisions.
- **Raised by:** Gore (Transhumanist Fan), endorsed by team.
### D-005: Core concept - single character, first-person, story-generator
- **Date:** 2026-02-08
- **Decision:** The game is a first-person, single-character experience. You select a character at game start and play from their perspective. The world is a rich simulation experienced through one person's keyhole view.
- **Supersedes:** D-002 (dynasty grand strategy concept)
- **Elevator pitch:** "Pick a character. Step into the Commonwealth. Figure it out."
- **Key pillars:**
- **Single character selection** - who you pick determines where you start, what you know, what you can do, and what you care about
- **Asymmetric information as core mechanic** - you only know what your character knows. Others lie, withhold, reveal. The same world-state looks completely different from different characters
- **Rimworld-style story generator** - an AI storyteller paces events for dramatic tension. Structural randomness (who's compromised, where evidence is) set at game start. Dramatic randomness (when things happen) driven by pacing
- **Wormhole network** as traversable infrastructure - you physically move through wormholes between locations
- **Crisis events emerge from simulation** - not timers, not scripted, but consequences
- **Replayability through perspective** - same conspiracy, different character, completely different game
- **Design references:** Rimworld (storyteller/systems), Disco Elysium (character-driven investigation), Sunless Skies (atmosphere/travel), King of Dragon Pass (event-driven decisions)
- **Raised by:** Team Leader (Jeroen), evolved through Rounds 4-6 with full team input.
- **Dissent:** None. Team unanimously energized by the pivot.
### D-006: SUPERSEDED by D-027
- **Date:** 2026-02-08
- **Decision:** The first playable prototype focuses on the Starflyer conspiracy arc, scoped to the investigative/political hub: the Institute, Armstrong City, and the Guardians of Selfhood. This tests the core mechanic (asymmetric information in a conspiracy) with controllable scope.
- **Rationale:** The conspiracy arc IS asymmetric information. If it's not compelling at this scale, a galaxy won't fix it. If it works, everything else is expansion.
- **Raised by:** Team Leader (Jeroen).
- **Superseded by:** D-027 (smuggler + detective vertical slice, 2026-02-10)
### D-007: Five pillars of game design
- **Date:** 2026-02-08
- **Decision:** The game rests on five core design pillars. All systems must serve at least one.
- **Pillars:**
1. **Characters & Information** - who you are, what you know, who you know. Asymmetric information is the master mechanic.
2. **The Wormhole Network** - where you go, how you move through the world. Physical traversal of infrastructure.
3. **Society & Factions** - the political landscape you navigate from inside, not above.
4. **Crisis & Storyteller** - what the world throws at you and when. Rimworld-style AI pacing with structural + dramatic randomness.
5. **Action & Spectacle** - what happens when it all goes loud. The punctuation, not the sentence.
- **Raised by:** Gestalt (pillars 1-4), Team Leader (pillar 5, citing Rimworld's shooter pedigree).
### D-008: Action pillar design principles
- **Date:** 2026-02-08
- **Decision:** The action/combat system follows these principles:
- **Rimworld/XCOM hybrid** - simple mechanics, stats-driven. Simple gets complicated fast on its own.
- **Z-levels** - floors, verticality. Not 3D rendering, but 3D space. Fights across floors of a building.
- **Perception-bounded** - you see/hear what your character can. Rest is abstracted/occluded. Same principle as information asymmetry applied to physical space.
- **LOD/occlusion** - simulation reduces outside player view. Both a design principle and performance optimization.
- **Large, varied maps** - locations should feel big. Achieved through procedural generation (templates + procedural flesh), trickery, or both. Procedural layouts also feed replayability.
- **Multiple maps** - different locations are separate maps. Step through a wormhole, load a new place.
- **Wildly asymmetric encounters** - balanced fights are the exception. Power mismatches in both directions are the norm and the source of tension.
- **Hubris wall as design principle** - let the player feel powerful, then recontextualize their power level. Not cheap difficulty spikes - genuine "you were playing a smaller game than you thought" moments. The books are not always balanced; the fun comes when a character hits their hubris wall.
- **Death = information loss, not game over** - memory cell backup system means death costs you everything since your last backup. Lost knowledge, lost relationships, lost deals. The storyteller knows what you've lost and can exploit it.
- **Scales with ascension** - baseline human fights with weapons, Higher fights with biononics, ANA-connected fights with something else entirely. The pillar transforms as the character evolves.
- **Design references:** Rimworld (real-time, simple systems, personal stakes), XCOM (tactical asymmetry, pod activation moments), Dwarf Fortress (z-levels, simulation depth)
- **Raised by:** Team Leader (Jeroen), with input from full team.
### D-009: Multiplayer - design for it, build single-player first
- **Date:** 2026-02-08
- **Decision:** Single-player is the build target. Multiplayer is designed into the architecture from day one so it can be added without rewriting the game.
- **Rationale:** Two players experiencing the same conspiracy from different keyholes (Senate insider + Guardian operative) is a killer feature. But building multiplayer too early kills projects. The compromise: architectural decisions now that make multiplayer a "add networking" problem later, not a "rewrite everything" problem. Team Leader flagged that bolting multiplayer on after the fact is one of the hardest things to do - so the architecture must be honest about this from the start.
- **Cost:** ~15-20% slower single-player development due to required abstractions. Accepted as cheap insurance.
- **Raised by:** Full team discussion. Tyre led technical framing, Team Leader insisted on architectural honesty.
### D-010: Multiplayer-ready architectural baseline
- **Date:** 2026-02-08
- **Decision:** Four non-negotiable architectural principles that must be present from the first line of code:
1. **Client-server separation** - even in single-player. The game simulation runs as a "server," the player view is a "client." Single-player = local client + local server. This is the single decision that makes or breaks retrofitting multiplayer.
2. **Information boundaries as a first-class system** - every piece of game state is tagged with who knows it. Not fog-of-war bolted on - the engine fundamentally thinks in terms of "what does this observer have access to." Required for single-player asymmetric information anyway. Multiplayer just means multiple observers.
3. **No baking player identity into the game loop** - the simulation doesn't know there's "the player." It knows there are characters, some of which are player-controlled. Adding a second player-controlled character should be a configuration change, not a rewrite.
4. **Deterministic simulation with input events** - game state advances based on timestamped actions, not "whatever the local machine calculated." Enables synchronization later without rewriting the simulation.
- **Side benefits (Nigel's observation):** Every one of these makes single-player better too. Information boundaries make NPC AI smarter about what they know. Client-server makes save/load cleaner. Deterministic simulation makes debugging easier. No sacrifice.
- **Engine implication:** Client-server friendliness is now a hard requirement on the engine shortlist (see Q-001).
- **Raised by:** Tyre (Technical Architect), endorsed by Team Leader as "sound architectural baseline."
### D-011: Fog of perception is non-negotiable (Pillar 1 infrastructure)
- **Date:** 2026-02-09
- **Decision:** Fog of perception is not a feature - it's the minimum requirement for information asymmetry to work with a top-down camera. Without it, the player is omniscient within their viewport and the entire information pillar collapses at the local map level. First-person camera gets this for free; top-down must enforce it.
- **Implementation:** Line-of-sight based (shadowcasting), not simple radius. Walls block vision, buildings are opaque, corners create blind spots, z-levels interact with sightlines.
- **Sound as secondary information channel:** Events outside LOS can be heard - footsteps, conversations, gunfire, alarms. Sound gives partial/directional information, prompting decisions based on incomplete data.
- **Applies to ALL entities:** NPCs use the same LOS/perception system as the player. An NPC who can't see you doesn't know you're there. NPCs have memory and inference (saw you enter a building → knows you're inside). Ties to D-010 principle 2: information boundaries are universal, the player's isn't special.
- **Fog returns when you leave:** Previously explored areas revert to fog over time. Information about locations decays. What you saw at the docks yesterday may not be true today.
- **v0.1 scope:** 2D shadowcast per z-level + sound propagation. Vertical LOS (looking between floors) deferred.
- **Rationale:** Team Leader identified overnight that top-down without fog is a fundamental gap in the information asymmetry design.
- **Raised by:** Team Leader (Jeroen), with technical framing by Tyre and Gestalt.
### D-012: Chunk-based map architecture for future borderless generation
- **Date:** 2026-02-09
- **Decision:** Maps use chunk-based generation and loading from day one. Chunks load/unload around the player. A bounded map is "only generate chunks within this boundary." Removing the boundary later to enable Minecraft-style borderless generation is a configuration change, not a rewrite.
- **v0.1:** Bounded ~150x150 per world, 2-3 z-levels, chunk-based internally.
- **Future:** Borderless generation. The world generates as you explore. The map can never be "solved" by walking to every corner. New areas develop, existing areas change.
- **Rationale:** Same principle as D-010 (multiplayer architecture) - design for the future, build the simpler version now.
- **Raised by:** Tyre (Technical Architect), endorsed by Team Leader.
### D-013: Diegetic insert/POI navigation system
- **Date:** 2026-02-09
- **Decision:** The player's map interface is diegetic - it IS the character's neural insert (Commonwealth technology). Not a game UI bolted on, but the character literally checking their implant's navigation overlay. Points of interest appear on the map only when learned through gameplay.
- **Canon basis (Miri):** Commonwealth citizens have inserts connecting them to the unisphere. Built-in navigation, messaging, data access. Characters in the books constantly check inserts for directions, news, contacts.
- **How POIs are learned:**
- Character background (starting knowledge based on who you are)
- NPC interactions (contacts send locations, tips, "meet me here" pins)
- Research (unisphere searches, case files, institutional databases)
- Physical discovery (finding something while exploring)
- **Different characters see different maps:** A cop sees flagged locations from case files. A Guardian sees safehouses and dead drops. A Senator sees political venues. Same city, different POI layer.
- **POIs can be manipulated:** Tips can be traps. Locations can be outdated. Information channels through the insert system carry the same trust/deception dynamics as verbal information.
- **Anti-Ubisoft:** No "climb tower to reveal icons." Map fills at the pace of investigation. Early game: sparse, frightening. Late game: dense, and you realize how much you missed.
- **Anchoring by desire, not force:** In a borderless world, the POI/insert system gives players reasons to go to specific places without funneling them. Navigation is pulled by player intent, not pushed by map design.
- **Multiplayer implication:** Players can share/send POIs via inserts. In co-op: collaborative conspiracy boards. In adversarial: feeding false locations.
- **Raised by:** Team Leader (Jeroen) proposed borderless + anchoring concept. Miri confirmed canon basis. Full team contributed mechanics.
### D-015: Camera locked to character, rotation as future option
- **Date:** 2026-02-09
- **Decision:** Camera is locked to the character at all times. No panning. Optionally rotates to character facing direction (player option, later version).
- **Rationale:** Pannable camera breaks the information model - you become a surveillance drone, not a character. Locked camera reinforces "you ARE this person." Rotation with facing direction restores directional audio mapping (binaural becomes viable again) and creates a natural vision cone (front = detailed, peripheral = reduced, behind = blind).
- **Vision cone model:**
- Forward: full LOS, full detail
- Peripheral: reduced range, dimmer
- Behind: fog / blind spot. You can be snuck up on.
- **Reference:** Hotline Miami's camera made that game terrifying with the same principle.
- **v0.1:** Locked camera, no rotation. Vision cone still works on fixed-north map. Rotation deferred as player option.
- **Raised by:** Team Leader (Jeroen).
### D-019: Top-down confirmed as primary camera, 3D cutscenes for key moments
- **Date:** 2026-02-09
- **Decision:** Top-down is the gameplay camera. Final. 3D cutscenes can be used for significant narrative moments (wormhole traversal, Dyson barrier opening, first contact, major reveals).
- **Rationale after full honest review:**
- What first-person would give us (visceral traversal, face-to-face conversations, natural asymmetry, spatial horror) is real but compensated by: vision cone + fog, internal monologue, perception mode overlays, sound model
- What top-down gives us that first-person can't: multi-layer information observation, tactical combat clarity, system legibility, NPC simulation visibility, strategic UI coexistence, 5-10x faster prototype
- Key insight (Gestalt): the fun is systems interacting - observation → insert check → thermal → monologue → mental note → exploitation. That sequence is BETTER top-down.
- Key insight (Paula): monologue interpreting faces/conversations is arguably richer than player reading 3D faces, and more faithful to Hamilton's close-POV writing style
- 3D cutscenes recapture the visceral moments without burdening gameplay engineering. They're decoupled, can be added as polish, game ships complete without them.
- Camera change to 3D IS the dramatic signal - player knows something significant is happening (Gestalt)
- **Architecture note (Tyre):** Client-server separation means the renderer is swappable. A full first-person client is architecturally possible in the future. Top-down now doesn't mean top-down forever.
- **v0.1:** Top-down only. No cutscenes. Those are milestone features.
- **Raised by:** Team Leader (Jeroen), after full team review of tradeoffs in Round 12.
### D-016: Internal monologue as core perception/atmosphere system
- **Date:** 2026-02-09
- **Decision:** The player character has an internal monologue that narrates sensory information the camera can't show, creates atmosphere, provides diegetic hints, and can be an unreliable narrator.
- **Functions:**
- **Perception bridge:** Translates non-visual senses into character voice. *"Footsteps behind me. Two people, unhurried."*
- **Atmosphere:** Character's running commentary on environment, mood, situation.
- **Diegetic tutorial:** Character thinks about what they might do. *"That terminal might have access logs."* No "press X" popups.
- **Unreliable narrator:** Monologue is character's INTERPRETATION, not ground truth. Can be wrong. *"Seems quiet. Safe to move."* (It wasn't safe.)
- **Character voice:** Varies by character background, mood, knowledge. Paranoid Guardian vs confident Senator walking the same street = different monologue = different experience.
- **Production note (Nigel):** Cheapest feature on the list - it's text. Thousands of contextual lines, AI-assistable generation, character-specific variants.
- **Raised by:** Emerged from team discussion. Tyre proposed text/log as sound option, team recognized broader potential.
### D-017: Perception modes as character-build system
- **Date:** 2026-02-09
- **Decision:** The fog/vision system supports multiple perception modes that vary by character build, equipment, and ascension level. Each mode reveals different information with different trust/quality tradeoffs.
- **Confirmed modes:**
- **Natural vision** - detail, color, identity. Blocked by walls. Everyone has it.
- **Thermal** - heat signatures through walls. Body count but no identity. Higher biononic / military gear.
- **Camera feeds** - remote visual from fixed positions. Only where cameras exist. Feed can be spoofed/looped. Hacker, institutional access, insert exploit.
- **Unisphere tracking** - location pings of known individuals. Only active inserts, can be masked. Law enforcement / intelligence access.
- **Audio analysis** - sound signatures, direction, classification. No visual. Insert processing, trainable skill.
- **Ascension scaling:**
- Baseline: natural vision + carried gear
- Enhanced: insert-based modes, camera access, audio processing
- Higher: biononic thermal, enhanced spectrum, passive scanning
- ANA-touched: pattern recognition across all feeds, predictive awareness
- **Playstyle implications (Nigel):** Low-tech Guardian playthrough = survival horror (blind, relying on contacts and paranoia). Senator playthrough = information overload (cameras and tracking but drowning in data). Perception modes are playstyle selectors.
- **Canon check (Miri):** All modes exist in the books. Higher biononics include enhanced senses. Unisphere connects everything. Security systems are hackable. Guardians actively spoof and evade. Starflyer agents defeat all sensor modes.
- **v0.1:** Natural vision cone + basic audio indicators + insert minimap only. Additional modes are milestone features, each self-contained and modular.
- **Engine implication:** Each perception mode is an observer query against the information boundary system (D-010 principle 2). Engine doesn't distinguish between eyes/thermal/camera - all are "given this sensor, what state is visible?"
- **Raised by:** Team Leader (Jeroen) proposed thermal and camera hacking. Full team developed into perception mode framework.
### D-018: Three-range sound model
- **Date:** 2026-02-09
- **Decision:** Sound information reaches the player through three ranges with decreasing accuracy and trust:
| Range | Method | Info quality | Trust level |
|-------|--------|-------------|-------------|
| Close (near/in LOS) | Stereo audio (maps to facing direction with camera rotation) | High accuracy, identity possible | Raw sensory, reliable |
| Medium (outside LOS, nearby) | Visual indicators at fog edge + internal monologue | Directional, imprecise, type classification | Sensory impression, reliable but vague |
| Long (across map) | Insert notifications, text alerts | Specific but delayed, location data | Network-dependent, spoofable, manipulable |
- **Key insight:** Each range is a different information QUALITY, not just distance. Close = trustworthy. Long = potentially compromised. The Starflyer's agents would absolutely spoof long-range feeds.
- **v0.1:** Screen-space stereo for close + visual fog-edge indicators for medium. Long-range insert alerts as stretch goal.
- **Raised by:** Full team discussion.
### D-014: v0.1 map specification
- **Date:** 2026-02-09
- **Decision:** First playable tech demo map spec:
| Layer | Spec |
|-------|------|
| World map | 3 worlds (Hub/Capital/Fringe), node graph with wormhole connections |
| Local maps | 1 per world, ~150x150 tiles, 2-3 z-levels, chunk-based |
| Key locations | 5-8 hand-crafted buildings/rooms per world embedded in procedural space |
| Ambient fill | Procedural from templates (district types vary per world) |
| Wormhole gates | Physical locations on local map, observable/traversable, social chokepoints |
| Fog | LOS-based shadowcasting with vision cone (forward/peripheral/blind), fog returns on departure |
| Sound | Stereo close-range + visual fog-edge indicators for medium range |
| Navigation | Diegetic insert minimap - dots when close, border arrows for known distant POIs |
| Camera | Locked to character, no panning, no rotation in v0.1 |
| Monologue | Internal character voice for non-visual perception, atmosphere, diegetic hints |
| Perception | Natural vision + basic audio only. Thermal/cameras/tracking deferred to milestones |
| NPCs | ~15 total across all worlds, on schedules, moving between locations |
| Art | Functional boxes with labels. Atmosphere carried by monologue and interaction models. |
- **Raised by:** Full team across Rounds 8-10.
### D-020: Engine and architecture selection — Godot client + Rust simulation via subprocess/IPC
- **Date:** 2026-02-09
- **Decision:** The game uses a split architecture: **Godot 4** (GDScript) as the rendering client, **Rust** with **bevy_ecs standalone** as the simulation server. The two communicate via **subprocess/IPC** (local socket for single-player, TCP for multiplayer). **NOT via GDExtension.**
- **Architecture:**
- The Rust simulation is a standalone binary with zero Godot dependencies. It runs the ECS world, perception queries, AI, storyteller, combat — all game logic.
- The Godot client is a pure renderer: receives `ObserverSnapshot` data, draws tiles/sprites/fog, plays audio, shows UI, captures input. No game logic in GDScript.
- Single-player: Godot launches the Rust binary as a child process. Local Unix socket or localhost TCP.
- Multiplayer: Godot connects to a remote Rust server. Same protocol. The simulation binary doesn't know the difference.
- This IS the D-010 client-server architecture — literally, not simulated.
- **Serialization:**
- **MessagePack** for all client-facing communication (Rust↔Godot). Dynamic structure supports variable HUD composition driven by perception modes (D-017). Cross-language, debuggable.
- **bincode** reserved for future Rust↔Rust server-to-server sync (same binary, hot path, zero overhead).
- **protobuf** rejected — solves deployment/versioning problems we don't have, poor GDScript support.
- **Why subprocess over GDExtension:**
- Eliminates entire risk categories: gdext pre-1.0 API churn, Godot version ABI breakage, FFI thread safety (`Gd<T>` is `!Send`), cross-boundary memory management.
- Decouples learning: build and test Rust simulation standalone, build Godot renderer standalone, connect when both work.
- Maps directly to D-010 client-server with no simulation — it IS client-server from day one.
- Either side can be upgraded, replaced, or scaled independently.
- Cost: ~1-5ms serialization latency per tick. Acceptable for a detective/strategy game, not a twitch shooter.
- **Key patterns:**
- `ObserverSnapshot`: the only data structure crossing the boundary. Contains visible entities, fog state, sound events, monologue triggers, HUD widget data. Variable shape per character build.
- `PlayerInput`: semantic actions (MoveNorth, Interact, UsePerceptionMode), not raw key events. Timestamped for deterministic processing.
- `SimBridge` trait: abstracts transport. `LocalBridge` (subprocess, channels) and `NetworkBridge` (TCP, MessagePack) implement the same interface.
- **Kill switch:** If no working prototype (character + fog + one NPC) exists by week 8 of development, pivot to pure Godot. If bridge/sync code exceeds game logic for 3 consecutive sprints, the architecture tax is too high.
- **Development sequence:**
1. Build Rust simulation as standalone binary (testable via terminal/logs)
2. Build Godot renderer as standalone project (hardcoded test data)
3. Connect via MessagePack protocol
- **Project structure:**
```
simulation/ # Pure Rust, bevy_ecs, zero Godot deps
client/ # Godot 4 project, GDScript only
protocol/ # Shared message definitions (MessagePack schemas)
```
- **Evaluation reports:** `docs/architecture/eval-godot-rust-bridge.md` (Tyre), `docs/architecture/risk-godot-rust-bridge.md` (Troblum)
- **Raised by:** Team Leader (Jeroen) proposed Godot client + Rust backend. Tyre designed architecture. Troblum's risk assessment shifted integration from GDExtension to subprocess/IPC. Full team endorsed.
- **Dissent:** None. Troblum's CRITICAL risk flags on GDExtension were accepted; subprocess approach addresses them.
### D-021: Official project title — "The Settled Reach"
- **Date:** 2026-02-10
- **Decision:** The official project and game title is **"The Settled Reach"**. The domain settledreach.com has been secured. Individual campaigns or scenarios can have subtitles in the format "The Settled Reach: [Scenario Name]" but the core title remains consistent.
- **Rationale:** Following Round 14's worldbuilding confirmation establishing the Settled Reach as the original setting, the Team Leader confirmed this as the official project title. The name reflects the setting's core tension: a civilization that has "settled" across the stars but whose "reach" is ultimately limited by infrastructure it doesn't fully control or understand.
- **Repository note:** The repository folder and git history will remain as "commonwealth" for historical continuity and to avoid breaking existing paths. The code name vs official title distinction is acceptable (similar to how game projects often have internal code names).
- **Raised by:** Team Leader (Jeroen), following Round 14 worldbuilding discussion.
- **Dissent:** None.
### D-022: Process — Round-based collaboration workflow
- **Date:** 2026-02-10
- **Decision:** Going forward, discussions are captured directly in round documents at `docs/discussions/round-NN-topic.md` rather than in DISCUSSION.md. DISCUSSION.md has become unwieldy to manage and archive. Qatux must be included in all team interactions (single-agent or multi-agent) to document discussions.
- **Rationale:** DISCUSSION.md grew to 26,000+ tokens and became clunky to archive. Direct round document creation is cleaner and more maintainable. Qatux's inclusion ensures no decisions or context are lost.
- **New workflow:**
1. Create round document at `docs/discussions/round-NN-topic.md`
2. Document collaboration within that file
3. Extract decisions to DECISIONS.md
4. Update discussions README
5. Re-index as needed
- **Implementation note:** DISCUSSION.md was removed 2026-02-10 after verifying all content (Rounds 1-15) was properly archived in `docs/discussions/`.
- **Raised by:** Team Leader (Jeroen).
- **Dissent:** None.
- **Effective:** Immediately (Round 15 onward).
### D-023: Three-tier content model with life-sim substrate
- **Date:** 2026-02-10
- **Decision:** The game uses a three-tier content architecture: Tier 1 (authored drama modules drawn from a pool at game start — plural, optional, relocatable), Tier 2 (templated content with combinatorial variation — both intrigue and life templates), Tier 3 (procedural filler with systemic hooks for Tier 2 colonization). Daily life is the substrate; conspiracies are weather. Players can investigate, pursue careers/relationships, or both. All are valid playthroughs. The storyteller activates Tier 1 modules based on player proximity and engagement, not timers.
- **Rationale:** A galaxy-spanning game needs content architecture that scales without hand-crafting everything. The life-sim substrate creates attachment that gives conspiracies emotional weight. Pool-based Tier 1 modules enable replayability and DLC expansion.
- **Raised by:** Team Leader (Jeroen), with full team endorsement across 3 rounds
- **Dissent:** None
### D-024: NPC generation model — 10 axes + combat component
- **Date:** 2026-02-10
- **Decision:** NPCs are generated with 10 axes: 7 essential (Want, Secret/vulnerability, Relationships 1-3, Tolerance threshold, Daily routine, Information inventory, Contentment) and 3 supporting (Personality traits 2-3, Tell system, Skill set including combat tag). Combat capability lives as an optional CombatCapability ECS component triggered by the combat-trained skill tag, not as an axis. Faction loyalty is folded into Relationships+Secret (discoverable, not labeled). Romantic profile is folded into Want+Personality+compatibility tag. Cultural/origin template is generation-time flavor, not a runtime axis. Triangles (3 NPCs with conflicting interests) are the atomic unit of social intrigue — 2 per template minimum, 1 cross-template.
- **Rationale:** Axes that create contradictions within NPCs produce player decisions. The 5 key interactions (Want×Secret, Routine×Secret, Tolerance×Relationships, Want×Relationships, Personality×Tolerance) drive the full investigation-and-social gameplay loop. Contentment axis (proposed by Gore) connects generated NPCs to the thematic spine. Combat as component follows the same pattern as perception modes (D-017).
- **Raised by:** Gestalt (consolidation), Gore (contentment axis), Paula (triangle model), Tyre (combat component). Full team endorsed.
- **Dissent:** None
### D-025: Social site / functional cluster as atomic template unit
- **Date:** 2026-02-10
- **Decision:** The atomic Tier 2 template unit is a "social site" (mechanical term) housed in a "functional cluster" (spatial term): 4-8 NPCs who regularly interact, within 15-40 tiles of connected space with internal sightlines. Social group defines systemic identity (who, what triangles). Physical cluster defines spatial identity (sightlines, overhearing, public/private). Templates define roles; NPCs fill roles. One NPC can hold roles in multiple social sites. NPC identity is independent of template instantiation. NPCs are owned by exactly one template with reference links (carrying relationship metadata) to others.
- **Rationale:** Life in the Settled Reach happens in clusters of connected spaces. The functional cluster is the natural unit of social observation, which is the natural unit of gameplay. Single-ownership with reference links prevents lifecycle conflicts while enabling cross-template contamination.
- **Raised by:** Gestalt (social site), Miri (functional cluster), Tyre (ownership model), Paula (reference metadata)
- **Dissent:** None
### D-026: Simulation tiers with timestamp-based eviction
- **Date:** 2026-02-10
- **Decision:** Four simulation tiers: Active (30-80 NPCs, full sim at 10-20 ticks/sec), Background (500-2,000 NPCs, state machine ticks 1/game-minute with 4 machines: schedule, mood, relationships, job), State-saved (10,000+, frozen serialized structs ~1-2KB each), Ungenerated (doesn't exist yet). Eviction uses interaction-timestamp LRU against available sim-space. NPCs with active scope tags (neighborhood, active-quest, colleague, known-contact) stay fully simulated. State-saved NPCs reactivate on player return (~2-5ms). Density follows the player — content generated ahead of arrival, home system fully instantiated at game start.
- **Rationale:** Timestamp-based eviction replaces categorical persistence rules with one priority queue. State-save makes disposal reversible. bevy_ecs dynamic component add/remove makes tier transitions seamless. Tyre confirmed all proposals fit within performance budgets.
- **Raised by:** Team Leader (timestamp model), Tyre (technical validation), Gestalt (scope tags)
- **Dissent:** None
### D-027: Vertical slice — smuggler + detective, two-character proof
- **Date:** 2026-02-10
- **Decision:** The proof-of-concept vertical slice is one station district containing: 1 workplace social site, 1 social venue (bar), 1 smuggling ring template, shared NPCs. Two playable characters: smuggler (logistics worker, insider access to criminal templates, social camouflage) and detective (institutional investigator, authority access, analytical). Success criteria: (1) 30 minutes of daily-life breathing room before contamination activates, (2) both playthroughs feel like fundamentally different games, (3) after each playthrough player names an NPC they felt conflicted about, (4) the observe→notice→follow→discover sequence emerges from systems not scripts.
- **Supersedes:** D-006 (prototype scenario: Institute/Armstrong/Guardians)
- **Rationale:** Smuggler + detective creates adversarial divergence — the detective's target IS the smuggler's daily life. Same templates, same NPCs, inverted relationships. Proves character-as-lens, contamination, life-sim attachment, and replayability simultaneously. Tyre confirms: ~20% more effort than single-character, no new architecture.
- **Raised by:** Team Leader (smuggler+detective choice), Nigel (two-character requirement), Ozzie (30-min runway), Gore (emotional criterion), Gestalt (systems criterion)
- **Dissent:** None
### D-028: Dialogue architecture — tagged line pools with four relational layers
- **Date:** 2026-02-10
- **Decision:** Dialogue uses tagged line pools with systemic selection, not branching trees. Four relational layers, all planned from authoring day one, built in sequence: (1) Access tiers — insider/outsider/authority/peer filter on every line, (2) Relationship history — interaction log modifying greeting and topic selection, (3) Trust-gated gossip — three disclosure tiers per role (surface/real/secret), (4) Unprompted disclosure — NPCs volunteer information weighted by trust and mood. Trait modifiers (not per-trait scripts) reshape delivery — base lines + trait transformation guide per template. Template content packs as writing deliverable: role voice kits, situation scripts, monologue hooks, environmental text, trait transformation guide. ~165-210 authored lines per Tier 2 template, generation-expanded 4x. Social dialogue budgeted 40% more than investigation. Line previewer CLI required as authoring tool and regression test harness.
- **Rationale:** All four layers are load-bearing — each enriches the previous ones. Tagged pools avoid combinatorial explosion while trait modifiers produce character variety. The generation pass (write 10, generate 40) scales authored content. Every memorable line needs a human hand; the generation pass fills the background.
- **Raised by:** Mellanie (authoring model), Paula (relational layers), Gestalt (axis-to-pipeline mapping), Tyre (previewer feasibility)
- **Dissent:** None on model. Minor ordering difference: Mellanie front-loads access tiers (structural), Paula front-loads relationship history (narrative). Both sequences work.
### D-029: Population entanglement ratio — 30/50/20
- **Date:** 2026-02-10
- **Decision:** NPC population split: ~30% truly flat (routine + greeting, social wallpaper), ~50% mundane triangles (neighbor disputes, workplace rivalries, relationship tensions — no conspiracy connection), ~20% entangled with intrigue content. The entanglement rate varies per seed to prevent metagaming calibration. Module attachment to known NPCs uses a ~60-70/30-40 ratio (known vs stranger), also varying per seed. The unentangled majority is both thematically essential ("is this enough?" needs honest counterweight) and mechanically essential (investigation signal requires noise floor).
- **Rationale:** If every NPC is suspicious, investigation collapses. The mundane triangles ARE the life-sim game — hours of play that never touch conspiracy. Variable entanglement rate defeats metagaming across playthroughs. Quiet life must feel genuinely good, not empty.
- **Raised by:** Gore (thematic), Paula (30/50/20 split), Nigel (anti-metagaming), Team Leader (majority unentangled)
- **Dissent:** None
### D-030: Testability architecture — 8 decisions for ticket #214
- **Date:** 2026-02-11
- **Decision:** The v0.1 testability architecture is confirmed with 8 sub-decisions from the Gap Analysis Workshop (Round 18):
1. **Rust test organization = Hybrid.** `#[cfg(test)]` for unit tests inside modules + `tests/` directory for integration tests. Both via `cargo nextest run`.
2. **Godot test framework = gdUnit4** (changed from GUT). Native JSON output, stable headless via `GdUnitCmdTool`, `GdUnitSceneRunner` for scene lifecycle tests, organizational maintenance.
3. **IPC testing = Three-layer architecture.** Layer 1: fixture-based serialization roundtrip (fast, every edit). Layer 2: mock subprocess protocol state machine (medium, every PR). Layer 3: real subprocess integration (slow, daily/pre-merge).
4. **Production code constraints + CauseChain.** No `#[cfg(test)]` in production. Public API is the test surface. ECS World setup replaces mock injection. CauseChain is a production component (monologue provenance, journal, debugging) that tests also leverage.
5. **Test runner tooling.** `cargo-nextest` (Rust) + gdUnit4 (Godot) + bash wrapper scripts in `test/` directory, whitelistable for agent use.
6. **Test output format = JSON summary.** Consistent schema across all runners (suite, total, passed, failed, failures array). JUnit XML as secondary CI format.
7. **#201 (Deterministic replay) promoted to CRITICAL.** Simulation must consume time, randomness, and input exclusively through injectable resources (`SimulationTime`, `SimRng`, `InputQueue`). Required by D-010 principle 4.
8. **Test priority aligned with hard blockers.** Phase 1 (sprint 1-2): test infra + collision/pathfinding/time. Phase 2 (sprint 3-4): monologue pipeline integration test + information boundary negative tests. Phase 3 (sprint 5+): CauseChain verification + divergent snapshots.
- **Rationale:** Two rounds of analysis by Tyre (Technical Architect) and Hoshe (QA Engineer) with cross-validation from all design agents. Key change: gdUnit4 over GUT driven by agent-driven development requirements (JSON output, headless stability, bus factor). CauseChain endorsed unanimously after all design agents independently identified the need for information provenance tracking.
- **Raised by:** Tyre (architecture), Hoshe (testability analysis). Full workshop endorsed.
- **Dissent:** GUT vs gdUnit4 resolved in Hoshe's favor — Tyre explicitly changed position. No remaining dissent.
### D-031: Time system — game clock and day phases
- **Date:** 2026-02-11
- **Decision:** The v0.1 time system uses the following model:
- **Tick-to-time mapping:** 10 simulation ticks = 1 game-minute (at 10 tps, 1 real second = 1 game-minute). A 30-minute real-time play session covers ~12-18 game-hours — enough for a full NPC daily cycle.
- **Day phases:** Four phases drive routine transitions: Morning, Afternoon, Evening, Night. NPCs transition between routine activities at phase boundaries (e.g., go to work in Morning, to the bar in Evening).
- **Time display:** Diegetic — shown on the player's neural insert HUD. The character checks their insert to see the time, consistent with D-013.
- **Pause:** Available in single-player. Simulation freezes, UI stays responsive. Compatible with future multiplayer (D-009) where pause would be disabled or vote-based.
- **Time-skip:** Deferred for v0.1. The "wait/stake out" mechanic (if implemented) would advance time while the player observes from a fixed position.
- **Not in scope for v0.1:** Deep time (years/decades), day/night lighting, seasonal cycles, time zones between locations.
- **Resolves:** Q-009
- **Raised by:** Tyre (technical proposal), Gestalt (day-phase design). Confirmed in Round 18 Gap Analysis Workshop with full team consensus.
- **Dissent:** None.
### D-004: Team composition confirmed
- **Date:** 2026-02-08
- **Decision:** Team of 8 agents + Team Leader.
| Agent | Role |
|-------|------|
| MIRI | Lore Expert & Canon Guardian |
| OZZIE | Player Experience / "Wow Factor" Advocate |
| PAULA | Narrative & Political Depth |
| GORE | Themes & Endgame Design |
| GESTALT | Systems Design & Fun Factor |
| NIGEL | Sandbox & Replayability |
| TYRE | Technical Architecture & Feasibility |
| SCRIBE | Documenter |
| Jeroen | Team Leader, final decisions |
---
## OPEN QUESTIONS
### Q-001: Game engine selection
- **Status:** Resolved → D-020
### Q-002: Scope of v0.1 playable prototype
- **Status:** Map spec resolved (D-014). Remaining: mechanics, characters, interactions for minimum playable build.
- **Assigned to:** Full team
### Q-003: Art direction / presentation style
- **Status:** Partially resolved for v0.1 (D-014: boxes with labels, atmosphere via dialog/interaction)
- **Remaining:** Long-term art direction beyond tech demo.
- **Assigned to:** TBD
### Q-004: One campaign spanning all eras or separate era scenarios?
- **Status:** Not yet discussed
- **Context:** Gore raised that Commonwealth Era and Void Era play very differently. Prototype focuses on pre-Starflyer War era.
- **Assigned to:** Gore, Miri to lead discussion
### Q-005: Scale for prototype - locations, characters, factions
- **Status:** Partially scoped
- **Early signal:** Institute/Armstrong City hub, ~10-20 characters, Guardians + institutional + political factions
- **Assigned to:** Gestalt, Tyre, Miri
### Q-006: Multiplayer or single-player only?
- **Status:** Resolved → D-009
### Q-007: Target platform(s)
- **Status:** Not yet discussed
- **Context:** Team Leader has Linux background (Fedora). Cross-platform considerations?
- **Assigned to:** Tyre
### Q-008: Licensing / distribution model
- **Status:** Not yet discussed
- **Question:** Open source? Free? Commercial? This affects engine choice and asset decisions.
- **Assigned to:** Team Leader
### Q-009: Time system
- **Status:** Resolved → D-031
### Q-010: Storyteller AI design
- **Status:** Not yet discussed
- **Question:** How does the Rimworld-style storyteller work? What are the pacing rules? How much structural randomness vs dramatic randomness?
- **Assigned to:** Gestalt, Nigel
### Q-011: Character selection and playable characters
- **Status:** Not yet discussed
- **Question:** Which characters are playable in the prototype? How different are their starting positions? Can you play canon characters or only original ones?
- **Assigned to:** Miri, Paula
---
## REJECTED ALTERNATIVES
### R-001: Stellaris mod
- **Rejected:** 2026-02-08
- **Reason:** Character system too shallow, multi-empire assumption conflicts with Commonwealth's single-civilization focus, wormhole-as-infrastructure not achievable within Stellaris modding. Team Leader's experience with Star Trek: New Horizons confirmed that even well-suited IPs struggle with character connection in Stellaris.
### R-002: CK3 total conversion
- **Rejected:** 2026-02-08
- **Reason:** Would require building a space map from scratch within CK3's framework - essentially building a game inside a game. The map system fundamentally doesn't support the complexity needed.
### R-003: Other existing games (Distant Worlds 2, GalCiv IV, Sins of a Solar Empire II, Victoria 3)
- **Rejected:** 2026-02-08
- **Reason:** Each captures at most 40% of what's needed. Smaller modding communities, less mature tools, and none solve the core CK3+Stellaris hybrid requirement.
### R-004: Pure Bevy (Rust) — no Godot
- **Rejected:** 2026-02-09
- **Reason:** No visual editor (level design is code-only). UI framework in flux. API breaks significantly between versions. For a solo developer who needs visual tools for hand-crafted buildings (D-014), Godot's editor is a massive productivity advantage. Bevy's ECS is used — just not its renderer.
### R-005: Pure Godot (GDScript or C#)
- **Rejected:** 2026-02-09
- **Reason:** Scene tree paradigm fights ECS-style simulation. Perception queries (D-017) and information boundaries (D-010) map naturally to ECS component queries, not scene tree traversal. Multi-core scaling for expanded content impossible in GDScript. Kept as kill-switch fallback if Rust architecture exceeds time budget.
### R-006: Godot + Rust via GDExtension
- **Rejected:** 2026-02-09
- **Reason:** gdext is pre-1.0 with breaking API changes. Godot version upgrades break GDExtension ABI. Thread safety at FFI boundary is CRITICAL risk (`Gd<T>` is `!Send`/`!Sync`). Couples Rust and Godot learning curves. Subprocess/IPC achieves the same architecture without the FFI risk surface, and maps directly to D-010 client-server. See `docs/architecture/risk-godot-rust-bridge.md` for full analysis.
### R-007: Godot + C++ via GDExtension
- **Rejected:** 2026-02-09
- **Reason:** More mature bindings than gdext, but trades Rust's safety guarantees for C++ memory unsafety. No advantage over subprocess/IPC approach. Developer not experienced in C++.
### R-008: Fyrox (pure Rust engine)
- **Rejected:** 2026-02-09
- **Reason:** Single maintainer. ~1/50th of Godot's community. Less documentation, fewer tutorials, weaker AI training data for Claude Code. Single-maintainer risk unacceptable for multi-year project.
### R-009: Custom framework (Rust + raylib/macroquad)
- **Rejected:** 2026-02-09
- **Reason:** Maximum control but you build everything — tilemap rendering, camera, UI, audio, input, asset pipeline. Months before testing a mechanic. The game's hard problems are simulation, not rendering — don't reinvent the rendering wheel.
### R-010: protobuf for client-server serialization
- **Rejected:** 2026-02-09
- **Reason:** Schema evolution across independent deployments is a problem we don't have (one developer, client and server ship together). Poor GDScript support. Rigid schema fights dynamic HUD composition driven by perception modes (D-017). MessagePack's schema-optional nature fits better.
---
*Document maintained by QATUX. Last updated: 2026-02-11*
# Decisions Archive
Decisions have been reorganized by domain. See:
- [decisions/README.md](decisions/README.md) for the domain index
- Individual domain files in `decisions/`
| File | Domain | Count |
|------|--------|-------|
| [architecture.md](decisions/architecture.md) | Technical foundation | 8 |
| [perception.md](decisions/perception.md) | Player observation | 6 |
| [content.md](decisions/content.md) | NPC, dialogue, templates | 5 |
| [scope.md](decisions/scope.md) | Game concept, prototype | 9 |
| [process.md](decisions/process.md) | Team, workflow | 3 |
| [questions.md](decisions/questions.md) | Open questions | 11 |
| [rejected.md](decisions/rejected.md) | Rejected alternatives | 10 |
*Restructured 2026-02-11. Original monolithic format in git history.*