settled-reach/docs/sprints/sprint-12/client.md

Sprint 12: Build — Client Tasks

Goal: Lay the production-layer foundations — simulation tier system, sound event pipeline, visual grammar, and knowledge boundary enforcement — and complete all v0.1 copy authoring so content packs, opening hooks, and world-building docs are done.

Branch: client Agents: Stig (client dev), Tyre (architect), Hoshe (QA)

Carry-over from Sprint 11

None. Sprint 11 was 7/7 done.

New Tickets

#	Title	Blocked by
#125	Close-range stereo audio	#124 (server)
#126	Medium-range visual indicators	—
#345	Fix entity_renderer.gd field name bug	—
#447	Resolve OQ-29: dialogue max-width pixel value	—

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

Key Decisions

• decisions/architecture.md — D-020 (IPC bridge), D-066 (dual-scale grid)
• decisions/perception.md — D-018 (three-range sound model), D-067 (recognition chime at cognitive delay onset), D-068 (5-bus audio architecture), D-069 (audio dip profiles), D-071 (ListeningFocus boost for eavesdropping)

Open Questions to Resolve Early

• OQ-29 (#447): Dialogue max-width pixel value. Resolve before any dialogue layout work. Fast resolution — pick a value, record the decision.

Notes

#125 — Close-range stereo audio

• Blocked by #124 (server sound event system). Start once server delivers sound_events in ObserverSnapshot.
• The audio_manager.gd autoload (client/scripts/autoloads/audio_manager.gd) already exists from Sprint 8. This ticket wires it to the snapshot-driven event loop.
• Close-range events (RangeCategory::Close) map to 2D positional audio using Godot's AudioStreamPlayer2D. Screen-space coordinates from the entity's world position.
• Asset registry: AudioAssetRegistry maps event type (Footstep, Voice, etc.) to audio file. The 8 audio assets from D-038 (done Sprint 10) are available — use them.
• D-068 specifies the 5-bus architecture (Master, Ambient, World SFX, Player Actions, UI). Sound events go on the World SFX bus.
• D-069 audio dip: during confrontation, World SFX drops 4–6dB. The dip logic is in audio_manager.gd — confirm it's wired to the confrontation state flag.

#126 — Medium-range visual indicators

• Fog-edge directional indicators for sound events outside LOS (RangeCategory::Medium).
• Arrow or icon at the fog boundary, pointing toward sound source direction. Color-coded per D-018 and D-069: neutral #c8d0e0, voices #e8c547, danger #d45d5d.
• Triggers an internal monologue description (server-side, but client shows the indicator at the fog edge).
• Implementation: overlay node on top of fog_renderer (client/scripts/rendering/fog_renderer.gd.uid — confirm file name). Draw using _draw() or a dedicated indicator scene.
• Does not require #124 to be complete — can implement the indicator rendering standalone with mock data, then wire to snapshot.
• Visual spec for the fog-edge pulse design (#317, visual team) is in sprint but may not arrive before implementation. Use the D-018 color values as the reference.

#345 — Fix entity_renderer.gd field name bug

• Known bug: entity_renderer.gd references entity.id but the bridge protocol uses entity.entity_id.
• File: client/scripts/rendering/entity_renderer.gd.
• Fix the field name, add a regression test to the client test suite.
• Quick fix — do this first to unblock clean rendering for the sprint.

#447 — Resolve OQ-29: dialogue max-width pixel value

• Open question: what is the max pixel width for the dialogue box?
• Resolution approach: measure against the target resolution, pick a value that fits the grid. Document in client/scripts/constants.gd as DIALOGUE_MAX_WIDTH.
• Record the resolved value as a decision if it has downstream impact (it does — affects text wrapping in dialogue UI).

Dependency Chain

#124 (server, sound events) → #125 (close-range stereo audio)
#126 (medium-range indicators) — standalone, parallel
#345 (field name bug) — quick fix, do first
#447 (OQ-29 resolution) — standalone, do early

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(client): Sprint 12 — sound pipeline, medium-range indicators, renderer fix" --description "body" --base main --head client