settled-reach/docs/design/the-friend-visual-treatment.md

THE FRIEND — Visual Treatment Specification

Version: v0.1 (Sprint 14) Author: Araminta (Visual Designer) Date: 2026-02-20 Ticket: #318 Status: Active — visual design input to server and copy team; constrains #251 (tell visual expression) Foundation: Entity Color System (#304), Visual Grammar v0.1, Decisions D-034, D-033, D-047, D-027

---

1. Design Principle

Per D-034: "Phase 1 identical to other friendly NPCs. Earned visual detail only."

THE FRIEND does not receive special visual marking. There is no halo, no highlight, no indicator that says "this NPC is important." The player's emotional investment in THE FRIEND is built entirely through story and interaction — accumulated time, dialogue, observed routine. Visual differentiation accrues through narrative, not through marking.

This is non-negotiable. If the game tells the player "this NPC matters," it removes the uncertainty that makes the eventual contradiction devastating. The detective should be conflicted not because the game flagged Sera as special, but because they made her special through their own attention.

The wow moment (D-027 success criterion #3: "player names an NPC they felt conflicted about") depends entirely on the visual system having been honest. THE FRIEND looked exactly like any other known/friendly NPC throughout. That's why the color shift lands.

---

2. The Two FRIENDs

Smuggler's FRIEND: Kael Davan — dock worker, ring member, the smuggler's closest colleague. Contradiction: secret meeting with unknown contact in restricted corridor (trying to exit the ring to protect his partner Naia).

Detective's FRIEND: Sera Venn — Commission field tech, bar regular, the detective's social anchor. Contradiction: avoids Torek Lintar while sitting on unreported evidence about Kael's manifest discrepancies (protecting her friend Naia).

Both FRIENDs follow the same visual pattern. The spec applies to both. Where character-specific detail is needed, it is noted.

---

3. Phase 1 — Before Relationship Builds (Identical to Any NPC)

3.1 Visual State

Phase 1 begins when the player first encounters THE FRIEND. It ends when the player has had 3+ meaningful interactions that build trust.

Property	Value	Notes
Entity color	#6bc9a6 (Known/Friendly green)	Standard D-033 Known state
Entity size	24×32px art, 64×64 canvas	Standard entity size
Outline	2px #333340	Standard entity outline
Animation tier	Tier 1	Public daily activities — readable
Silhouette feature	One identifying feature	See §3.2
Insert bloom	Soft halo at D-033 green, 2–3px gaussian	Standard insert treatment

THE FRIEND is green. Exactly like any other known/friendly NPC. The player has no way to distinguish them from Lera (bar owner), from a dock colleague, from any other Known relationship.

3.2 Identifying Silhouette Feature

Each named NPC has one identifying silhouette feature (D-044) that allows recognition by shape before color is processed. These features are design-level decisions — they are built into the NPC sprite and remain consistent throughout all phases.

NPC	Silhouette feature	Notes
Kael Davan	Vest ridge	The dock-worker vest creates a shoulder-width silhouette difference from generic workers
Sera Venn	Uniform collar	Commission field tech uniform collar — distinguishes her from bar-regulars in plainclothes
Lera Sessik	Apron shape	Bar owner's apron creates distinctive hip-width silhouette

The silhouette feature is NOT a marker. It is simply what makes Kael look like Kael and not like a generic dock worker. The player identifies him by shape, same as they identify any person in a crowd by how they carry themselves.

In Phase 1, the player will not yet know who Kael is. They see a green entity with a vest ridge. After one or two interactions, they associate vest-ridge = Kael. The identification system builds through play, not through a label.

---

4. Phase 2 — Relationship Building (3+ Interactions, Trust Accruing)

4.1 Visual State

Phase 2 is entered after the player has had sufficient meaningful interactions with THE FRIEND that trust is accruing (per the server's trust progression system, #324). The player now has a genuine social relationship — not just an acquaintance, but someone they've spent time with.

Visual changes in Phase 2: none to the entity itself.

The entity remains green. The silhouette remains the same. No new markers appear.

4.2 What "Earned Visual Detail" Means

"Earned visual detail" does not mean the entity sprite changes. It means the player has built up contextual knowledge that makes THE FRIEND visually meaningful even without special marking.

The player now knows:

• Where Kael usually is at what time of day (routine familiarity)
• What Kael's silhouette looks like from across a room (pattern recognition)
• Which zone Kael belongs to (environmental anchoring)

This contextual knowledge is itself a form of visual differentiation — not rendered, but real. When the player sees a green vest-ridge entity at the docking terminal at 0800, they don't need a marker to know it's Kael. They've learned it.

4.3 Object Layer Detail (D-052)

Per D-052, each NPC has a "favorite color" expressed through personal objects — not entity sprites. By Phase 2, the player may have observed Kael's personal space and noted object-layer details: his particular mug color, the color of his dock-worker ID lanyard, the worn cargo blanket he keeps near his work station.

These are NOT visual markers. They are world texture. But they are the kind of visual detail that makes a person a person rather than an entity. The player remembers the mug color. When they see the mug on the table in the maintenance corridor, they know Kael was here.

This is earned visual recognition through accumulated observation — exactly what the principle intends.

---

5. Phase 3 — Contradiction Discovered (PersonOfInterest Transition)

5.1 The Moment

The contradiction is discovered through player action — observing Kael in the restricted corridor meeting, finding Sera avoiding Torek in a way that doesn't add up. The discovery is not scripted with a cutscene. The player sees it happen in the normal top-down view.

At the moment of contradiction discovery, THE FRIEND's relationship state transitions from Known/Friendly to PersonOfInterest on the server's knowledge graph. This triggers the D-033 color change.

5.2 Color Transition Specification

Property	Value	Notes
From color	#6bc9a6 (Known/Friendly green)	The color the player has seen for hours
To color	#e8c547 (PersonOfInterest amber)
Transition duration	0.5 seconds	Standard D-033 fade duration
Transition type	Linear color lerp	Same as all relationship transitions
When triggered	On server's PersonOfInterest state delivery	Client receives updated RelationshipState in snapshot

0.5 seconds is the right duration here. It is long enough to be perceptible — the player watches green become amber, they don't blink and miss it. It is short enough to feel immediate rather than gradual. This is the one relationship color change the game has been building toward. It must land.

5.3 Staging Requirement

This is THE FRIEND's first color change. It must be the first relationship color change the player has seen in the session.

The opening 20–25 minutes of gameplay must not trigger any other NPC's relationship state change. No other NPC should transition between any two D-033 states before THE FRIEND's green-to-amber shift. This is a level design and scripting constraint, not a rendering constraint — it is satisfied by game design, not by visual code.

Why this matters: The player must have already learned what green means. They must associate #6bc9a6 with "trusted person I know" before amber can mean "this trusted person has complicated things." Without the reference point, the color shift is just a color shift.

5.4 Post-Transition Visual State

Once PersonOfInterest amber is active, THE FRIEND renders with:

Property	Value	Notes
Entity color	#e8c547	Amber
Insert halo	2–3px gaussian bloom, amber	Standard insert treatment for amber
Outline	2px #333340	Unchanged
Silhouette feature	Unchanged	Vest ridge / uniform collar — identity persists

No additional markers. No special framing. The player's relationship to this entity has changed; the entity itself has not changed. The amber is the signal, not a badge.

---

6. Animation Tier Transition

6.1 Before Contradiction Discovery — Tier 1

Until the contradiction is discovered, THE FRIEND operates in Tier 1 animation: public daily activities, instantly readable, clearly motivated. The player can observe Kael working cargo and understand "he is working." They can observe Sera at the bar and understand "she is relaxing after shift."

Tier 1 behavior is readable by design. This is important: the player needs to feel like they know Kael before knowing him becomes complicated.

6.2 The Transition Point

THE FRIEND enters Tier 2 animation when the player has seen the contradiction.

Not before. Not based on a timer or tick count. The trigger is epistemic — it is not when Kael has the secret meeting (that always happens), but when the player observes it. The contradiction exists in the simulation from session start; the visual weight of it is unlocked by the player's discovery.

Before discovery: Kael walks, works, drinks at Lera's. All Tier 1. Clearly motivated.

After discovery: Kael still walks and works. But now when he pauses near a doorway, the player reads it differently. The behaviors themselves haven't changed — Kael always paused near doorways sometimes. The player's interpretive frame has changed.

This is the Tier 2 mechanic expressed perfectly: the animation tier boundary is invisible. The player experiences the shift subjectively, not through a visual mode change.

6.3 Behaviors That Become Legible as Tier 2

Once the player has seen the contradiction, previously Tier 1-readable Kael behaviors become Tier 2-legible. The same animation serves both interpretations:

Behavior	Pre-discovery reading	Post-discovery reading
Pausing near corridor B-7	Break / distracted	Checking if the coast is clear
Looking around	Habit / awareness	Watching for the player
Lingering near a crate	Moving cargo / waiting	Exchanging something
Taking an alternate path	Shortest route was blocked	Avoiding someone

The simulation may or may not actually be running the Tier 2 intent behind these behaviors — that's Dudley's domain. What matters for the visual spec is that the player's interpretive state changes the meaning of any Tier 2 behavior they observe.

6.4 Monologue Frequency

Per D-063: post-confrontation, monologue frequency spikes and available topics narrow. This is not a visual change on the entity but is part of the player's experience of THE FRIEND post-discovery. The character's inner voice reacts. This is specified in the copy team's monologue authoring contracts — reference here for completeness.

---

7. Cross-Reference: Entity Color System

THE FRIEND's color transitions are fully governed by the entity color system (Entity Color System spec, #304). The visual system does not need to know about THE FRIEND specifically — it responds to the relationship state the server delivers.

The visual spec obligation is: ensure the staging conditions are met so that THE FRIEND's green-to-amber is the first relationship color change. After that, the color system handles everything automatically.

---

Appendix A — Phased Summary Table

Phase	Trigger	Entity color	Animation tier	Visual changes
Phase 1: Acquaintance	First visible	#6bc9a6 green	Tier 1	None. Identical to any Known NPC.
Phase 2: Trust building	3+ meaningful interactions	#6bc9a6 green	Tier 1	None on entity. Player's contextual knowledge accumulates.
Phase 3a: Contradiction seen	Player observes contradiction	Transitioning	Tier 1 still	0.5s green → amber (#e8c547) fade
Phase 3b: Post-discovery	Amber state locked	#e8c547 amber	Tier 2 behaviors now legible	Amber sustained. No additional markers.

---

Appendix B — Decision Cross-References

Decision	Relevance
D-027	Vertical slice success criteria. #3: "player names an NPC they felt conflicted about" — this spec serves that criterion.
D-033	Entity color = relationship to player. Source of truth for all color values in this spec.
D-034	THE FRIEND production NPC pattern. Source for phase structure and character profiles.
D-044	Visual hierarchy. Entity always dominant. Silhouette feature as recognition signal.
D-047	Two-tier animation system. Tier 1/Tier 2 boundary, invisible to player.
D-052	Character favorite colors — object-layer identification. Phase 2 earned visual detail.
D-063	Confrontation text styling — italic first-person options, 1.5s monologue beat. Post-discovery monologue behavior (not visual, but contextually related).