settled-reach/docs/sprints/sprint-2/server.md

title, description, type, status, sprint, team

title	description	type	status	sprint	team
Sprint 2 — Server Briefing	Shadowcasting algorithm, vision cone implementation, ObserverSnapshot v2 schema	sprint	archived	2	server

Sprint 2: See — Server Tasks

Goal: Fog of perception working through the bridge — server computes LOS visibility, client renders fog.

Branch: server Agents: Dudley (simulation), Oscar (networking)

Design Tasks

#	Title	Blocked by
#359	Resolve Q-018: shadowcasting algorithm selection	—
#358	Design ObserverSnapshot v2 schema	—

Implementation Tickets

#	Title	Blocked by
#110	Shadowcasting algorithm - server	#359 (algorithm decision)
#111	Vision cone implementation	#110
#112	Observer visibility query	#111, #358, #361, #362
#25	Game clock and day-phase system	#358 (snapshot schema)

Knowledge Graph Tickets (from Workshop #351, D-041)

#	Title	Priority	Est.	Blocked by
#361	Implement KnowledgeGraph component + types	critical	1d	—
#362	StableEntityId + EntityRegistry resource	critical	1d	—
#363	KnowledgeEventQueue + processing system	high	0.5d	—
#364	Direct observation knowledge flow	critical	0.5d	—
#365	Basic knowledge decay system	high	0.5d	—
#367	Knowledge graph unit test suite	high	1d	—

Start #361 and #362 on day 1. Both block #112 (observer visibility query). See decisions/architecture.md D-041 for canonical struct definitions.

Use db/connectors/ticket show <id> for full details.

Key Decisions

• decisions/perception.md — D-011 (fog non-negotiable), D-015 (locked camera + vision cone), D-018 (three-range sound model)
• decisions/architecture.md — D-010 (information boundaries), D-020 (ObserverSnapshot), D-031 (time system), D-041 (Knowledge Graph Data Model)
• docs/workshops/knowledge-graph-information-boundaries/round2-synthesis.md — canonical reference for knowledge graph structs and Sprint 2 scope

Open Questions to Resolve Early

• Q-018 (#359): Shadowcasting algorithm selection — symmetric (Albert Ford) vs recursive. Needs benchmarking at 150x150 scale. Resolve before #110 starts.
• Q-019 (#360): Entity ID stability — how entity_id: u64 maps to bevy Entity. Affects client entity lifecycle. (Joint ticket, blocks #130.)
• Q-021: Tick budget overflow policy — what happens when a tick exceeds 100ms. (Not yet ticketed.)

Notes

• #236 (Sprint 1, done): WalkabilityMap and validate_movement are implemented (server/src/simulation/movement.rs). Walls are both collision barriers AND LOS occluders — the shadowcasting system reads the walkability map (or a parallel opacity map) to determine what blocks vision.
• #110: Core of the sprint. Implement LOS calculation per z-level. Output: set of visible tiles for a given observer position.
• #111: Vision cone sectors (forward/peripheral/behind per D-015). Facing direction component needed. Forward = full LOS range, peripheral = reduced range + dimmer, behind = blind. The cone modulates the shadowcast output.
• #112: Given an observer entity, return visible entities and tiles. This is the system that populates ObserverSnapshot.entities with only what the observer can see. Currently the snapshot includes ALL entities (no filtering). This ticket adds the filter.
• #25: SimulationTime already exists (server/src/simulation/time.rs) with tick/pause/day-phase. Remaining: include time data in ObserverSnapshot so the client can display it. May also need FacingDirection component for vision cone.
• ObserverSnapshot expansion: The ObserverSnapshot struct (server/src/bridge/types.rs) needs new fields: visible_tiles: Vec<VisibleTile> (or bitmap), player_facing: Direction, game_time: TimeData. Design this before implementation starts.

Dependency Chain

#359 (Q-018) → #110 (shadowcast) → #111 (vision cone) ──┐
#361 (KnowledgeGraph) ─┬─→ #112 (observer query) → ...  │
#362 (StableEntityId) ─┘                                  │
#358 (snapshot v2) → #112, #113, #25  ────────────────────┘
#25 (time) → parallel track, blocked by #358

Knowledge graph parallel track:
#361, #362 (day 1-3, no blockers) → #363, #364 (day 3-4) → #365, #367 (parallel)

PR Workflow

When ready to submit, create a PR with tea CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(simulation): description" --description "body" --base main --head server