settled-reach/docs/sprints/sprint-3/joint.md

Sprint 3: Know — Joint Tasks

Goal: Player character can observe NPCs, track their knowledge, and interact with the environment through a working observation event pipeline.

Branches: server + client (merge to main for integration)

Joint Tickets (Split Per Team)

Joint tickets are split between server and client teams. Work happens on separate branches, merges through main.

#341: Basic IPC error handling implementation

Split:

• Server half: Deserialization failure handling (log + dump raw bytes), clean shutdown on pipe break
  • Assigned to: server team (Dudley)
  • Files: server/src/bridge/local.rs, server/src/bridge/tcp.rs
• Client half: Server crash detection (SIGCHLD), error dialog with last log lines, pipe break handling
  • Assigned to: client team (Stig)
  • Files: client/scripts/protocol/server_process.gd, client/scripts/protocol/local_bridge.gd

Blocker: None — both sides can implement independently against the D-020 IPC contract.

#84: Multiple entity sync

Split:

• Server half: Add 2-3 NPCs to simulation with proper TilePosition + Npc components, ensure all appear in ObserverSnapshot
  • Assigned to: server team (Dudley)
  • Files: server/src/main.rs (world spawn setup)
  • Depends on: #86 (NPC components), #236 (done)
• Client half: Verify all entities render correctly from snapshot data, test entity lifecycle (appear/disappear/move)
  • Assigned to: client team (Stig)
  • Files: client/scripts/rendering/entity_renderer.gd
  • Depends on: #345 (bug fix)

Integration point: Both halves can be tested independently (server logs snapshot content, client uses test data), then integrated through the existing IPC bridge.

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

Key Decisions

• decisions/architecture.md — D-020 (subprocess IPC), D-010 (client-server separation), D-030 (testability)
• decisions/content.md — D-024 (NPC model), D-027 (vertical slice criteria)

Sprint Completion Proof

"Walk around and notice NPCs" — the sprint is done when:

1. Fog and LOS work (Sprint 2 baseline, maintained)
2. Multiple NPCs appear on screen with distinct colors
3. NPCs have daily routines and pathfinding works
4. Player can attempt to interact (dispatcher exists, even if handlers are stubs)
5. Observation events generate when NPCs do something interesting
6. IPC errors display useful messages instead of silent crashes
7. Entity rendering bug (#345) is verified fixed or documented as non-issue

Observation pipeline proof: Spawn an NPC at a scheduled location. The server generates an observation event when the NPC is in LOS. Logs confirm the event was generated with correct trigger type and NPC reference.

This is the first moment NPCs feel like people instead of sprites — they move with purpose, and the game notices when something is off.

Notes

• #341 (IPC error handling): Sprint 1-2 had minimal error handling — crashes were silent or cryptic. This ticket adds the minimum viable error UX: deserialization failures show raw data for debugging, server crashes show log tail in a dialog, pipe breaks shut down cleanly. Improves developer experience and prevents "what just happened" moments.
• #84 (Multiple entity sync): Sprint 1-2 had a single player entity. This ticket proves the sync layer works with multiple entities. The server-side work overlaps with #86 (NPC components) — if #86 is done first, this becomes trivial. The client-side work depends on #345 being resolved.
• Test plan per D-030 Phase 1: Sprint 3 bridges Phase 1 and Phase 2. Collision/pathfinding tests (#237) continue Phase 1 focus. Observation event generation (#239) is the first Phase 2 work (monologue pipeline integration test).

Dependency Chain

Server branch:
#341 (IPC error, server) → standalone, no blockers
#84 (multi-entity, server) → blocked by #86 (NPC components)

Client branch:
#341 (IPC error, client) → standalone, no blockers
#84 (multi-entity, client) → blocked by #345 (bug fix)

Integration:
Both halves of #341 merge independently
Both halves of #84 merge when both are complete

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(scope): description" --description "body" --base main --head <branch>