settled-reach/docs/workshops/observer-snapshot-pipeline/workshop-brief.md

title, description, type, status, workshop, created

title	description	type	status	workshop	created
Observer Snapshot Generation Pipeline Workshop Brief	Design the server-side pipeline that computes per-tick ObserverSnapshot from world state via spatial queries, LOS, and sound propagation.	workshop	archived	observer-snapshot-pipeline	2026-02-11

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