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: Open
• 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?
• 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: ScreenshotManager (https://github.com/ASecondGuy/ScreenshotManager) — evaluate for improving the existing F12 bug reporter's screenshot capture. We already have F12 screenshot + bug report in-game. This plugin could improve it: better file management, auto-naming, viewport isolation, gallery/history. Evaluate what patterns we can adopt into the 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: CityCrafter3D — procedural city/settlement generation

• Status: Open (high interest)
• Question: CityCrafter3D (https://github.com/immaculate-lift-studio/CityCrafter3D) — procedural 3D city generation in Godot. The generation logic needs to be in Rust (server-side, D-020), but the patterns are highly relevant: road network generation, building placement rules, district zoning, lot subdivision, procedural layout algorithms. Study as a reference implementation for our Rust-side location generator. Key questions: what algorithms does it use (wave function collapse, L-systems, grid subdivision)? How does it handle building variety from limited asset sets? What's the data model for a generated city — can we extract the layout representation and replicate it in Rust with the client rendering from server-sent layout data?
• Cross-reference: Generator architecture, D-096 (chunk loading), D-097 (simulation tiers), location generation

---

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)

---

32 questions (7 resolved, 1 partially resolved, 24 open). Last updated: 2026-03-23.