settled-reach/decisions/questions-architecture.md

Open Questions — Architecture

Technical foundation questions: engine, protocols, data structures, performance, save/load.

---

Q-001: Game engine selection

• Status: Resolved → D-020

Q-006: Multiplayer or single-player only?

• Status: Resolved → D-009

Q-009: Time system

• Status: Resolved → D-031

Q-018: Shadowcasting algorithm selection

• Status: Resolved → D-035
• Question: Which line-of-sight algorithm should be used? Symmetric shadowcasting (Albert Ford) vs recursive shadowcasting. Both are proven but differ in symmetry properties (symmetric: if A sees B, then B sees A) and implementation complexity. Requires benchmarking at 150x150 map scale with 30 entities to validate performance within 100ms tick budget.
• Context: D-011 mandates LOS shadowcasting for fog of perception. Architecture review identified this as unspecified (audit section 2.2). Critical for Sprint 2 perception pipeline.
• Assigned to: Tyre, Dudley
• Source: Architecture Review Audit 2026-02-11

Q-019: Entity ID stability strategy

• Status: Partially resolved → D-041
• Resolution: Server-side: StableEntityId component + EntityRegistry resource provides bidirectional StableId(u64) <-> Entity mapping. StableId assigned once at entity spawn, never changes, persists across save/load. Knowledge graphs reference StableId, not bevy Entity. Client-side mapping (Godot StableId -> scene node lifecycle) remains open.
• Remaining: Client-side entity lifecycle management, scene node mapping strategy.
• Date partially resolved: 2026-02-11
• Assigned to: Tyre, Dudley (client-side portion)
• Source: Knowledge Graph & Information Boundaries Workshop

Q-020: Multi-entity collision resolution

• Status: Open
• Question: When two NPCs attempt to move to the same tile on the same tick, what is the resolution policy? Options: first-write-wins (deterministic with system ordering), both fail (conservative), priority-based (e.g., player > NPC, Active tier > Background tier).
• Context: D-012 defines tile collision. WalkabilityMap exists (server/src/simulation/movement.rs) but handles single-entity validation. Architecture review identified multi-entity collision as unspecified.
• Assigned to: Gestalt, Dudley
• Source: Architecture Review Audit 2026-02-11

Q-021: Tick budget overflow policy

• Status: Open
• Question: When a simulation tick exceeds the 100ms budget, what happens? Options: (1) slow down real-time and preserve determinism (tick completes fully before next), (2) skip ticks and break determinism, (3) cap work per tick and defer to next tick. Must align with D-010 principle 4 (deterministic simulation).
• Context: D-026 defines 100ms tick budget for Active tier at 10 tps. Architecture review consensus recommendation proposes "slow real-time, don't skip ticks." Needs formal decision.
• Assigned to: Tyre, Dudley
• Source: Architecture Review Audit 2026-02-11

Q-022: NPC pathfinding cache eviction

• Status: Open
• Question: With 80 Active-tier NPCs each caching ~3 pathfinding routes, the cache holds ~240 paths. What is the eviction policy? LRU? Time-based expiration? Fixed size per NPC? How are paths invalidated when walkability changes (doors lock, areas become restricted)?
• Context: Architecture review identified pathfinding as MEDIUM gap (audit section 2.2). Cache management needs specification regardless of algorithm choice.
• Assigned to: Tyre, Dudley
• Source: Architecture Review Audit 2026-02-11

Q-023: Debug visualization scope

• Status: Open
• Question: What information should the debug overlay display? Candidates: LOS rays, pathfinding waypoints, vision cones, information boundary tags (who knows what), tick timing breakdown, spatial partition grid cells. Dev-only tool, or accessible for mod development?
• Context: Architecture review (Troblum) identifies debug visualization as missing operational infrastructure. Needed for debugging perception system, information boundaries, and performance issues.
• Assigned to: Tyre, Stig
• Source: Architecture Review Audit 2026-02-11

Q-029: Save file format design

• Status: Open
• Question: What should the long-term save file format look like? Key considerations:
  1. Versioning and migration: How do saves survive across game versions? Schema evolution strategy (field additions, renames, removals). Should saves embed a version number and run migrations on load?
  2. Compression: Raw MessagePack vs compressed (zstd, lz4)? Tradeoff between save/load speed and file size. SaveStateV1 is already MessagePack — does that carry forward?
  3. Integrity: Checksums or signatures to detect corruption? CRC32 header?
  4. Metadata header: Should the file have a readable header (game version, save date, play time, character name) that the loading screen can read without deserializing the full save?
  5. Determinism: D-010 requires deterministic simulation. Can saves capture enough state to resume deterministically, or is approximate resume acceptable?
  6. Modding: Should the format be documented for mod authors? Does it need extension points?
  7. Cloud sync: Any considerations for Steam Cloud or similar? File size limits?
• Context: Sprint 19 implements a quick-and-dirty save format (D-085 per-game directories, MessagePack serialization from SaveStateV1). This question tracks the thorough design pass for production quality.
• Assigned to: Tyre, Dudley
• Source: Team Leader directive (Sprint 19 planning)

Q-030: Seed configuration schema

• Status: Open
• Question: What artifact records all randomizer decisions at game start? The wiki-review workshop proposed a seed-state.yaml capturing: world seed, character selection, pool draws (Tier 1 modules, FRIEND selection, contraband variant), template assignments, NPC trait rolls, triangle configurations, and entanglement pattern. Ticket #394 (seed configuration schema design) exists but the design is open.
• Assigned to: Tyre, Gestalt
• Source: Wiki Review Workshop + v0.1 Content Scoping Workshop

Q-046: Departure schedule model — departure windows as generator output for docked vessels

