---
title: "Sprint 14 — Visual Briefing"
description: "Entity color system spec, text display hierarchy, sound indicator visual design"
type: sprint
status: archived
sprint: 14
team: "visual"
---

# Sprint 14: Live — Visual Tasks

**Goal:** Bring NPCs to life — mood, trust, routine execution, and NPC-to-NPC conversation drive the first emergent social observables; the simulation produces a world that breathes independently of the player.

**Branch:** `visual`
**Agents:** Araminta (art direction)

## Carry-over from Sprint 13

None. All Sprint 13 visual tickets done (#315 monologue display spec).

## New Tickets

| # | Title | Blocked by |
|---|-------|------------|
| #304 | Entity Color System Spec — relationship-to-player mapping | #303 done |
| #316 | Text display hierarchy spec — 4 content pipelines | #303 done |
| #317 | Sound indicator visual design — fog-edge pulse | #303 done |
| #318 | THE FRIEND visual treatment spec | #303 done, #297 done, #298 done |
| #334 | Environmental text visual standards | #303 done |
| #251 | Tell visual/behavioral expression | — |

All six tickets are unblocked. All are spec/design documents — Araminta authors; no code deliverables from the visual branch this sprint.

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

## Key Decisions

- `decisions/content.md` — D-033 (entity color = relationship to player — approved color hex values: unknown=teal #4a9ebb, known/friendly=green #6bc9a6, person-of-interest=amber #e8c547, hostile=red #d45d5d, static objects=grey #8090a8), D-034 (THE FRIEND — phase 1 identical to other friendly NPCs, earned visual detail only), D-043 (art direction — functional warmth), D-044 (visual hierarchy — entity > object > structure), D-045 (environmental neutrality — zero shift with narrative state), D-046 (lighting system — three-reference model), D-047 (two-tier animation system — Tier 1 readable, Tier 2 ambiguous), D-048 (neural insert overlay), D-049 (z-level rendering stack — 8 layers)
- `decisions/perception.md` — D-016 (internal monologue — text rendering), D-017 (perception modes), D-018 (three-range sound model — color codes for sound indicator: neutral #c8d0e0, voices #e8c547, danger #d45d5d), D-035 (tag taxonomy — monologue display spec references character field), D-062 (invisible locked dialogue — no lock icons, no hints)
- `decisions/scope.md` — D-027 (vertical slice success criteria — #3: player names an NPC they felt conflicted about = THE FRIEND)

## Notes

- **#304 — Entity Color System Spec:** Araminta formalizes the approved D-033 color model into a full spec document. Output: `docs/design/entity-color-system.md`. Required sections:
  - Relationship state → color mapping table (hex values confirmed in D-033 are the canonical source).
  - How relationship state is determined at render time: client receives `relationship: RelationshipState` on each `VisibleEntity` in the snapshot (`server/src/bridge/types.rs` `VisibleEntity`). Client maps state to color via a lookup table in `entity_renderer.gd` (`client/scripts/rendering/entity_renderer.gd`).
  - Transition behavior: when an entity's relationship state changes (e.g., PersonOfInterest after confrontation), how the color shift renders — instant or tween, duration.
  - Static objects: always `#8090a8` regardless of any relationship state. Define what counts as a static object (fixtures, furniture, terminals) vs entity (NPCs, player, carried items).
  - Edge cases: player character color (not subject to relationship coloring — different treatment), entities in fog (D-033 color does NOT show through fog — unrecognized fog blobs are grey until cognitive delay resolves), entities at periphery (reduced saturation per D-046 lighting reference model).
  - Color blindness note: D-033 colors were selected for functional warmth — include Araminta's assessment of whether the teal/green/amber/red set is distinguishable under deuteranopia and protan deficiency. Flag if adjustment needed.
  - This spec is the direct input to the client-side implementation (future sprint — no client ticket this sprint). Must be self-contained enough for Stig to implement from the doc alone.

- **#316 — Text display hierarchy spec:** How the four content pipelines render distinctly. Output: `docs/design/text-display-hierarchy.md`. Four pipelines:
  1. **Dialogue** (NPC speech + player response options): bottom panel, max 20% height, max ~100 chars per line (D-061). Speaker name styled. Response options styled differently from speech.
  2. **Internal monologue** (player character): left-side or bottom-left, italic, smaller font, character colour from #315 spec (done Sprint 13).
  3. **Observation / overheard** (what the player perceives about NPCs or overhears): distinct treatment from monologue — diegetic information output, not character voice. Consider: greyed label, different font weight, positioned differently.
  4. **Environmental text** (signage, terminals, news tickers in-world): diegetic — appears in the world layer, not the HUD layer. Two-language treatment per D-036 (Concordat Standard + Van Maanen's Star vernacular). Character limits per format (signage shorter, terminal longer, news ticker scrolling).
  - Each pipeline needs: position on screen, font size/weight, colour scheme, max width/height, fade/truncation behaviour. D-049 z-layer assignments for each.
  - Reference: `docs/design/monologue-display-spec.md` (#315, done) for monologue pipeline specifics — this spec extends and cross-references it.

- **#317 — Sound indicator visual design:** Fog-edge pulse indicators for the D-018 three-range sound model. Output: `docs/design/sound-indicator-visual.md`. Design requirements (from ticket and D-018):
  - **Purpose:** Complementary to audio, not replacement. Indicates sound presence for players with audio off or in loud environments.
  - **Colors:** neutral #c8d0e0 (footsteps, ambient), voices #e8c547 (NPC conversation), danger #d45d5d (alarms, alerts).
  - **Position:** Fog edge — where the visible area meets unexplored/deep fog. Not a minimap overlay, not a screen-edge indicator. Appears at the boundary tiles of the player's visible cone.
  - **Shape and animation:** Pulse — how many pixels, what frequency, what easing, what opacity range. Must not be distracting during exploration; must be noticeable when specifically a threat.
  - **Direction encoding:** Indicates direction the sound comes from — how? Arc segment on fog edge in the direction of source? Size variation? Specify clearly for Stig's implementation.
  - **Range differentiation:** Close sounds (≤3 tiles) produce larger/brighter pulses; medium (≤8 tiles) moderate; long (≤20 tiles) subtle. Define the three visual levels.
  - **When it does not appear:** When audio is playing and the sound is within the visible area (no need to indicate what you can already see/hear). Rules for suppression.
  - The `sound_indicator_renderer.gd` file exists at `client/scripts/rendering/sound_indicator_renderer.gd` — Araminta should note what it currently does vs what the spec calls for.

- **#318 — THE FRIEND visual treatment spec:** How Kael Davan (smuggler's FRIEND) and Sera Venn (detective's FRIEND) look different from other NPCs through earned visual detail only — no special marking. Output: `docs/design/the-friend-visual-treatment.md`. Per D-034 design principle: Phase 1 identical to other friendly NPCs (green rectangle per D-033). Differentiation accrues through story, not through marking. Required sections:
  - **Phase 1 (before player builds relationship):** Identical to any other Known/Friendly NPC. Green rectangle, no distinguishing visual.
  - **Phase 2 (after 3+ interactions, trust building):** What subtle visual shift occurs — if any — that is diegetically justified, not metatextual marking. Examples: does the character carry an item that renders (a manifest, a specific color? per D-033 object color rules)? Does their routine placement become more predictable visually? Define what "earned visual detail" means concretely.
  - **Phase 3 (contradiction discovered — PersonOfInterest):** Transition to amber #e8c547 per D-033. Monologue firing rate spikes. Spec: when does the color shift? Immediately on confrontation? On player delivery of contradiction knowledge? Tween duration.
  - **Animation tier:** THE FRIEND is in Tier 2 animation (ambiguous, privately motivated behaviors per D-047) once the player has seen their contradiction. Before contradiction: Tier 1. Spec the transition point.
  - Cross-reference `docs/design/entity-color-system.md` (#304, this sprint) once it is drafted.

- **#334 — Environmental text visual standards:** How signage, terminals, and news tickers render in-world. Output: `docs/design/environmental-text-standards.md`. Per ticket:
  - **Signage:** Short (1-3 words typical), both Concordat Standard and Van Maanen's Star vernacular. Character limits. Font size relative to tile size (D-066: 1m visual tiles, 2x retina factor). Position: floating above the tile, or rendered on the tile surface.
  - **Terminals:** Longer text, readable on interaction (Observe verb). Two-state: ambient (icon/identifier visible from range) and active (text readable when player is adjacent).
  - **News tickers:** Scrolling text, ambient, not blocking gameplay. Where on screen — in-world (floating above terminal), not HUD overlay.
  - **Bilingual treatment:** Concordat Standard is the colonial lingua franca (neutral, bureaucratic). Van Maanen's Star vernacular is the local dialect (warm, compact, consonant-heavy per D-036 naming conventions). Which text in which language per context? Formal signage = Concordat Standard. Informal social text (bar menu, worker notices) = Van Maanen's Star vernacular. Mixed where both audiences are intended.
  - **Rendering layer:** Per D-049 z-layer stack — environmental text is object-layer (layer 2-3), not HUD layer (layer 6+). Must not occlude entities.

- **#251 — Tell visual/behavioral expression:** How NPC behavioral tells manifest in the top-down renderer. Output: `docs/design/tell-visual-expression.md`. Per D-024 tell system (5 categories: nervous, angry, friendly, guarded, routine deviation) and server's `TellSystem` component (`server/src/npc/mod.rs`). In v0.1, tell expression is via **monologue text** (server emits monologue on observe_npc trigger when tell is active), not visual animation — this is confirmed. However, Araminta's task is to define:
  - What observable behaviors in the top-down renderer accompany tells — movement hesitation (NPC pauses before entering a room), route changes (NPC takes alternate path), grouping behavior (NPC lingers near another), interaction changes (NPC avoids certain tiles).
  - These are **behavioral patterns in the simulation** described visually — the spec tells Dudley what the tell should look like at the tile level, which he implements as movement/pathfinding modifiers. The spec is the design input to server-side tell behavior.
  - Per D-047 animation tier: Tier 2 animation is "ambiguous, privately motivated behaviors." Tells are the canonical Tier 2 examples — movement hesitation is a Tier 2 animation. Define which of the 5 tell categories maps to which Tier 2 behaviors.
  - Araminta's scope here: the visual description. Dudley implements the simulation behavior. Mellanie writes the monologue that accompanies the tell.

## Dependency Chain

```
#304 (entity color spec) ─────────────────→ #318 (THE FRIEND visual, cross-ref)
#316 (text display hierarchy) ───────────→ standalone
#317 (sound indicator visual) ───────────→ standalone
#318 (THE FRIEND visual) ────────────────→ #251 (tell visual, cross-ref)
#334 (environmental text) ───────────────→ standalone
#251 (tell visual) ──────────────────────→ standalone
```

Recommended order: start #304 (entity color) first — #318 cross-references it. #251 and #318 can proceed in parallel once #304 is drafted. The other three (#316, #317, #334) are fully independent and can proceed in any order.

## 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 "docs(visual): description" --description "body" --base main --head visual
```