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/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