• Status: Resolved → D-108 (MobileChunk Specification)
• Resolution: scheduled_departure: Option<SimTick> in Docked state is mandatory generator output. Vessels without departure schedules are an error state. The Docked struct must include docked_since: SimTick and scheduled_departure: Option<SimTick> — these fields must be added at implementation time (absent from Tyre's Round 4 canonical struct).
• Date resolved: 2026-02-27
• Source: Generator Architecture Workshop (#562)
• Assigned to: Tyre + Miri

Q-059: PlatformInfo full interface scope

• Status: Resolved → D-141
• Question: What properties should PlatformInfo expose beyond power state, memory, and file paths?
• Resolution: 23 properties across 7 categories (power, memory, CPU, GPU, platform identity, display, locale), 1 signal (power_profile_changed), 2 methods (refresh_memory, get_diagnostics). Researched Unity SystemInfo, Unreal FPlatformMisc, SDL3. Skip: GPU VRAM (not available in Godot), CPU frequency, audio devices (AudioManager owns that), network connectivity (single-player), VM detection. Add properties only when a ticket needs them — no stubs. get_diagnostics() returns flat Dictionary for bug reports.
• Date raised: 2026-03-13
• Date resolved: 2026-03-13
• Assigned to: Tyre
• Source: Sprint 26 client work (#646, #659)

Q-060: Can Surface Deform produce acceptable clothing at extreme body types?

• Status: OPEN
• Question: The Surface Deform batch pipeline runs and produces output, but visual quality at extreme body types (heavy, thin) has not been verified at gameplay or mugshot zoom. Does the clothing mesh hold its shape when Surface Deform stretches it to fit a heavy body?
• Date raised: 2026-03-19
• Source: Quaternius aesthetic spike — clothing pipeline validation
• Cross-reference: D-162

---

Q-063: Footstep VFX system (Godot Asset Library #4122)

• Status: Open
• Question: Integrate the Footsteps asset (https://godotengine.org/asset-library/asset/4122) into the character visual system. Jeroen wants this in the game. Evaluate: how does it hook into the animation system? Does it work with our toon shader pipeline? Should footstep triggers be animation events or raycast-based?
• Cross-reference: D-149 (3D characters rendered live), D-160 (body segments)

---

Q-064: 3D planet generator for wiki system screenshots

• Status: Resolved — answered by #779 (Sprint 32)
• Question: Evaluate the Godot 3D Planet Generator (https://github.com/remijean/godot-3d-planet-generator) for generating unique planet visuals per star system in the wiki. Each of the 301 systems could get a procedurally generated planet rendered as a screenshot for its wiki page. Key questions: can we get enough visual variety across 301 systems (different biomes, atmospheres, colors, ring configurations)? Can the generator run headlessly for batch rendering? What's the parameter space — how many distinct-looking planets can it produce? Could the planet configs be seeded from system properties (star class, habitable zone, etc.) for consistency across regenerations?
• Resolution: Pure Python ray-sphere renderer (spikes/planet-renders/generate_planets.py) replaces the Godot plugin approach. Answers all evaluation criteria: (1) visual variety via planet_class type × body_id seed = 301 distinct renders, (2) fully headless — no Godot required, ~2s for all 7 types, (3) seeded from system properties for reproducibility. Avoids headless Godot rendering complexity. See docs/design/planetary-screenshots-spec.md.
• Cross-reference: Wiki system pages (docs/wiki/), world generation pipeline

---

Q-065: Shooting mechanics — Deep RayCast 3D vs Ballistic Penetration System vs server-side

• Status: Open
• Question: Evaluate approaches for projectile/hitscan combat mechanics. Three options: (a) Deep RayCast 3D (https://godotengine.org/asset-library/asset/4464) — penetrating raycasts through multiple objects, chain hits, laser effects. (b) Ballistic Penetration System (https://godotengine.org/asset-library/asset/4356) — physics-based damage reduction through materials (thickness, hardness, penetration depth). (c) Roll our own server-side in Rust/bevy_ecs since combat is server-authoritative. Key question: should hit detection and damage calculation live on the client (these plugins) or the server (D-010 server authority)? Could the client use these for visual feedback (tracer rendering, impact effects) while the server handles the authoritative hit/damage calculation?
• Cross-reference: D-010 (server-authoritative simulation), D-012 (client is a view)

---

Q-066: PathMesh3D for procedural environment geometry

• Status: Open
• Question: Evaluate PathMesh3D (https://godotengine.org/asset-library/asset/3626) — extrudes 2D profiles along 3D paths at runtime to create meshes. C++ GDExtension, MIT licensed. Potential uses: procedural pipes/cables/wiring in station interiors, rail/track generation, corridor geometry, any environment element that follows a path. Not clear yet where this fits in the pipeline — could be a generator-time tool or a runtime decoration system. Worth investigating when environment procedural generation starts.
• Cross-reference: Generator architecture, environment asset pipeline

---

Q-067: Vehicle physics for in-world transport

• Status: Open
• Question: Evaluate vehicle physics plugins for player/NPC transport between zones. Two candidates: (a) MAdvanced Vehicle System (https://godotengine.org/asset-library/asset/3697) — full car physics with gearbox, AI traffic, traffic management, lights, sounds, steering wheel support. Godot 4.6, MIT, actively updated. (b) Godot Simple Motorcycle Physics (https://godotengine.org/asset-library/asset/4670) — raycast-based motorcycle, simpler scope. Questions: does the game need driveable vehicles or just NPC traffic? Is vehicle movement client-side physics or server-authoritative? The AI traffic and traffic management in MAdvanced could serve NPC vehicle simulation. Scope for v0.2: probably not, but worth tracking for when districts/zones need inter-zone travel.
• Cross-reference: D-010 (server authority), world generation

---

Q-068: Procedural terrain generation patterns — chunk loading and noise

• Status: Open (reference/inspiration)
• Question: Block-based 3D Procedural Map Generation Demo (https://godotengine.org/asset-library/asset/2698) — Perlin noise terrain with chunk-based loading/unloading. Not directly usable (block-based, Godot 4.2) but the patterns are relevant: seed-deterministic generation for consistent worlds across sessions, chunk loading within player proximity for memory/performance, terrain type placement from noise values. Reference for when the world generator produces location terrain and the client needs to stream it. The chunk load/unload pattern maps to our simulation tier system (Active → Background → State-saved).
• Cross-reference: Generator architecture, D-097 (simulation tiers), D-096 (chunk loading)

---

Q-069: GPU cloth simulation for dynamic clothing

• Status: Open
• Question: Evaluate GPU Cloth Simulation (https://godotengine.org/asset-library/asset/4853) — compute shader-based cloth with collisions, turbulence, pinning, inertia. MIT, Godot 4.5. NOT for character clothing (solidify is our look). Best use: environmental dressing — sails on ships, flags, awnings, laundry on lines, market tarps, banners. These are static-anchor cloth meshes that add life to environments without per-body fitting. Evaluate performance cost per cloth instance and max reasonable count per scene.
• Cross-reference: Character visual system, D-152 (LOD tiers), clothing pipeline

---

Q-070: NobodyWho LLM patterns vs our Rust voice pipeline

• Status: Open (evaluated, not adopted)
• Question: NobodyWho (https://docs.nobodywho.ooo/) is a GDExtension providing in-process LLM inference (llama.cpp) with GGUF models. Evaluated against our existing Gemma 2 voice pipeline in server/src/voice/. Verdict: does not fit D-020 — client-side LLM violates client-as-pure-renderer. Our server-side Rust approach is architecturally correct. Patterns worth adopting: (a) tool calling with grammar-enforced structured output — NPC queries game state via typed function calls, guaranteed parseable. (b) Preemptive context shifting for infinite conversations without truncation. (c) GGUF model flexibility (not locked to Gemma 2). These patterns should be evaluated for integration into the Rust voice pipeline, not as a client-side plugin.
• Cross-reference: D-020 (server authority), server/src/voice/ pipeline, D-010 (determinism)

---

Q-071: Steam integration template for multiplayer lobbies

• Status: Open (future — Steam/multiplayer stage)
• Question: Two resources for Steam multiplayer: (a) SteamMultiplayerPeer (https://github.com/expressobits/steam-multiplayer-peer) — the actual networking primitive. Implements Godot's MultiplayerPeer interface over Steam networking (relay, NAT traversal, lobbies). This is the building block we'd use. (b) Steam Template (https://godotengine.org/asset-library/asset/3328) — CC0 template wrapping SteamMultiplayerPeer with menu UI, settings, lobby management. Reference for UI patterns. Key architecture question: our server-authoritative model (D-010, D-020) means the dedicated server runs the simulation. SteamMultiplayerPeer could handle client↔server transport (using Steam relay for NAT traversal) rather than raw TCP/WebSocket. This would give us Steam friend invites, lobby discovery, and relay infrastructure for free. Evaluate when multiplayer work begins.
• Cross-reference: D-010 (server authority), D-020 (subprocess IPC), Oscar (networking agent)

---

Q-072: BitTorrent for P2P asset/mod/world state distribution

• Status: Open (future — multiplayer stage)
• Question: godot-torrent (https://godotengine.org/asset-library/asset/4384) — full BitTorrent protocol as GDExtension, C++ native performance. MIT, Godot 4.5. Potential uses: (a) mod/asset sync between multiplayer clients without central CDN costs — players seed assets to each other. (b) World state distribution — large world snapshots shared P2P rather than server→each-client. (c) DLC/content pack distribution. Key advantage: scales with player count (more players = more seeds = faster). Key risk: NAT traversal, firewall issues, player trust (can you trust torrent-distributed assets?). Would need content verification (hash/signature) to prevent tampering.
• Cross-reference: Oscar (networking), multiplayer architecture, mod support

---

Q-073: BehaviourToolkit patterns for Rust NPC AI

• Status: Open (reference — implementation is server-side Rust)
• Question: BehaviourToolkit (https://github.com/ThePat02/BehaviourToolkit, https://godotengine.org/asset-library/asset/2333) — FSM, Behaviour Trees, Blackboard Resource, nested composition (BT inside FSM and vice versa). MIT. The plugin itself is GDScript/Godot and lives on the wrong side of D-020 for us. But the patterns are directly applicable to the Rust server NPC simulation: (a) Blackboard pattern — shared key-value state between behaviour nodes without coupling, maps to bevy_ecs components. (b) Nested FSM↔BT composition — our NPC state machines (schedule, mood, relationships, job per D-097) could nest behaviour trees for decision-making within each state. (c) Editor interface patterns — how they visualize/debug behaviour trees could inform our server-side tooling. Study the source for architectural patterns, implement in Rust/bevy_ecs.
• Cross-reference: D-097 (simulation tiers, 4 state machines), Dudley (server developer), NPC behaviour system

---

Q-074: Screenshot manager for in-game captures and bug reports

• Status: Open
• Question: Two references for improving the existing F12 bug reporter: (a) ScreenshotManager (https://github.com/ASecondGuy/ScreenshotManager) — better screenshot file management, auto-naming, viewport isolation. (b) BugReporter (https://github.com/ASecondGuy/BugReporter) — patterns for attaching system info, game state snapshots, reproduction steps to bug reports. Both from the same author. Evaluate what patterns we can adopt into our existing bug reporter flow.
• Cross-reference: /bug-report skill, character creator screenshot system

---

Q-075: RichText3D for in-world text rendering

• Status: Open
• Question: RichText3D (https://github.com/mszylkowski/rich-text-3d-godot) — renders BBCode to a 3D plane in real time. MIT, performant (renders only on property change, max once per frame). Supports color, bold, italic, images, tables, font size, auto text wrapping. Use cases: in-world signage (shop names, zone labels, directional signs), NPC name/title floating labels, item descriptions on crates/containers, news tickers on station displays, terminal screens. The adjustable resolution (pixels per Godot unit) means text stays readable at our isometric camera angles. Worth evaluating when diegetic UI and in-world text elements are implemented.
• Cross-reference: Diegetic UI design, in-world interaction system

---

Q-076: DeformableMesh for runtime environment and damage variation

• Status: Open
• Question: DeformableMesh (https://github.com/cloudofoz/godot-deformablemesh) — runtime mesh deformation with SphericalDeformer, SimpleDeformer (bend, twist, taper), and DragDeformer nodes. MIT, Godot 4.0+. Use cases: (a) environmental variety from shared meshes — same pipe asset bent differently per instance, twisted metal in damaged zones, wind-bent vegetation/trees. (b) Damage visualization — crushed containers, warped hull plating, dented surfaces. (c) Procedural variation at generator time — deform base assets to create unique instances without authoring each one. The DragDeformer could also serve interactive manipulation (bending objects during gameplay). Low priority but high variety-per-asset value.
• Cross-reference: Generator architecture, environment asset pipeline, damage system

---

Q-077: World generation architecture → PROMOTED TO WORKSHOP

• Status: Promoted — see docs/workshops/world-generation/BRIEF.md
• Question: Outgrew Q-record format. All references (CityCrafter3D, Chunk Manager, Retro Terrain, Spatial Gardener, GridMapLayer, PathMesh3D, DeformableMesh, Poly Haven) consolidated into the workshop brief.
• Cross-reference: docs/workshops/world-generation/BRIEF.md

---

Q-078: God rays for atmospheric lighting

• Status: Open
• Question: SimplestGodRay3D (https://github.com/AguaMineral/SimplestGodRay3D) — drop-in volumetric light shaft effect. Light streaming through station viewports, between buildings in exterior zones, through tree canopy in rural areas. Low implementation effort, high atmosphere value. Evaluate: does it work with our GL compatibility renderer? Performance cost per instance? Compatible with our toon shader aesthetic or does it look too realistic?
• Cross-reference: Lighting design, environment atmosphere

---

Q-079: GridMapLayer — 2D tile logic driving 3D grid rendering

• Status: Open (high relevance)
• Question: GridMapLayer (https://github.com/Caaz/grid-map-layer) — manages 3D GridMaps through TileMapLayer patterns. MIT, Godot 4.4+. Directly relevant: our server sends 2D tile grid data, the client renders 3D isometric. This plugin bridges that gap — autotiling for 3D tiles using 2D rules, arbitrary subdivisions (2x2+ gridmap tiles per 2D tile), multiple GridTiles per 2D tile (layered grids for collision variation), programmatic tile setting for procedurally generated areas. This could be the rendering layer for server-generated floor plans — the server sends the tile palette + grid, the client uses GridMapLayer with autotiling to render walls, floors, doors with correct 3D tile selection.
• Cross-reference: D-096 (chunk loading), tile rendering pipeline, server→client tile data

---

Q-080: Mod loader architecture reference

• Status: Open (reference — future feature)
• Question: Godot Mod Loader (https://github.com/GodotModding/godot-mod-loader) — community-standard mod loading framework for Godot. Study for architectural patterns: mod discovery and load ordering, dependency resolution between mods, conflict detection, API boundaries (what mods can and can't touch), mod manifest format, hot-reload vs startup-only loading, save compatibility with mods enabled/disabled. We'll roll our own but these patterns are battle-tested across many Godot projects. Key question for our architecture: mods need to work with both the Rust server (gameplay mods, new items, behaviours) AND the Godot client (visual mods, UI mods). The mod loader needs to span both sides of the D-020 boundary.
• Cross-reference: D-020 (client/server split), mod support, Q-072 (BitTorrent for mod distribution)

---

Q-081: VisionCone3D for client-side fog refinement

• Status: Open (high priority — solves the 2D→3D fog transition problem)
• Question: VisionCone3D (https://github.com/Tattomoosa/VisionCone3D) — 3D vision cone raycasting in Godot. MIT, Godot 4.4+. Proposed architecture: (a) Server does authoritative shadowcasting per D-011/D-015, sends visible chunk list in ObserverSnapshot (coarse grid truth). (b) Client uses VisionCone3D to re-trace locally against actual 3D wall geometry within the server-approved visible area. (c) The client's vision cone output drives 3D fog-of-war rendering with smooth, geometry-following edges instead of tile-stepped boundaries. This solves the stepped edge display issue from communicating visibility as grid chunks — the client refines to sub-tile accuracy using real 3D geometry. No information leak: client can only refine within server-approved visible chunks, never see beyond. The cone configuration mirrors the server's D-015 vision cone (forward/peripheral/blind spot zones). Performance tuning options available per the plugin docs.
• Cross-reference: D-011 (LOS shadowcasting), D-015 (vision cone), D-043–D-049 (fog system), fog_state.gd (current 2D fog implementation)

---

Q-082: VoronoiShatter for destruction effects

• Status: Open
• Question: VoronoiShatter (https://github.com/robertvaradan/voronoishatter) — procedural Voronoi fracture of 3D meshes into rigidbody pieces. MIT, Godot 4.4+, native GDScript. Convex and concave mesh support, seamless materials, auto rigidbody generation. Use cases: wall breaches during combat, crate/container destruction, station hull damage, environmental destruction. Pure client-side visual effect — server sends "object destroyed," client shatters the mesh locally. The Voronoi pattern gives natural-looking irregular fractures. Could pre-compute shatter patterns at load time for performance, trigger on damage event.
• Companion: Particle Scene Compositor (https://github.com/tvenclovas96/particle-scene-compositor) — spawn scene instances as particles. Destruction fragments + sparks/smoke/dust in one effect. Shatter → fragments fly → each fragment emits particles.
• Cross-reference: Combat system, damage visualization, environment interaction

---

Q-083: ThemeGen for dynamic insert styling and value-level theming

• Status: Open
• Question: ThemeGen (https://github.com/Inspiaaa/ThemeGen) — themes-as-GDScript-code with semantic colours, reusable styles, theme variations, and live preview in editor. MIT. Directly relevant to dynamic inserts: (a) Value-level theming — common/uncommon/rare items get different colour palettes from the same base layout. (b) Faction-themed inserts — Frost Compact cold blues, Reach Authority golds, derived programmatically from a base theme. (c) Danger/security level indicators — zone inserts shift colour based on threat level. (d) Player customisation — let players pick an insert accent colour, ThemeGen derives the full palette. The code-based approach means themes can be generated from server data (faction ID → theme variation) without authoring each one.
• Cross-reference: Diegetic UI / insert system, Stig (UI developer), Araminta (visual design)

---

Q-084: Isometric point-and-click navigation pattern

• Status: Open
• Question: Reference: isometric-2d-point-and-click-movement (https://github.com/Domogo/isometric-2d-point-and-click-movement). This is 2D but the interaction pattern applies to our 3D isometric setup: click ground tile → convert screen position to tile coordinate → server pathfinds (A* on tile grid) → client animates character along path. Key problems to solve: (a) mouse→3D isometric tile coordinate conversion (ray from camera through click point to ground plane, accounting for D-148 45° map rotation). (b) Path visualization (preview line showing where character will walk). (c) Click-to-move vs WASD — do we support both? (d) Server roundtrip latency — does the client predict movement or wait for server confirmation? Study for interaction patterns, implement in our 3D stack.
• Design notes: Character stays center-screen, map scrolls around them (not character moving on static map). Character always faces toward mouse cursor — this creates a natural looking-direction that drives the D-015 vision cone direction. Unresolved: what happens visually when walking one direction while looking backward (walk animation vs facing direction conflict — later solve). Latency: 200ms feels instant in web interactions (Jeroen's rule from web design) — if server roundtrip is under 200ms, click-to-move without client prediction may be acceptable. Needs user testing to verify.
• Cross-reference: D-148 (camera angle), D-010 (server authority), D-015 (vision cone facing), navigation/pathfinding

---

Q-085: Portal rendering for spatial transitions and viewports

• Status: Open
• Question: Portal concept — not the Godot plugin (client doesn't need it — transparency handles adjacent rooms, SubViewport handles remote camera feeds). The SERVER needs portal logic: when the shadowcasting/vision cone hits a door opening, visibility extends through it into the next room. Portals are openings in the tile grid that allow raycasts to pass between rooms/zones. Study the plugin (https://github.com/VojtaStruhar/godot-portals-plugin) for the spatial math patterns, implement in Rust server's visibility system. Key: doors open = portal active = vision extends through. Doors closed = wall = vision blocked.
• Cross-reference: D-011 (LOS), D-015 (vision cone), z-level system, information boundary design

---

Q-086: Day/night cycle — server time driving client lighting

• Status: Open
• Question: Reference: DynamicDayNightCycles (https://github.com/eisclimber/DynamicDayNightCycles). The game time is server-authoritative — server ticks time, sends current time-of-day in ObserverSnapshot. Client renders lighting accordingly. Station interiors: artificial lighting follows schedules (dim at night cycle, full during work shifts). Exterior/rural zones: sun position, sky color, shadow direction from time of day. Station viewports could show star position shifting. NPC schedules already tied to time (D-097 schedule state machine). Key question: how granular is the lighting transition — smooth real-time interpolation or discrete time blocks (morning/afternoon/evening/night)?
• Cross-reference: D-097 (NPC schedules), environment lighting, server game clock

---

Q-087: Water shader for environment zones

• Status: Open
• Question: Godot Realistic Water (https://github.com/godot-extended-libraries/godot-realistic-water) — water rendering with reflections, refraction, waves. May be too realistic for our toon aesthetic — evaluate whether it can be styled down or if a simpler toon water shader is better. Use cases: docking bay water features, hydroponic farms, waste processing, rural rivers/lakes, rain puddles, port zones, fountains. Question: does toon water need reflections or just stylized wave animation + color? The Retro Terrain reference (Q-077) already handles water tile transitions — this adds the surface rendering. Also check if GL compatibility renderer supports the shader features.
• Cross-reference: Q-077 (world generation / terrain), environment aesthetics, GL compatibility renderer

---

Q-088: Spatial audio for information-aware sound

• Status: Open
• Question: spatial_audio_player_3d (https://github.com/Danikakes/spatial_audio_player_3d) — 3D spatial audio with occlusion and environmental awareness. Directly tied to the information system: sound carries information. Footsteps through walls = muffled (you know someone's there but not who). Conversation in the next room = faint/unintelligible (partial information). Gunshot echoes in corridors = direction cues. The server already knows which audio events are in hearing range (part of the ObserverSnapshot). The client needs spatial rendering: distance attenuation, wall occlusion, reverb based on room size/material. Also ties into Inigo's audio design specs. Evaluate whether this plugin handles occlusion raycasting or just basic 3D positioning.
• Cross-reference: D-011 (LOS — audio equivalent), Inigo (sound designer), information boundary, audio propagation rules

---

Q-089: Procedural star rendering for space viewports and star map

• Status: Open
• Question: Godot Starlight (https://github.com/tiffany352/godot-starlight) — procedural starfield rendering. Use cases: (a) Station viewport backgrounds — look out a window, see stars. (b) Star map navigation screen. (c) Docking bay exterior views. (d) Skybox for any exterior/surface zone. Could combine with Q-064 (planet generator) for full space vista — procedural stars + procedural planets visible from station viewports. Seed from system coordinates for consistent views per location.
• Cross-reference: Q-064 (planet generator), station viewport design, star map UI

---

Q-090: Markov chains for procedural name/text generation in Rust

• Status: Open
• Question: Pattern reference: Markov Machine (https://github.com/BirDt/markov-machine) — Markov chain text generation. Need a Rust crate, not the Godot plugin. Candidates to evaluate: markov crate, markov_chain crate, or hand-roll (Markov chains are ~50 lines of Rust). Use cases: NPC name generation from cultural name pools (train on corridor-specific names, generate plausible new ones), shop/business name generation, procedural signage text, news ticker filler, overheard conversation snippets. Faster and cheaper than LLM for short text that just needs to feel culturally consistent. Could train separate chains per corridor/culture for regional flavor. The existing voice pipeline (Gemma 2) handles dialogue variation — Markov is for the lightweight procedural text that doesn't need semantic coherence.
• Cross-reference: Generator architecture, name pools, voice pipeline (server/src/voice/)

---

Q-091: Event-driven audio system

• Status: Open
• Question: Event Audio (https://github.com/bbbscarter/event-audio-godot) — data-driven event→sound mapping. Game events trigger audio without hardcoded play() calls. Complements Q-088 (spatial audio handles WHERE, this handles WHEN/WHAT). Server sends game events in ObserverSnapshot (door opened, NPC entered, combat started), client maps these to audio via configuration. Inigo's audio design specs define the sound palette — this system is the dispatcher that connects game events to that palette. Evaluate whether we adopt the plugin pattern or build our own event→audio bus.
• Cross-reference: Q-088 (spatial audio), Q-063 (footsteps), Inigo (sound designer), AudioManager autoload

---

Q-092: Modular settings menu as foundation for #735

• Status: Open
• Question: Godot Modular Settings Menu (https://github.com/MarkVelez/godot-modular-settings-menu) — composable settings panels for keybinds, audio, video, accessibility. Evaluate as the foundation for epic #735 (Settings and input system). Instead of building keybind remapper, audio sliders, resolution picker, and controller support from scratch, start from this template and restyle to match our UI aesthetic. Key: the modular approach means we can add/remove panels as features are implemented without restructuring.
• Cross-reference: Epic #735 (settings/input system), Frame0 wireframe session

---

Q-093: Tile-based exploration map in player insert (Google Maps for the implant)

• Status: Open (high interest)
• Question: Reference: MapTileProvider (https://github.com/AngryMeenky/MapTileProvider) — lazy-loading tile map provider. Concept: the player's insert has a map that works like Google Maps — pan, zoom, tile-based rendering. Server generates map tiles from ECS exploration data (what the player has seen). Explored areas show room layouts, corridors, points of interest. Unexplored areas are blank/fogged. Zoom levels: room detail → building → district → zone → station overview. Knowledge-graph-driven overlays: NPC last-known positions (if the player tracked them), quest markers, danger zones, faction territories. Map tiles are server-authoritative (can't see what you haven't explored) and cached on the client. The tile pyramid approach means the map scales to any world size without loading everything at once.
• Cross-reference: Information boundary (D-011), insert/minimap UI, knowledge graph (D-041), #732 (minimap ticket)

---

Q-094: Chart widgets for economy/market insert UI

• Status: Resolved — deferred to Phase 3+ (player interaction layer)
• Date resolved: 2026-04-05
• Resolution: No player-facing economic UI is in scope for Phase 2. The Phase 2 deliverable is the autonomous simulation ticking on investor screens — no player verbs, no insert UI for market data. Chart widget evaluation (Easy Charts plugin, ThemeGen integration, information boundary application) deferred until Phase 3 when the player interaction layer begins.
• Question: Easy Charts (https://github.com/fenix-hub/godot-engine.easy-charts) — line charts, bar charts, scatter plots, pie charts in Godot. For the insert UI: (a) commodity price history graphs (X4/EVE-style market view), (b) faction reputation trends over time, (c) supply/demand curves per station, (d) character stat progression, (e) economy health indicators. The diegetic justification: the player's implant has market analytics. Data comes from server via ObserverSnapshot (the player only sees market data they have access to — information boundary applies). Evaluate whether this plugin's visual style can be themed to match our insert aesthetic (ThemeGen Q-083 integration).
• Cross-reference: Economy system (X4/EVE inspiration), insert UI, Q-083 (ThemeGen), information boundary, D-181 (signal vocabulary — Phase 3 player access)

---

Q-098: Persistence of generated river/city mapping outputs

• Status: Resolved — D-225 (atlas layer-stream proxy), 2026-05-23
• Resolution: Resolved against the question's own premise. The viewer does not need a durable store under the LRU: the cascade is deterministic and ~45 ms, so eviction → recompute is acceptable. Baking into systems.db (option a) is rejected — it bloats the install and makes modded bodies second-class. Decision: lazy compute on demand, served by a mod-first layer-stream proxy that resolves a body's source files (base + mod dirs) and streams the computed Layer1Output over the existing IPC bridge, backed by the D-203 in-memory LRU (miss → background AnalyzeBody; eviction → recompute). See D-225. The mod-content-catalog corner (mods adding new body rows / terrain_reference to the binary systems.db) is spun off to Q-099.
• Question: The deterministic cascade can recompute river courses (D8 drainage, D-208) and city placements (economic sim + attractor matching, D-211) from seed at any time, so persisting them is a cost optimization, not a correctness need. But the compute is expensive — recomputing per session or per atlas view is waste. How are these mapping outputs persisted so they are computed once per body and kept? D-203's BodyWorldState cache is an LRU — it evicts (volatile). The fork: (a) build-time bake into systems.db (D-200 build-time tier — precompute all, ship); (b) lazy compute + persist at runtime (cache DB / savegame — compute on first visit, keep); (c) hybrid. Whatever the answer, the in-memory LRU should sit over a durable store so eviction triggers a cheap reload, not a recompute.
• Context: Raised 2026-05-22 looking ahead from the Phase 4 markers strip (#951). Refines D-200 (three-tier execution) and D-203 (LRU cache). Gates the Atlas layer viewer (#960), which needs persisted mapping to render without recomputing. Determinism (#952) guarantees recompute is always a valid fallback.
• Cross-reference: D-200, D-203, D-208, D-211, #952 (determinism harness), #960 (atlas viewer)

---

Q-099: Mod content catalog — body rows / terrain_reference overlay for systems.db

• Status: Open — spun off from D-225 (2026-05-23)
• Question: D-225 resolves mod file resolution (a mod body's source heightmap.png is found by searching mod dirs over the base install). But a mod adding a new body also needs that body discoverable: the bodies row and its terrain_reference live in systems.db, which is binary and source-canonical (D-189) — mods cannot append to it. How does a mod register new bodies (and other DB-resident catalog rows)? Options: a mod manifest the server merges into an in-memory catalog overlay at load; a parallel mod catalog DB layered over the systems.db reads; or a documented mod build step. Out of scope for #960 (base-install resolution ships the viewer); needed before third-party bodies are first-class.
• Context: Raised 2026-05-23 from the D-225 mod-first layer-stream proxy design. The proxy makes first-party and mod bodies flow through an identical resolve→compute→stream path given a resolvable source file; this question is the remaining gap — getting a mod's new body into the catalog the resolver consults.
• Cross-reference: D-225, D-189 (systems.db source-canonical), #960 (atlas viewer — base-install only for now)

---

Q-100: Biome authority — Python sim vs Rust cascade

• Status: Resolved in principle (Jeroen, 2026-05-25) — implementation detail open. The baked heightmap + reliefmap are deterministic inputs (gameplay never touches them), so the natural world is f(reliefmap, heightmap, seed) and the cascade derives from the baked artifacts, never independently re-derives. The biome/climate the reliefmap encodes is therefore baked as data the Rust cascade reads (option A below); subbiome::classify's independent re-derivation is reconciled away. Open: exactly which data layers to bake + the Rust read path.
• Question: Two independent biome systems exist. planet_simulation.py (build-time) computes biome from a Whittaker table + sim-derived temperature/moisture and colours reliefmap.png — the authoritative visual. subbiome::classify (Rust, runtime, D-210) re-derives SubBiomeVariant from proxies (elevation percentile, slope, river-distance moisture, latitude temperature). They diverge — a cold fjord coast reads CoastalLowland in Rust, which lacks the temperature field. Which is canonical? (A) Python canonical → bake temperature + moisture as additional atlas layers the Rust cascade reads (richer; more storage/pipeline; mod-friendly per D-225); (B) Rust canonical → re-render reliefmaps from cascade output at bake time (simpler; loses the atmospheric sim; regenerates ~267 reliefmaps); (C) keep split (pragmatic; contradicts the dual-artifact principle, D-226). Related sub-fork: the Python river-carve (colours the reliefmap) and the Rust D8 network (D-208) also diverge — the dual artifact requires reconciling them.
• Context: Tyre's top integration snag. Blocks the biome axis of D-228 and the dual-artifact reconciliation. Tyre's lean: A long-term, B for Phase 4, with the expansion path designed in.
• Cross-reference: D-228, D-226, D-210, D-208, D-225, tooling/planet-gen/planet_simulation.py, server/src/atlas/subbiome.rs

---

Q-101: Refinement / derivation contract — coarse hint → fine geometry + morphology algorithm family

• Status: Open — the atlas-derivation workshop's primary technical output, not yet specified (2026-05-25)
• Question: How does a coarse, map-scale hint (a ~78 km Layer-1 cell) plus a seed become fine, ~1 m-voxel coherent geometry — deterministically, without squaring — across ~3 scale jumps (78 km cell → ~1 km region → 64 m chunk → 1 m voxel)? Needs: the inter-layer hint+seed→geometry API (Tyre sketched a RegionHint); a context-driven morphology algorithm family selected by local context (rivers meander in lowlands / incise in mountains; coasts dune / crag / fjord by slope + lithology + glaciation), ≥6 distinct generators (meander, incised gorge, braided delta, dune strand, cliff coast, fjord, mountain pass); integer-only structural decisions (D-010), f64 confined to within-voxel interpolation; clean transitions between adjacent morphology families. Unowned dependency: the ocean/lake mask — D-223 stripped the markers.json polygons that D-209 CoastalAccess/LakeShore extraction referenced, so the mask must instead be derived from the heightmap sea-level threshold or a baked water-bodies layer. Lithology is a required input (promoted load-bearing by the volumetric subsurface, D-227). Also in scope: body-class parameters (hydrosphere, tectonic activity, atmosphere) must modulate river-network density — the effective river threshold — so an arid body and an oceanic body differ in how many rivers, not just where they run (today RIVER_THRESHOLD is a global constant, Nigel); and river flow direction (upstream/downstream — gates effort vs speed, and feeds the seasonal water model) derives from the D8 network at query time.
• Context: The heart of the atlas→tile derivation; surfaces as the cascade builds the region → chunk → voxel layers.
• Cross-reference: D-227, D-228, D-208, D-209, D-223, D-010, D-222

---

Q-102: Cohesion-matrix algorithm — seam-free continuous variation

• Status: Open — deferred from D-228 (2026-05-25)
• Question: D-228 mandates that intra-region material / sub-biome scatter come from a global, position-keyed continuous noise field so chunk/region boundaries never read as grid seams, while authored straight lines (roads, plazas) stay crisp. Concretely: the noise basis (value / Perlin / simplex / worley); keying on world position (not chunk index) to stay continuous across boundaries; how material / sub-biome thresholds map onto it; integer-only / determinism (D-010); and how authored linear features composite over the continuous field without bleeding.
• Context: The anti-squaring principle pushed down to the material layer.
• Cross-reference: D-228, D-227, D-010

---

Q-103: Tile-mutator op schema

• Status: Open — deferred from D-227 (2026-05-25)
• Question: D-227 makes tile mutators the sole persisted state (save = seed + mutator log). What does one mutator record — a full per-voxel override, or typed ops (Dig, Build(FloorMaterial), Place(object), Destroy(object), SetMaterial)? Typed ops are compact, semantic, replayable, but need a fixed op vocabulary; full overrides are simple but heavier and lose intent. Also: replay ordering / conflict semantics, and confirmation that a position-keyed mutator stays valid across re-derivation (determinism guarantees an identical base — to be pinned).
• Context: Needed when the save system is built (Phase 5+).
• Cross-reference: D-227, D-010

---

Q-104: Floor-index ↔ absolute voxel-z coordinate mapping

• Status: Resolved 2026-05-25 by D-229
• Resolution: Resolved via FloorExtent { base_floor, floor_count, FloorHeightProfile::{Uniform|Variable} } + the pure functions floor_at_voxel_z / voxel_range_for_floor.
• Question: D-227 introduces an absolute physical z coordinate (metres, continuous over the voxel grid) alongside D-110's floor-index addressing (base_z: i8, a story-counting integer). The two coexist but the bridge is undefined: "the floor at base_z = -2" → which absolute voxel-z values does it span? With variable-height floors (D-227 — default 3 voxels, a cathedral ~10), the mapping is non-linear (a floor's voxel-z depends on the heights of the floors below it). What is the mapping function, and where is it owned (a per-building floor table? a region floor-height index?)? Needed before anything queries both systems (Phase 5 building interiors / vertical movement). Gap, not contradiction — D-227 and D-110 do not conflict.
• Context: Raised in the atlas-derivation workshop (Tyre, Round 2 review of D-227).
• Cross-reference: D-227, D-110, D-049, D-222

---

Q-105: Region seasonal/clock state — the shared cheap-dynamism source

• Status: Open — committed in principle (D-228); model details open (2026-05-25)
• Question: D-228 commits to a deliberately cheap, deterministic, region-level seasonal/clock state — computed once per region per phase, inherited by its tiles — from which a family of transient surface conditions derive — all computed from the region's seasonal + tidal + weather phase, none of it stored: flooded tiles (floodplain / tidal-flat / seasonal-river, where the water-height crosses local elevation), snow & ice cover, puddles (weather / rain), weather generally, and the farmland crop cycle (sown → growing → ripe → harvested → fallow). The model must stay "nearly free" — simple deterministic functions of the in-game clock + body/region parameters, no per-tile or per-frame simulation. Open: the exact phase functions — a seasonal term phased by hemisphere (latitude sign), driven by the year clock; a tidal term only when the body has a moon (no satellite → no tide), driven by the lunar/day clock with amplitude from the satellite config; a weather term (shorter-term precipitation → puddles + general conditions); how snow/ice depth, puddles, flood extent, weather, and the crop cycle each read the same state; the snow/ice cover model — D-228 removed Snow/Ice from TerrainMaterial, so snow/ice are entirely this seasonal cover overlay (permanent only where climate never melts them — poles, glaciers), depth rising/falling with the seasonal phase; determinism (state = f(clock, region) → reproducible) and its interaction with the cache + the D-226 pause/inspection (a frozen phase for stable inspection); and recompute cadence (per phase-change, not per frame).
• Context: Grew from the floodplain dependency — "floodplain is only feasible if water heights move" — into a general cheap-dynamism source. Jeroen's constraints: clock + hemisphere bound, moon-gated tides, computed once per region, simple rules; snow / weather / crop cycle ride the same calculation.
• Cross-reference: D-228, D-227, D-226 (dynamic-state inspection), D-010

---

Q-106: Era-band stacking depth for layered architecture-flavor

• Status: Resolved 2026-05-25 by D-232 (round 3) — the question is dissolved, not answered.
• Question (original): D-232 (round-2 draft) made flavor a three-layer resolution (body × district × era-band). How many era-bands does a settlement produce as a function of founding_age_years? What is the minimum age-gap between bands? How do the flavor slices differ between bands?
• Resolution: The round-3 rewrite of D-232 retired the era-band material-progression entirely. The Reach is post-space-travel throughout — there is no stone→concrete→glass tech ladder, so era is not a flavor-stacking axis. A block's construction era (still derived from distance-to-founding-origin, D-229) reads as maintenance/wear through the condition layer (D-217/D-198); the occasional out-of-vogue building is handled by D-232's deviation system (the "past-vogue holdover" — temporal sibling of the spatial swerve), not by multi-band flavor stacking. So there are no era-bands to count.
• Cross-reference: D-232, D-229, D-217/D-198 (condition — where era's wear lands)

---

Q-107: Wiki → Atlas content-set consolidation

• Status: Open — raised by Jeroen (2026-05-25)
• Question: The wiki pages live semi-outside game scope yet are piped into Atlas content screens AND are now a generator input (D-232 architecture-flavor distilled from wiki prose). Where authored per-body content lives (frontmatter vs companion file vs a consolidated tree) should follow a consolidation of ALL wiki content — pages + heightmaps + markers + architecture-flavor — into one first-class, baked Atlas content set (the "move it into a gamedata/ subtree" instinct), not a per-feature hack. The generator-facing tables (trait_templates + atlas_body_trait_bias, D-232) are invariant to the source location, so this does not block the fill seam.
• Cross-reference: D-232, D-223, D-191 (Atlas/settlement), and the development cascade (Phase 1 wiki + Phase 3 Atlas)

---

56 questions (11 resolved, 1 partially resolved, 44 open). Last updated: 2026-05-25.