settled-reach/decisions/perception.md

# Perception Decisions

How the player observes and interacts with the world: camera, fog, line-of-sight, sound, monologue, perception modes.

---

### D-011: Fog of perception is non-negotiable (Pillar 1 infrastructure)
- **Date:** 2026-02-09
- **Decision:** Fog of perception is not a feature - it's the minimum requirement for information asymmetry to work with a top-down camera. Without it, the player is omniscient within their viewport and the entire information pillar collapses at the local map level. First-person camera gets this for free; top-down must enforce it.
- **Implementation:** Line-of-sight based (shadowcasting), not simple radius. Walls block vision, buildings are opaque, corners create blind spots, z-levels interact with sightlines.
- **Sound as secondary information channel:** Events outside LOS can be heard - footsteps, conversations, gunfire, alarms. Sound gives partial/directional information, prompting decisions based on incomplete data.
- **Applies to ALL entities:** NPCs use the same LOS/perception system as the player. An NPC who can't see you doesn't know you're there. NPCs have memory and inference (saw you enter a building → knows you're inside). Ties to [D-010](architecture.md#d-010-multiplayer-ready-architectural-baseline) principle 2: information boundaries are universal, the player's isn't special.
- **Fog returns when you leave:** Previously explored areas revert to fog over time. Information about locations decays. What you saw at the docks yesterday may not be true today.
- **v0.1 scope:** 2D shadowcast per z-level + sound propagation. Vertical LOS (looking between floors) deferred.
- **Rationale:** Team Leader identified overnight that top-down without fog is a fundamental gap in the information asymmetry design.
- **Raised by:** Team Leader (Jeroen), with technical framing by Tyre and Gestalt.

### D-015: Camera locked to character, rotation as future option
- **Date:** 2026-02-09
- **Decision:** Camera is locked to the character at all times. No panning. Optionally rotates to character facing direction (player option, later version).
- **Rationale:** Pannable camera breaks the information model - you become a surveillance drone, not a character. Locked camera reinforces "you ARE this person." Rotation with facing direction restores directional audio mapping (binaural becomes viable again) and creates a natural vision cone (front = detailed, peripheral = reduced, behind = blind).
- **Vision cone model:**
  - Forward: full LOS, full detail
  - Peripheral: reduced range, dimmer
  - Behind: fog / blind spot. You can be snuck up on.
- **Reference:** Hotline Miami's camera made that game terrifying with the same principle.
- **v0.1:** Locked camera, no rotation. Vision cone still works on fixed-north map. Rotation deferred as player option.
- **Raised by:** Team Leader (Jeroen).

### D-016: Internal monologue as core perception/atmosphere system
- **Date:** 2026-02-09
- **Decision:** The player character has an internal monologue that narrates sensory information the camera can't show, creates atmosphere, provides diegetic hints, and can be an unreliable narrator.
- **Functions:**
  - **Perception bridge:** Translates non-visual senses into character voice. *"Footsteps behind me. Two people, unhurried."*
  - **Atmosphere:** Character's running commentary on environment, mood, situation.
  - **Diegetic tutorial:** Character thinks about what they might do. *"That terminal might have access logs."* No "press X" popups.
  - **Unreliable narrator:** Monologue is character's INTERPRETATION, not ground truth. Can be wrong. *"Seems quiet. Safe to move."* (It wasn't safe.)
  - **Character voice:** Varies by character background, mood, knowledge. Paranoid Guardian vs confident Senator walking the same street = different monologue = different experience.
- **Production note (Nigel):** Cheapest feature on the list - it's text. Thousands of contextual lines, AI-assistable generation, character-specific variants.
- **Raised by:** Emerged from team discussion. Tyre proposed text/log as sound option, team recognized broader potential.

