settled-reach/docs/design/tell-visual-expression.md

title, description, type, status, ticket, decision_refs, author, created, updated

title	description	type	status	ticket	decision_refs	author	created	updated
Tell Visual/Behavioral Expression	Specification for five NPC tell categories mapped to Tier 2 movement behaviours with intensity scaling	design	active	#251	D-016 D-024 D-033 D-044 D-047	Araminta	2026-02-20	2026-03-05

Tell Visual/Behavioral Expression — Specification

Version: v0.1 (Sprint 14) Author: Araminta (Visual Designer) Date: 2026-02-20 Ticket: #251 Status: Active — visual design input to server-side tell behavior (Dudley, future sprint); constrains monologue content (Mellanie) Foundation: Visual Grammar v0.1 (§6, animation tier system), THE FRIEND Visual Treatment (#318), Decisions D-024, D-047

---

1. What This Document Covers

The tell system (D-024 axis: Tell System) defines behavioral signals that NPCs exhibit when their underlying state creates tension with their public behavior. A nervous NPC shows nervousness. An angry NPC shows anger. These are not metatextual UI indicators — they are behavioral patterns in the top-down renderer.

Araminta's scope: How tells look at the tile level — what movement patterns, position choices, and timing behaviors constitute each tell category. This is the design input that Dudley uses to implement movement and pathfinding modifiers on the server.

Dudley's scope: Implementing these behaviors as simulation-side movement decisions, pathfinding priority changes, and activity state modifications.

Mellanie's scope: Writing the monologue lines that fire when the player observes a tell via observe_npc trigger. In v0.1, tell expression is primarily via monologue text — the server emits a monologue trigger when a tell is active and the player observes the NPC.

The tell is not visible as a UI element. There is no icon, no indicator, no animation label. The tell manifests as a behavioral pattern that the player may or may not notice, may or may not interpret correctly. The monologue (if it fires) provides the character's interpretation.

---

2. Tell Categories and Animation Tier Mapping

D-024 defines the tell system axis on the NPC model. This spec identifies 5 tell categories derived from the axis. Each maps to one or more Tier 2 behavioral expressions (D-047 animation tier system). The mapping is based on what the tell would look like from a top-down view on a character operating in a public space.

Tell category	Internal state	Primary Tier 2 behavior	Secondary behavior	Notes
Nervous	Stress above tolerance threshold, concealment at risk	Movement hesitation + route checking	Proximity avoidance to specific zones	Most common for characters with active secrets
Angry	High stress, contested relationship, tolerance reached	Accelerated/direct movement	Short dwell times	Anger in the Settled Reach is internalized — no outburst in public
Friendly (suppressed)	Wanting to interact but constrained	Lingering near character / zone	Approach-and-withdraw pattern	Friendly tell occurs when NPC wants contact but can't initiate
Guarded	Protective of information or person	Proximity positioning	Route shielding	NPC places themselves between player and something/someone
Routine deviation	Normal routine interrupted by higher priority	Unexpected location, unexpected timing	Unusual activity for current day phase	The broadest tell — anything outside the established pattern

---

3. Tier 2 Behavioral Vocabulary

These are the Tier 2 animation states that serve as tell expressions. Each behavior is observable in the top-down renderer and ambiguous in isolation — the player sees what but not why.

3.1 Movement Hesitation

Appearance: NPC stops at a tile boundary for 0.5–2.0 seconds before entering a room, doorway, or open space. The pause is distinct from the NPC's Idle animation — it is directional (NPC is facing the destination, not standing neutrally). No heading change during the pause.

Ambiguity: Break? Waiting for someone? Checking the space? Nervous? All are plausible.

Server implementation note: A PathRequest with a brief pre-entry wait injected before the final move into the destination tile. Duration variable by stress level (higher stress = longer hesitation, up to 2.0s).

Which tells use it:

• Nervous: Primary expression. NPC hesitates before entering a space they associate with risk.
• Guarded: Secondary expression. NPC hesitates before committing to a route past a target zone.

3.2 Route Deviation

Appearance: NPC takes a longer path between two points than the direct route. The direct route passes by a certain person, object, or zone; the NPC routes around it. To a player who doesn't know the direct route, this looks like normal navigation. To a player who has mapped the space, this looks wrong.

Ambiguity: Corridor blocked? Just habit? Avoiding someone? Picking something up along the way?

Server implementation note: Pathfinding with an avoidance weight on specific tiles associated with the avoided entity/zone. The alternate route is valid — just longer than necessary. The NPC arrives at their destination; they just took a detour.

Which tells use it:

• Nervous: NPCs nervous about a person route around that person.
• Guarded: NPCs protecting a location route to block others from approaching it via the most direct path.
• Routine deviation: Primary expression. Route is different from the established pattern for this NPC at this day phase.

3.3 Lingering

