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

docs(workshops): add 5 architecture spike workshop briefs

Browse Source 
Workshop briefs for the larger spikes identified by the architecture
review audit: knowledge graph & information boundaries, observer
snapshot pipeline, NPC AI state machines, save/load architecture,
and map authoring pipeline. Each includes participants, key questions,
input documents, and expected outputs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-11 21:36:02 +01:00
co-authored by Claude Opus 4.6
parent e1a3913060
commit 1920f002a1
6 changed files with 380 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workshops/README.md
+6
View File
@@ -19,3 +19,9 @@ docs/workshops/
|----------|-------|--------|
| [Content Architecture](content-architecture/) | 17 | Complete |
| [v0.1 Gap Analysis](v01-gap-analysis/) | 18 | Complete |
| [Content Gap Analysis v0.1](content-gap-analysis_v0_1/) | — | Complete |
| [Knowledge Graph & Information Boundaries](knowledge-graph-information-boundaries/) | — | Brief ready |
| [Observer Snapshot Pipeline](observer-snapshot-pipeline/) | — | Brief ready (blocked by Knowledge Graph) |
| [NPC AI State Machines](npc-ai-state-machines/) | — | Brief ready |
| [Save/Load Architecture](save-load-architecture/) | — | Brief ready |
| [Map Authoring Pipeline](map-authoring-pipeline/) | — | Brief ready |
docs/workshops/knowledge-graph-information-boundaries/workshop-brief.md
+71
View File
@@ -0,0 +1,71 @@
# Knowledge Graph & Information Boundaries Workshop Brief
**Goal:** Design the knowledge data structure that replaces `InformationInventory { known_facts: Vec<String> }` — the pillar-1 mechanic foundation for asymmetric information.
**Ticket:** #351 (epic)
**Priority:** CRITICAL — Sprint 2 blocker
**Participants:** Tyre (architecture lead), Gestalt (mechanics), Paula (narrative), Dudley (implementation), Qatux (docs), Si (tickets)
**Source:** Architecture Review Audit 2026-02-11, Consensus Recommendation #12
## Context
The architecture audit independently identified the knowledge graph as the **most important and least specified critical system**. Both Tyre and Troblum rated it CRITICAL.
D-010 principle 2 says: "every piece of game state is tagged with who knows it." The current implementation in `server/src/npc/mod.rs` has `InformationInventory { known_facts: Vec<String> }` — a placeholder that cannot support observation, monologue, dialogue, or success criteria.
This system is load-bearing for:
- D-010: Multiplayer-ready information boundaries
- D-011: Fog of perception (what returns when you leave)
- D-017: Perception modes (what different modes reveal)
- D-028: Tagged line pools (access-tier dialogue)
- D-033: Entity color from relationship state
- Q-016: Knowledge hierarchy (`suspects` < `knows_of` < `knows_details`)
## Key Questions to Resolve
### Data Structure
1. What does "entity A knows about entity B" look like as a Rust struct?
2. How is knowledge confidence tracked? (Q-016: hierarchy levels)
3. How does knowledge decay over time? (D-011: "fog returns when you leave")
4. How are non-entity facts tracked? (locations, events, relationships between others)
### Knowledge Flow
5. How does knowledge enter the graph? (Direct observation, told by NPC, inferred)
6. How does the `KnowledgeSource` affect confidence?
7. Can knowledge be wrong? (Misinformation, outdated information)
8. How do NPCs share knowledge with each other? (Gossip, reports, investigations)
### Performance
9. At 80 Active NPCs, each knowing about ~50 entities, what's the memory budget?
10. How is the knowledge graph queried efficiently for observer snapshot generation?
11. Does knowledge graph update need spatial partitioning? (Only update knowledge for nearby entities)
### Game Mechanics Integration
12. How does the knowledge graph drive monologue triggers? (D-019, tickets #119-122)
13. How does knowledge state affect dialogue access tiers? (D-028)
14. How do social triangles interact with knowledge? (Does knowing about a triangle change behavior?)
## Input Documents
| Document | What to read | Why |
|----------|-------------|-----|
| `decisions/perception.md` | D-011, D-015-D-019 | Perception system requirements |
| `decisions/architecture.md` | D-010 (principles), D-024 (NPC model), D-026 (simulation tiers) | Architecture constraints |
| `decisions/content.md` | D-028 (tagged line pools), D-033 (entity color) | Content system dependencies |
| `decisions/questions.md` | Q-016 (knowledge hierarchy), Q-017 (triangle pressure) | Open questions this workshop should resolve |
| `server/src/npc/mod.rs` | Current NPC component model | What exists today |
| `server/src/perception/mod.rs` | Perception plugin stub | Where this code will live |
| `docs/audits/architecture-review-2026-02-11.md` | Tyre R-01, Troblum section 4 | Detailed analysis and proposals |
## Expected Outputs
1. **Decision: D-0XX — Knowledge Graph Data Model** — Rust struct definitions for `KnowledgeGraph`, `EntityKnowledge`, `KnowledgeConfidence`, `KnowledgeSource`
2. **Decision: Resolution of Q-016** — Knowledge hierarchy levels with concrete enum values
3. **Design document:** Knowledge flow specification (how knowledge enters, propagates, decays)
4. **Tickets:** Implementation tasks broken down from the design
5. **Performance budget:** Memory and query time targets at 80 NPCs
## Workshop Format
Two rounds, following project convention:
- **Round 1:** Each participant independently analyzes the questions from their domain perspective
- **Round 2:** Cross-review, debate, and synthesis into concrete decisions
docs/workshops/map-authoring-pipeline/workshop-brief.md
+75
View File
@@ -0,0 +1,75 @@
# Map Authoring Pipeline Workshop Brief
**Goal:** Define how v0.1 maps (5-8 hand-crafted buildings per world, 150x150 tiles, 2-3 z-levels) are authored, stored, and loaded by both server and client.
**Ticket:** #355 (epic)
**Priority:** MEDIUM — Sprint 2-3 target
**Participants:** Tyre (architecture lead), Stig (client rendering), Araminta (visual design), Dudley (server loading), Qatux (docs), Si (tickets)
**Source:** Architecture Review Audit 2026-02-11, Tyre R-09
## Context
D-014 specifies 3 worlds with ~150x150 tile maps, 2-3 z-levels, and 5-8 hand-crafted buildings per world. The chunk-based `WalkabilityMap` exists (`server/src/simulation/movement.rs`) for collision, but there is no:
- Tile type system (floor, wall, door, furniture, etc.)
- Visual tile data (what the client renders)
- Map authoring tool or format
- Map loading pipeline for either server or client
The audit recommends **Tiled editor** (mature, cross-platform, JSON export) but this needs validation against the project's specific requirements (z-levels, entity spawn points, per-tile metadata like walkability and LOS blocking).
## Key Questions to Resolve
### Authoring Tool
1. Tiled vs Godot TileMap editor vs hand-authored YAML/JSON? (Audit recommends Tiled)
2. If Tiled: which export format? (JSON, TMX/XML, CSV?)
3. How are buildings authored separately and placed into the world map?
4. How are z-levels represented? (Separate layers? Separate files? Tiled group layers?)
### Tile Data Model
5. What tile types exist? (floor, wall, wall_half, door, window, furniture, decoration?)
6. What per-tile metadata is needed? (walkable, blocks_los, blocks_sound, interaction_type?)
7. How do tiles map to the WalkabilityMap? (Direct 1:1? Computed from tile properties?)
8. How are tile visuals defined? (Sprite atlas indices? Named references? Autotile rules?)
### Map Format
9. What's the canonical map format the server loads? (Tiled JSON? Custom binary? TOML?)
10. Does the client load the same format or a different one? (Server = collision/logic, client = visual)
11. How are entity spawn points defined in the map? (NPC start positions, item placements)
12. How are social sites (D-025) tagged in the map? (Zone markers, named regions)
### Loading Pipeline
13. How does the server load maps into the chunk-based system?
14. How does the client load maps into TileMapLayer nodes?
15. Is hot-reload supported for iteration? (Edit map, reload in running game)
16. How are map assets versioned? (Save files reference map version?)
### Visual Design
17. What is the tile size? (16x16, 32x32, 64x64?)
18. How does the v0.1 visual grammar (D-003, v0.1 placeholder art) apply to tiles?
19. How do zone-specific color palettes (per Araminta's visual grammar) affect tile rendering?
20. How does fog overlay interact with the tile layers? (Audit recommends TileMapLayer for fog)
## Input Documents
| Document | What to read | Why |
|----------|-------------|-----|
| `decisions/scope.md` | D-012 (chunks), D-014 (map spec) | Map requirements |
| `decisions/scope.md` | D-025 (social site templates) | Location definitions |
| `server/src/simulation/movement.rs` | WalkabilityMap, chunk system | Existing server-side map code |
| `client/scenes/main.tscn` | Current scene structure | Where tilemap nodes go |
| `client/scripts/rendering/world_renderer.gd` | World rendering stub | Client rendering entry point |
| Spatial layout tickets (#311-313) | Bar, logistics hub, smuggling spaces | Specific buildings to author |
## Expected Outputs
1. **Decision: D-0XX — Map Authoring Pipeline** — Tool choice, format, loading pipeline
2. **Tile type specification:** Enum of tile types with properties (walkable, blocks_los, etc.)
3. **Map format schema:** Documentation of the canonical format both sides load
4. **Authoring guide:** How to create a new building/location using the chosen tool
5. **Tickets:** Implementation tasks (server loader, client loader, tile type system, first test map)
6. **Proof of concept:** One building loaded and rendered in both server and client
## Workshop Format
Two rounds:
- **Round 1:** Each participant analyzes from their domain (Tyre: format/loading, Stig: client rendering, Araminta: visual requirements, Dudley: server integration)
- **Round 2:** Cross-review, tool evaluation, finalize pipeline
docs/workshops/npc-ai-state-machines/workshop-brief.md
+77
View File
@@ -0,0 +1,77 @@
# NPC AI State Machines Workshop Brief
**Goal:** Specify the 4 Background-tier state machines (schedule, mood, relationships, job) — states, transitions, day phase integration, and tick budgets.
**Ticket:** #353 (epic)
**Priority:** HIGH — Sprint 3 target
**Participants:** Gestalt (mechanics lead), Paula (narrative), Dudley (implementation), Tyre (architecture), Nigel (emergent play), Qatux (docs), Si (tickets)
**Source:** Architecture Review Audit 2026-02-11, Tyre R-06
## Context
D-026 defines four simulation tiers. Background-tier NPCs (500-2,000) run "state machine ticks" at 1/game-minute frequency. D-026 mentions "4 state machines: schedule, mood, relationships, job" but provides no specification of states, transitions, or interactions.
The NPC component model (D-024, `server/src/npc/mod.rs`) defines 10 axes including `DailyRoutine`, `MoodState`, `RelationshipWeb`, and `Occupation` — but these are type stubs without behavior logic.
This workshop must produce state machine specifications that are:
- **Implementable** — Clear states and transition rules Dudley can code
- **Interesting** — State interactions that produce emergent NPC behavior (Gestalt, Nigel)
- **Narratively grounded** — State changes that create observable drama (Paula)
- **Performant** — Within the 1/game-minute update budget for 500+ NPCs (Tyre)
## Key Questions to Resolve
### Schedule FSM
1. What are the schedule states? (work, home, social, sleep, commute, errand?)
2. How do day phases (D-031: morning, afternoon, evening, night) drive transitions?
3. How do schedules vary by NPC type? (worker, socialite, loner, authority figure)
4. What makes an NPC deviate from their routine? (Events, mood, relationship pressure)
### Mood FSM
5. What are the mood states? (calm, stressed, suspicious, friendly, hostile, afraid?)
6. What events trigger mood transitions? (Observation, confrontation, social pressure)
7. How does mood affect schedule? (Stressed NPC skips social time? Suspicious NPC changes route?)
8. How does mood affect dialogue access? (D-028 tag system integration)
### Relationship FSM
9. What are the relationship states? (stranger, acquaintance, friend, ally, rival, enemy?)
10. How do relationships change? (Repeated interaction, shared knowledge, betrayal, trust)
11. How do social triangles (D-024) create relationship pressure?
12. How does Q-017 (triangle pressure threshold) feed into relationship transitions?
### Job FSM
13. What are the job states? (idle, working, break, commute, off-duty?)
14. How does job interact with schedule? (Job state constrains schedule options)
15. How do different occupations (dock worker, security, merchant, bureaucrat) vary?
16. How does job state affect what the NPC knows? (Location access, information exposure)
### Cross-Machine Interactions
17. How do the 4 machines communicate? (Shared blackboard? Event bus? Direct reads?)
18. What's the priority when machines conflict? (Mood says "flee" but schedule says "work")
19. How do Active-tier NPCs differ from Background-tier? (Full AI vs state machine only)
20. How does tier transition preserve state? (Active NPC drops to Background — which state is kept?)
## Input Documents
| Document | What to read | Why |
|----------|-------------|-----|
| `decisions/architecture.md` | D-026 (simulation tiers), D-031 (time/day phases) | Tier and timing constraints |
| `decisions/scope.md` | D-024 (NPC model), D-025 (social sites) | NPC components and locations |
| `decisions/content.md` | D-028 (tagged line pools), D-034 (THE FRIEND) | Content dependencies |
| `decisions/questions.md` | Q-016, Q-017 | Open questions about knowledge hierarchy and triangle pressure |
| `server/src/npc/mod.rs` | Current component stubs | What exists today |
| `server/src/simulation/tier.rs` | Tier system stub | Where tier logic lives |
## Expected Outputs
1. **Decision: D-0XX — NPC State Machine Specification** — States, transitions, and interaction rules for all 4 machines
2. **Decision: Resolution of Q-017** — Triangle pressure threshold mechanics
3. **State diagram:** Visual state machines for each FSM (can be Mermaid diagrams)
4. **Transition tables:** For each FSM, a table of (current_state, event) -> new_state
5. **Performance budget:** Per-NPC update cost at Background tier frequency
6. **Tickets:** Implementation tasks for each FSM + cross-machine integration
## Workshop Format
Two rounds:
- **Round 1:** Each participant designs the machines from their domain (Gestalt: mechanics, Paula: narrative weight, Nigel: emergent play, Tyre: performance, Dudley: implementation feasibility)
- **Round 2:** Cross-review and reconcile — especially where mechanics vs narrative vs performance conflict
docs/workshops/observer-snapshot-pipeline/workshop-brief.md
+80
View File
@@ -0,0 +1,80 @@
# Observer Snapshot Generation Pipeline Workshop Brief
**Goal:** Design the algorithm for "what does entity X perceive this tick?" — the server-side pipeline that computes ObserverSnapshot from world state.
**Ticket:** #352 (epic, blocked by #351)
**Priority:** CRITICAL — Sprint 2 blocker
**Participants:** Tyre (architecture lead), Dudley (implementation), Troblum (algorithm review), Qatux (docs), Si (tickets)
**Source:** Architecture Review Audit 2026-02-11, Consensus Recommendation #13
**Dependency:** Workshop 1 (Knowledge Graph) must complete first — this pipeline consumes the knowledge graph.
## Context
Both audit reviewers independently flagged the observer snapshot pipeline as CRITICAL and unspecified. The `ObserverSnapshot` wire type exists (`server/src/bridge/types.rs`) but the algorithm that populates it does not.
This pipeline IS the game loop from the client's perspective. Every tick, the server must:
1. Determine what the observer can see (spatial + LOS)
2. Determine what the observer can hear (sound propagation)
3. Filter visible state through the observer's knowledge graph
4. Assemble the snapshot for transmission
The pipeline must run within the 100ms tick budget at 80 Active NPCs (D-026).
## Key Questions to Resolve
### Pipeline Stages
1. What are the exact stages? (spatial query → LOS → sound → knowledge filter → assembly?)
2. Which stages can be parallelized? (bevy_ecs system parallelism)
3. What order do stages run in the bevy_ecs schedule?
### Spatial Query
4. How does the spatial index (ticket #340, SpatialIndex trait) feed into perception?
5. What's the perception range? Fixed or variable by perception mode (D-017)?
6. How do z-levels affect spatial queries? (D-014: 2-3 z-levels)
### Line of Sight
7. Which shadowcasting algorithm? (Q-018 — may resolve here or separately)
8. How do vision cones (D-015: forward/peripheral/behind) modify base LOS?
9. How do perception modes (D-017: thermal, camera, etc.) alter what's "visible"?
10. What is the LOS cache strategy? (Per-tick full recompute vs incremental?)
### Sound Propagation
11. How does three-range sound (D-018) map to the spatial query?
12. Does sound propagation through walls need a separate algorithm?
13. How are sound events created and consumed within a tick?
### Snapshot Assembly
14. What fields does ObserverSnapshot need beyond the current `tick` + `Vec<VisibleEntity>`?
15. How is fog grid data encoded? (Bitfield? Per-tile enum?)
16. When should delta compression be introduced? (Design interface now, implement later?)
### Performance
17. What's the per-tick budget breakdown? (e.g., spatial 5ms, LOS 20ms, sound 5ms, assembly 10ms)
18. Can perception updates be staggered across ticks for NPCs far from the player?
19. How many LOS queries can run within budget at 150x150?
## Input Documents
| Document | What to read | Why |
|----------|-------------|-----|
| `decisions/perception.md` | D-011, D-015, D-016, D-017, D-018, D-019 | Full perception spec |
| `decisions/architecture.md` | D-010, D-020, D-026, D-030, D-031 | Architecture + time constraints |
| `server/src/bridge/types.rs` | ObserverSnapshot, VisibleEntity types | Current wire format |
| `server/src/perception/mod.rs` | Perception plugin stub | Where this code will live |
| `server/src/simulation/movement.rs` | WalkabilityMap | Tile data available for LOS |
| `docs/audits/architecture-review-2026-02-11.md` | Tyre R-02, R-04; Troblum section 5 | Detailed proposals |
| Workshop 1 output | KnowledgeGraph design | Knowledge filtering input |
## Expected Outputs
1. **Decision: D-0XX — Observer Snapshot Pipeline** — Stage definitions, ordering, bevy_ecs system layout
2. **Decision: Resolution of Q-018** — Shadowcasting algorithm choice (or defer to separate spike)
3. **Algorithm specification:** Pseudocode for each pipeline stage
4. **Performance budget:** Per-stage timing targets at 80 Active NPCs
5. **Tickets:** Implementation tasks per stage
6. **ObserverSnapshot v2 schema:** Extended wire format with fog, sound, monologue fields
## Workshop Format
Two rounds:
- **Round 1:** Each participant independently analyzes the pipeline from their perspective
- **Round 2:** Cross-review, reconcile performance budgets, finalize algorithm choices
docs/workshops/save-load-architecture/workshop-brief.md
+71
View File
@@ -0,0 +1,71 @@
# Save/Load Architecture Workshop Brief
**Goal:** Design the save/load system — serialization strategy, versioning, migration, and relationship to tier serialization.
**Ticket:** #354 (epic)
**Priority:** MEDIUM — must resolve before vertical slice
**Participants:** Tyre (architecture lead), Dudley (implementation), Troblum (evaluation), Qatux (docs), Si (tickets)
**Source:** Architecture Review Audit 2026-02-11, Tyre R-08
## Context
Save/load is not addressed in any existing decision document or ticket. Both audit reviewers flagged this as a gap that must be resolved before the vertical slice.
The audit consensus recommends a **custom SaveState struct** over bevy_reflect, with versioning and migration. Troblum notes this creates a third data model alongside ECS components and ObserverSnapshot — every NPC component change requires updating 3 places.
D-026 defines tier serialization for State-saved NPCs (~1-2KB per frozen entity). The save/load system must interoperate with this — a full save includes all tiers, while tier serialization handles individual NPC state-save/restore during gameplay.
## Key Questions to Resolve
### Serialization Strategy
1. Custom `SaveState` struct vs bevy_reflect vs hybrid? (Audit recommends custom)
2. What is serialized? (All ECS components? Only authoritative state? Derived state rebuilt on load?)
3. What format? (bincode for speed, MessagePack for debuggability, JSON for human-readability?)
4. How large is a typical save? (15 NPCs x 1-2KB + map state + knowledge graphs + game clock)
### Versioning
5. What version scheme? (Semantic? Monotonic integer?)
6. How are migrations handled? (Forward-only? Rollback support?)
7. What triggers a version bump? (Any component change? Only breaking changes?)
8. How is backwards compatibility tested?
### Tier Integration
9. How does full-save serialization relate to tier serialization (#96)?
10. State-saved NPCs are already serialized blobs — does save/load wrap these directly?
11. Active-tier NPCs need full component serialization — same format as State-saved, or different?
12. How does the knowledge graph serialize? (Per-entity? Separate table?)
### Architecture
13. Where does save logic live? (bevy_ecs system? Separate module outside the schedule?)
14. How is save triggered? (Manual save, autosave, checkpoint?)
15. What about save corruption? (Checksums? Atomic writes? Backup previous save?)
16. Quick save vs named saves — different mechanisms or same with different metadata?
### Client-Side
17. Does the client need save/load awareness? (Save menu, load screen, save file browser)
18. How does save/load interact with the IPC bridge? (Pause simulation, serialize, resume?)
19. Are save files portable across platforms? (Q-007 implications)
## Input Documents
| Document | What to read | Why |
|----------|-------------|-----|
| `decisions/architecture.md` | D-010, D-020, D-026 | Architecture constraints, tier system |
| `server/src/npc/mod.rs` | NPC component model | What needs serializing |
| `server/src/simulation/tier.rs` | Tier system stub | Existing serialization infrastructure |
| `server/src/simulation/rng.rs` | SimRng (ChaCha20 seed) | RNG state must be saved for determinism |
| `server/src/simulation/time.rs` | SimulationTime | Game clock state |
| `server/Cargo.toml` | serde, rmp-serde dependencies | Available serialization tools |
## Expected Outputs
1. **Decision: D-0XX — Save/Load Architecture** — Strategy, format, versioning scheme
2. **SaveState schema:** Rust struct definitions with serde derives
3. **Migration strategy:** How version N saves load in version N+1
4. **Integration spec:** How save/load interacts with tier serialization
5. **Tickets:** Implementation tasks (server save system, client save UI, save format tests)
## Workshop Format
Two rounds:
- **Round 1:** Each participant analyzes from their domain (Tyre: architecture, Dudley: implementation, Troblum: risk and alternatives)
- **Round 2:** Cross-review, resolve trade-offs, finalize schema