settled-reach/docs/sprints/sprint-14/visual.md

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):

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "docs(visual): description" --description "body" --base main --head visual