Appearance: NPC arrives at a location but does not begin a Tier 1 activity. They stand in the area, possibly using Idle animation, for longer than transit time would explain. The NPC's presence in the location appears unmotivated — they have not started working, eating, or talking.

Ambiguity: Waiting for someone? Thinking? Watching the door? On a break they didn't plan?

Server implementation note: After completing PathRequest to a destination, inject an unmotivated Idle activity state before assigning the next DailyRoutine activity. Duration variable by tell intensity. The NPC is physically present but not executing their scheduled behavior.

Which tells use it:

• Friendly (suppressed): Primary expression. NPC has reason to want contact with the player but cannot initiate. They linger near the player's likely path.
• Nervous: Secondary expression. NPC lingers near an exit or junction (choosing a direction).
• Guarded: Primary expression. NPC lingers near the person or thing they are protecting — present without clear activity.

3.4 Approach-and-Withdraw

Appearance: NPC moves toward a character or location, stops within ~3 tiles, pauses, then moves away without initiating interaction. This is a two-step Tier 2 behavior — approach (pathfinding toward target), hesitation (brief stop), withdrawal (pathfinding to alternate destination). The complete sequence takes 4–8 seconds.

Ambiguity: Changed their mind? Forgot something? Lost nerve? Saw something that made them reconsider?

Server implementation note: Two sequential PathRequest instances with an unmotivated Idle state (1–2s) between them. First request targets a tile near the goal entity/zone. Second request targets a tile away from it.

Which tells use it:

• Friendly (suppressed): Primary expression. The NPC wanted to speak with the player but couldn't bring themselves to do it.

3.5 Grouping (Proximity Positioning)

Appearance: NPC persistently positions themselves near a specific entity or zone without a Tier 1 activity justifying the proximity. Unlike lingering (which is about staying in one spot), grouping behavior involves movement that tracks a moving target — the NPC adjusts their position as the other entity moves.

Ambiguity: Friends? Colleagues? Monitoring? Protecting?

Server implementation note: Pathfinding goal shifts dynamically based on target entity position — maintain ~2–3 tile proximity without entering interaction range. This is distinct from escorting (which is intentional) or conversation (which has its own state).

Which tells use it:

• Guarded: Primary expression. NPC positions themselves between the player and a protected entity.
• Nervous: Secondary expression. NPC unconsciously stays near someone they trust when stressed.

3.6 Avoidance

Appearance: NPC reacts to the player's (or another entity's) presence by increasing distance. When the player enters a zone, the NPC finds a reason to be in a different part of it, or exits. This is distinguishable from normal zone movement because the timing correlates with the player's arrival — but correlation is not confirmation.

Ambiguity: Coincidental? Habit? Assigned to another area? Afraid?

Server implementation note: On player entry to zone, if tell is active, NPC's current ActivityTarget is replaced with one on the far side of the zone or in an adjacent zone. The replacement looks like a routine update — there is no visual signal of the change. Timing threshold: avoidance triggers within 3 ticks of player zone entry.

Which tells use it:

• Nervous: Secondary expression. NPC avoids the person they are nervous about.
• Guarded: Secondary expression. NPC moves away from the player to avoid revealing the protected entity by their own proximity.

---

4. Tell Category → Behavior Matrix

Tell category	Movement hesitation	Route deviation	Lingering	Approach/withdraw	Grouping	Avoidance
Nervous	●● Primary	● Secondary	● Secondary	—	● Secondary	● Secondary
Angry	—	—	—	—	—	● Primary
Friendly (suppressed)	—	—	●● Primary	●● Primary	—	—
Guarded	● Secondary	● Secondary	●● Primary	—	●● Primary	● Secondary
Routine deviation	—	●● Primary	●● Primary	—	—	—

●● = primary expression, ● = secondary expression, — = not used.

