From 7f97cb7ce3ce8098958e8015e852d27daac52719 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Wed, 11 Feb 2026 21:45:38 +0100 Subject: [PATCH] docs(sprints): add Sprint 2 "See" briefings for server, client, joint Sprint 2 goal: fog of perception working through the bridge. Server computes LOS visibility, client renders fog. Carries over #236 and #81 from Sprint 1. Co-Authored-By: Claude Opus 4.6 --- docs/sprints/sprint-2/client.md | 52 ++++++++++++++++++++++++++++++ docs/sprints/sprint-2/joint.md | 56 ++++++++++++++++++++++++++++++++ docs/sprints/sprint-2/server.md | 57 +++++++++++++++++++++++++++++++++ 3 files changed, 165 insertions(+) create mode 100644 docs/sprints/sprint-2/client.md create mode 100644 docs/sprints/sprint-2/joint.md create mode 100644 docs/sprints/sprint-2/server.md diff --git a/docs/sprints/sprint-2/client.md b/docs/sprints/sprint-2/client.md new file mode 100644 index 000000000..21a46018f --- /dev/null +++ b/docs/sprints/sprint-2/client.md @@ -0,0 +1,52 @@ +# Sprint 2: See — Client Tasks + +**Goal:** Fog of perception working through the bridge — server computes LOS visibility, client renders fog. + +**Branch:** `client` +**Agents:** Stig (UI), Oscar (networking) + +## Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #116 | Camera lock to character | — | +| #129 | Tile rendering engine | — | +| #130 | Entity sprite management | — | +| #131 | Fog overlay rendering | #129 (needs tile layer to overlay) | +| #113 | Fog rendering - client | #131 (rendering layer), server #112 (fog data in snapshot) | + +Use `db/connectors/ticket show ` for full details. + +## Key Decisions + +- `decisions/perception.md` — D-015 (camera locked, no panning), D-011 (fog of perception), D-019 (top-down camera) +- `decisions/architecture.md` — D-020 (ObserverSnapshot drives all rendering) +- `decisions/scope.md` — D-014 (v0.1 map spec: ~150x150, 2-3 z-levels, fog + LOS) + +## Notes + +- **#116:** Camera follows player character position. No panning, no rotation (v0.1). The `GameState.player_position` already tracks position — camera just needs to center on it smoothly. Use `Camera2D` with smoothing. Existing `main.gd` handles input; camera attaches to the player entity's position. +- **#129:** Multi-layer tilemap rendering from snapshot data. Currently the client renders entities as `ColorRect` placeholders (`client/scripts/rendering/entity_renderer.gd`). This ticket adds a `TileMapLayer` (or multiple layers) for floor/walls/objects. Tiles come from the `ObserverSnapshot` — the client draws what the server says is visible. Placeholder art: colored rectangles with labels (D-014: "functional boxes with labels"). +- **#130:** Upgrade entity rendering from `ColorRect` to proper sprite management. Animation states (idle, walk). Entity color based on relationship state (D-033: unknown=teal, known=green, POI=amber, hostile=red). Facing direction indicator. Builds on existing `entity_renderer.gd`. +- **#131:** Fog overlay on the tile layer. Three visibility states: visible (clear), fog-edge (dimmed), hidden (dark/black). Driven by `visible_tiles` data from `ObserverSnapshot`. This is the rendering half of the fog system — the server (#112) determines what's visible, the client draws the fog. +- **#113:** Integration of server fog data into the client fog renderer. The existing `fog_renderer.gd` is a stub. This ticket connects it to actual visibility data from the snapshot. Fog returns when you leave an area (time-based decay, tracked client-side from last-seen tick). +- **WorldRenderer:** The existing `world_renderer.gd` orchestrates entity + fog rendering. It already calls `entity_renderer.update_entities()` and `fog_renderer.update_fog()` — the stubs just need real implementations. + +## Parallelism + +``` +#116 (camera) — independent, start immediately +#129 (tiles) — independent, start immediately +#130 (sprites) — independent, start immediately +#131 (fog overlay) — needs #129 done +#113 (fog integration) — needs #131 + server #112 +``` + +#116, #129, #130 can all be worked in parallel from day one. + +## 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): +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(client): description" --description "body" --base main --head client +``` diff --git a/docs/sprints/sprint-2/joint.md b/docs/sprints/sprint-2/joint.md new file mode 100644 index 000000000..baa7290ce --- /dev/null +++ b/docs/sprints/sprint-2/joint.md @@ -0,0 +1,56 @@ +# Sprint 2: See — Joint Tasks + +**Goal:** Fog of perception working through the bridge — server computes LOS visibility, client renders fog. + +**Branches:** `server` + `client` (merge to main for integration) + +## Pre-Sprint + +| Task | Owner | Notes | +|------|-------|-------| +| Resolve Q-018 (shadowcast algorithm) | Tyre, Dudley | Blocks #110. Benchmark symmetric vs recursive at 150x150 scale. | +| Resolve Q-019 (entity ID stability) | Tyre, Dudley | Affects client entity lifecycle (#130). | +| Design ObserverSnapshot v2 schema | Tyre | Add visible_tiles, player_facing, game_time fields. Both teams need this before fog integration. | + +## Integration Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #81 | End-to-end connection test | Sprint 1 carry-over (in_progress) | +| NEW | Fog data through bridge | Server #112, Client #113 | +| NEW | Sprint 2 proof: fog of perception | All above | + +Use `db/connectors/ticket show ` for full details. + +## Key Decisions + +- `decisions/architecture.md` — D-020 (IPC protocol, ObserverSnapshot), D-010 (information boundaries) +- `decisions/perception.md` — D-011 (fog non-negotiable), D-015 (vision cone) + +## Sprint Completion Proof + +**"Walk into a room and see the fog"** — the sprint is done when: + +1. Player character moves on screen (Sprint 1 baseline, maintained) +2. Camera follows the player character (no panning) +3. Tiles render from snapshot data (floor + walls visible) +4. Entities appear/disappear based on line-of-sight +5. Fog covers areas outside the vision cone +6. Walking behind a wall hides what's on the other side +7. Walking around a corner reveals what's there + +This is the first moment the game *feels* like an immersive sim — you can't see behind walls, and that constraint IS the game. + +## Notes + +- **#81 (carry-over):** End-to-end connection test still in_progress from Sprint 1. Must complete before fog integration work. +- **ObserverSnapshot v2:** The current `ObserverSnapshot` (`server/src/bridge/types.rs`) only has `tick` + `entities: Vec`. Sprint 2 needs: tile visibility data, facing direction, time-of-day. Design the expanded schema before both teams start, so the contract is clear. +- **Fog data through bridge:** Server #112 produces visibility-filtered snapshots. Client #113 consumes them. The bridge already handles MessagePack serialization — new fields just need to be added to both sides. +- **Test plan per D-030 Phase 1:** Sprint 2 aligns with D-030's "Phase 1 (sprint 1-2): test infra + collision/pathfinding/time." Collision tests exist (`movement.rs`). Shadowcasting (#110) needs unit tests for known LOS scenarios (corridor, corner peek, wall block). Vision cone (#111) needs sector boundary tests. + +## 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): +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(scope): description" --description "body" --base main --head +``` diff --git a/docs/sprints/sprint-2/server.md b/docs/sprints/sprint-2/server.md new file mode 100644 index 000000000..281eb6fb6 --- /dev/null +++ b/docs/sprints/sprint-2/server.md @@ -0,0 +1,57 @@ +# 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) + +## Carry-over from Sprint 1 + +| # | Title | Status | Notes | +|---|-------|--------|-------| +| #236 | Tile collision system | ready | WalkabilityMap exists, needs wall data for LOS | + +## New Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #110 | Shadowcasting algorithm - server | #236 (walls needed for LOS) | +| #111 | Vision cone implementation | #110 | +| #112 | Observer visibility query | #111 | +| #25 | Game clock and day-phase system | — (SimulationTime exists, needs day-phase integration into snapshot) | + +Use `db/connectors/ticket show ` 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) + +## Open Questions to Resolve Early + +- **Q-018: Shadowcasting algorithm selection** — symmetric (Albert Ford) vs recursive. Needs benchmarking at 150x150 scale. Resolve before #110 starts. +- **Q-019: Entity ID stability** — how `entity_id: u64` maps to bevy `Entity`. Affects client entity lifecycle. +- **Q-021: Tick budget overflow policy** — what happens when a tick exceeds 100ms. + +## Notes + +- **#236 (carry-over):** `WalkabilityMap` and `validate_movement` are already implemented (`server/src/simulation/movement.rs`). The remaining work is integrating wall/blocked tile data that the shadowcasting algorithm needs. Walls must be both collision barriers AND LOS occluders. +- **#110:** Core of the sprint. Implement LOS calculation per z-level. The `WalkabilityMap` stores tile walkability in chunks — the shadowcasting system reads this (or a parallel opacity map) to determine what blocks vision. 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` (or bitmap), `player_facing: Direction`, `game_time: TimeData`. Design this before implementation starts. + +## Dependency Chain + +``` +#236 (walls) → #110 (shadowcast) → #111 (vision cone) → #112 (observer query) +#25 (time) → standalone, parallel track +``` + +## 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): +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(simulation): description" --description "body" --base main --head server +```