### D-017: Perception modes as character-build system
- **Date:** 2026-02-09
- **Decision:** The fog/vision system supports multiple perception modes that vary by character build, equipment, and ascension level. Each mode reveals different information with different trust/quality tradeoffs.
- **Confirmed modes:**
  - **Natural vision** - detail, color, identity. Blocked by walls. Everyone has it.
  - **Thermal** - heat signatures through walls. Body count but no identity. Higher biononic / military gear.
  - **Camera feeds** - remote visual from fixed positions. Only where cameras exist. Feed can be spoofed/looped. Hacker, institutional access, insert exploit.
  - **Unisphere tracking** - location pings of known individuals. Only active inserts, can be masked. Law enforcement / intelligence access.
  - **Audio analysis** - sound signatures, direction, classification. No visual. Insert processing, trainable skill.
- **Ascension scaling:**
  - Baseline: natural vision + carried gear
  - Enhanced: insert-based modes, camera access, audio processing
  - Higher: biononic thermal, enhanced spectrum, passive scanning
  - ANA-touched: pattern recognition across all feeds, predictive awareness
- **Playstyle implications (Nigel):** Low-tech Guardian playthrough = survival horror (blind, relying on contacts and paranoia). Senator playthrough = information overload (cameras and tracking but drowning in data). Perception modes are playstyle selectors.
- **v0.1:** Natural vision cone + basic audio indicators + insert minimap only. Additional modes are milestone features, each self-contained and modular.
- **Engine implication:** Each perception mode is an observer query against the information boundary system ([D-010](architecture.md#d-010-multiplayer-ready-architectural-baseline) principle 2). Engine doesn't distinguish between eyes/thermal/camera - all are "given this sensor, what state is visible?"
- **Raised by:** Team Leader (Jeroen) proposed thermal and camera hacking. Full team developed into perception mode framework.

### D-018: Three-range sound model
- **Date:** 2026-02-09
- **Decision:** Sound information reaches the player through three ranges with decreasing accuracy and trust:

| Range | Method | Info quality | Trust level |
|-------|--------|-------------|-------------|
| Close (near/in LOS) | Stereo audio (maps to facing direction with camera rotation) | High accuracy, identity possible | Raw sensory, reliable |
| Medium (outside LOS, nearby) | Visual indicators at fog edge + internal monologue | Directional, imprecise, type classification | Sensory impression, reliable but vague |
| Long (across map) | Insert notifications, text alerts | Specific but delayed, location data | Network-dependent, spoofable, manipulable |

- **Key insight:** Each range is a different information QUALITY, not just distance. Close = trustworthy. Long = potentially compromised. The Starflyer's agents would absolutely spoof long-range feeds.
- **v0.1:** Screen-space stereo for close + visual fog-edge indicators for medium. Long-range insert alerts as stretch goal.
- **Raised by:** Full team discussion.

### D-019: Top-down confirmed as primary camera, 3D cutscenes for key moments
- **Date:** 2026-02-09
- **Decision:** Top-down is the gameplay camera. Final. 3D cutscenes can be used for significant narrative moments (wormhole traversal, Dyson barrier opening, first contact, major reveals).
- **Rationale after full honest review:**
  - What first-person would give us (visceral traversal, face-to-face conversations, natural asymmetry, spatial horror) is real but compensated by: vision cone + fog, internal monologue, perception mode overlays, sound model
  - What top-down gives us that first-person can't: multi-layer information observation, tactical combat clarity, system legibility, NPC simulation visibility, strategic UI coexistence, 5-10x faster prototype
  - Key insight (Gestalt): the fun is systems interacting - observation → insert check → thermal → monologue → mental note → exploitation. That sequence is BETTER top-down.
  - Key insight (Paula): monologue interpreting faces/conversations is arguably richer than player reading 3D faces, and more faithful to Hamilton's close-POV writing style
  - 3D cutscenes recapture the visceral moments without burdening gameplay engineering. They're decoupled, can be added as polish, game ships complete without them.
  - Camera change to 3D IS the dramatic signal - player knows something significant is happening (Gestalt)
- **Architecture note (Tyre):** Client-server separation means the renderer is swappable. A full first-person client is architecturally possible in the future. Top-down now doesn't mean top-down forever.
- **v0.1:** Top-down only. No cutscenes. Those are milestone features.
- **Raised by:** Team Leader (Jeroen), after full team review of tradeoffs in Round 12.

### D-033: Entity color = relationship to player
- **Date:** 2026-02-11
- **Decision:** Entity color in the top-down view represents the character's *relationship* to the player character, not an objective property. The same NPC can appear as different colors to different characters. Color is a client-side derivation from `RelationshipState` component + knowledge state — not an NPC property.
- **Color palette:**
  - **Unknown/Neutral:** Cool teal `#4a9ebb` — default for unassessed NPCs
  - **Known/Friendly:** Soft green `#6bc9a6` — people the character knows and trusts
  - **Person of Interest:** Warm amber `#e8c547` — monologue or case file has flagged something
  - **Hostile/Dangerous:** Muted red `#d45d5d` — character KNOWS there's danger (subjective, not omniscient)
  - **Static objects:** Muted grey `#8b8ba0` — furniture, equipment, environmental
  - **Player character:** `#e0e8ff` (detective, cool) / `#e8e0d0` (smuggler, warm)
- **Key principle:** Red means danger TO YOUR CHARACTER, not danger in the abstract. The detective might see amber (flagged in case file) where the smuggler sees green (trusted colleague). This IS asymmetric information rendered visually.
- **Transition behavior:** Color shifts smoothly (0.5s fade) when relationship state changes. THE FRIEND's first color shift (green → amber) should be the first relationship color change in the session — maximum emotional impact.
- **Cross-reference:** Internal monologue ([D-016](#d-016-internal-monologue-as-core-perceptionatmosphere-system)), THE FRIEND pattern ([D-034](content.md#d-034-the-friend--production-level-npc-pattern))
- **Raised by:** Araminta (Round 1 proposal, color palette design), project lead (approved, directive #2)
- **Dissent:** None

### D-035: Symmetric shadowcasting (Albert Ford) selected for LOS computation
- **Date:** 2026-02-11
- **Decision:** Albert Ford's symmetric shadowcasting algorithm is selected for all line-of-sight computation. The traditional recursive shadowcasting algorithm is rejected.
- **Resolves:** Q-018
- **Benchmark results (debug build, 1000 iterations, range 20):**

| Map | Density | Symmetric | Recursive | Speedup |
|-----|---------|-----------|-----------|---------|
| 32x32 | open | 920µs/call | 1118µs/call | 1.2x |
| 32x32 | 10% walls | 845µs/call | 4003µs/call | 4.7x |
| 32x32 | 30% walls | 334µs/call | 2099µs/call | 6.3x |
| 64x64 | open | 929µs/call | 1114µs/call | 1.2x |
| 64x64 | 10% walls | 745µs/call | 4060µs/call | 5.5x |
| 64x64 | 30% walls | 215µs/call | 1716µs/call | 8.0x |
| 150x150 | open | 919µs/call | 1102µs/call | 1.2x |
| 150x150 | 10% walls | 615µs/call | 3347µs/call | 5.4x |
| 150x150 | 30% walls | 163µs/call | 1709µs/call | 10.5x |

- **Key findings:**
  - Symmetric is 1.2-10.5x faster across all configurations (debug build; release will be significantly faster)
  - Advantage increases with wall density — more occlusion means less work for the quadrant-based approach
  - Map size has minimal effect on relative performance at range 20 (both algorithms are bounded by vision range, not map size)
  - All values well within the 100ms tick budget (D-026), even in debug
  - Symmetry property verified: if A sees B, then B always sees A — critical for D-011's requirement that NPCs use the same perception system as the player
- **Implementation:** Uses rational fraction slopes (`num/den` integer pairs) to avoid floating-point drift. Processes 4 cardinal quadrants with coordinate transforms. The production API is `compute_fov(is_opaque, origin_x, origin_y, range, z_level) -> VisibilityMap`.
- **Raised by:** Dudley (implementation + benchmark), Tyre (technical direction)
- **Dissent:** None

---

*8 decisions. Last updated: 2026-02-11*