Angry tell note: Anger in the Settled Reach is internalized in public spaces. An angry NPC does not have an outburst. They move faster (shorter dwell times, quicker route execution), speak shorter sentences (Mellanie's domain), and avoid the person they are angry with if they can manage it. Avoidance is the primary behavioral tell. There is no raised fist or stamped foot. The station is a workplace; people here manage.

---

5. Tell Intensity — Scaling the Visual Weight

Tell behaviors scale in intensity based on the NPC's current stress level or trigger severity. The intensity affects duration and frequency, not the type of behavior.

Intensity level	Server trigger	Hesitation duration	Linger duration	Route deviation
Low	StressAboveThreshold barely met	0.5s	3–5s	Minor (+10% path length)
Medium	Stress significantly elevated	1.0s	5–10s	Moderate (+20–30% path length)
High	DuringActivity / NearSpecificEntity triggered	1.5–2.0s	10–15s	Major (+50%+ path length)

High-intensity tells are rare. If every NPC is visibly nervous all the time, the signal degrades. Tells are most powerful when they occur against a background of normal behavior. The player must earn the observation by paying attention.

---

6. Tell Recognition — Monologue as the Interpretation Layer

In v0.1, tell expression in the renderer is the behavior. The monologue is the character's interpretation.

The player sees: An NPC hesitating before entering the cargo office. The character thinks (monologue): "She stopped before going in. Like she needed to decide something." (Observation tier monologue, observe_npc trigger, tell active for Nervous category)

The monologue fires when:

1. The player is observing the NPC (cursor hover / Observe verb)
2. A tell is active on that NPC
3. The character's knowledge state is sufficient to notice (basic observation — no special knowledge required for surface-level tell recognition)

The monologue does NOT confirm the tell's meaning. It describes what was seen, in the character's voice, without resolving the ambiguity. The detective's monologue and the smuggler's monologue for the same tell will interpret it through different cognitive registers (Mellanie's domain).

---

7. THE FRIEND's Tell Trajectory

7.1 Kael Davan (Smuggler's FRIEND)

Pre-discovery: Kael exhibits routine deviation tell — he has a regular dock schedule but occasionally takes longer routes. In Phase 1 and Phase 2, this is unnoticed or attributed to route preference. The tell is present from session start.

Contradiction seen: Kael in restricted corridor meeting. The player observes the meeting itself — this is not a tell but a direct observation. After the meeting, Kael's nervous tell activates at higher intensity (movement hesitation, avoidance of the player). The behaviors the player may have noticed but ignored before now carry new meaning.

Post-discovery: Kael's tell pattern becomes legible. The approach-and-withdraw the player may have seen once (Kael walking toward the dock, pausing, turning) now reads as Kael wanting to say something but being unable to. The player interprets the same behavior through a new frame.

7.2 Sera Venn (Detective's FRIEND)

Pre-discovery: Sera exhibits avoidance tell around Torek Lintar. She routes around him, leaves when he enters The Last Shift. This is observable from the start — but without context, the player reads it as social preference.

Contradiction understood: The player makes the connection: Sera's avoidance of Torek correlates with Kael's manifest discrepancies. Sera knows something and is avoiding the person who would use that information.

Post-discovery: Sera's guarded tell (proximity positioning near Naia, avoidance of Torek and the detective) becomes legible as protective behavior. The detective character has a trained observation skill — they should notice this. The monologue should reflect recognition ("She's not avoiding him. She's keeping herself between him and something.").

---

8. Scope Boundaries

In scope (Araminta / this spec):

• What tells look like as tile-level movement patterns
• Mapping of tell categories to Tier 2 behaviors
• Intensity scaling guidance

In scope (Dudley / server implementation):

• Implementation of movement hesitation via PathRequest wait injection
• Route deviation via pathfinding avoidance weights
• Lingering via unmotivated Idle activity state
• Approach-and-withdraw via two sequential PathRequests with pause
• Grouping via dynamic proximity pathfinding target
• Avoidance via zone-entry reactive ActivityTarget replacement
• TellSystem component and TellTrigger matching (StressAboveThreshold, NearSpecificEntity, DuringActivity, TimeOfDay, Always)

In scope (Mellanie / monologue content):

• Monologue lines for each tell category, per character (observe_npc trigger + tell active)
• Maintaining ambiguity in the monologue — describing behavior without confirming intent
• Character-differentiated interpretation (detective reads analytically; smuggler reads socially)

---

Appendix A — Decision Cross-References

Decision	Relevance
D-024	NPC generation model. Tell system axis definition. 5 tell categories. TellTrigger model.
D-047	Two-tier animation system. All tell behaviors are Tier 2 expressions.
D-033	Entity color. No tell modifies entity color — tells are behavioral, not chromatic.
D-016	Internal monologue as perception bridge. Monologue fires on observed tell.
D-044	Visual hierarchy. Tells are behavioral, not decorative — no overlays, no icons.

Appendix B — Quick Reference for Dudley

Tier 2 behavior	Server mechanism	Trigger
Movement hesitation	Pre-entry wait in PathRequest	StressAboveThreshold, NearSpecificEntity
Route deviation	Pathfinding avoidance weight on specific tiles	StressAboveThreshold, DuringActivity
Lingering	Unmotivated Idle between PathRequest and DailyRoutine activity	NearSpecificEntity, Always (for guarded)
Approach-and-withdraw	Two sequential PathRequests + Idle (1–2s) between	NearSpecificEntity (friendly suppressed)
Grouping / proximity positioning	Dynamic pathfinding target tracking entity	NearSpecificEntity (guarded)
Avoidance	Zone-entry reactive ActivityTarget replacement	NearSpecificEntity, StressAboveThreshold

Intensity scaling: Hesitation duration 0.5s / 1.0s / 1.5–2.0s. Linger duration 3–5s / 5–10s / 10–15s. Route deviation +10% / +20–30% / +50%+ path length. Intensity driven by stress value distance above threshold.