settled-reach/docs/design/monologue-display-spec.md

Monologue Display System — Visual Specification

Version: v0.1 (Sprint 13, updated Sprint 14) Author: Araminta (Visual Designer) Date: 2026-02-19 Ticket: #315 Status: Active — constrains copy authoring (#299, #300) and future client monologue UI implementation Foundation: Visual Grammar v0.1 (§5.2, §5.3)

---

1. Typography

1.1 Typeface

Michroma (Google Fonts, Regular 400) — no exceptions. Monologue renders through the same neural insert perception layer as all other text (Visual Grammar §5.4). There is no separate "inner voice font."

1.2 Size and Weight

All sizes at 1080p base resolution. Godot 4 handles DPI scaling.

Variant	Size	Weight	Notes
Standard	13px	Regular 400	Interior voice. Quieter than dialogue (16px).
Urgent	13px	Regular 400	Same size — urgency is communicated through opacity, color, and bloom, not typographic scale.

No bold, no italic, no size variation within a single line. Monologue is the character's unformatted thought stream. Emphasis comes from the writing, not from styling.

1.3 Character-Differentiated Color

Monologue text color reflects the character's register. The detective thinks in cool tones (analytical, institutional). The smuggler thinks in warm tones (social, street-level). These colors are deliberately desaturated — monologue should never compete with D-033 entity colors for visual attention.

Detective:

Variant	Color	Hex	Opacity
Standard	Cool grey-blue	#d0d4e0	85%
Urgent	Bright cool blue	#e0e8f8	100%

Smuggler:

Variant	Color	Hex	Opacity
Standard	Warm grey-cream	#d8d0c4	85%
Urgent	Bright warm cream	#f0e4d4	100%

1.4 Urgent Bloom

Urgent monologue lines receive a subtle bloom pulse: 2px gaussian blur at 30% blend, pulsing between 20% and 40% over a 1.5-second cycle. The pulse begins on fade-in and continues through the hold duration. This is the only visual animation on monologue text.

The urgent recognition chime (D-067, UISounds bus) fires simultaneously with the bloom onset.

---

2. Positioning

2.1 Screen Anchor

Monologue occupies a fixed screen position — not entity-relative. The character's inner voice is not a speech bubble; it exists in the player's perceptual space, not the game world's physical space.

2.2 Placement

Monologue lines are anchored to the lower-left quadrant of the screen, above the dialogue box region.

Property	Value	Notes
Horizontal anchor	Left edge + 5% screen width margin	Left-aligned, clear of screen edge
Vertical anchor	25% from screen bottom	Above dialogue box max height (20%). 5% gap separates monologue from dialogue top edge.
Max text width	50% screen width	Prevents lines from spanning the full screen. At 1920px, this is 960px — comfortably fits 80 characters at 13px Michroma.

2.3 Dialogue Box Relationship

The dialogue box (D-061) occupies the bottom 20% of the screen. Monologue sits directly above it with a 5% gap. This spatial separation is the core mechanic: the character thinks one thing (above, inner) while the NPC speaks another (below, outer).

When dialogue is inactive, monologue lines remain at the same vertical position — as if the dialogue box were present but invisible. The monologue region does not slide down to fill the gap. Consistent positioning trains the player to associate the lower-left quadrant with interior thought.

2.4 Z-Layer

Z-layer 7 (D-049). Topmost rendering layer. Monologue is:

• Never occluded by game world elements (layers 0–4)
• Never affected by fog shader (layer 5)
• Rendered above the insert overlay (layer 6)
• Co-resident with dialogue box and HUD chrome on layer 7

Within layer 7, monologue text renders above the dialogue box but below modal UI (world menu, pause).

---

3. Stacking Rules

3.1 Maximum Visible Lines

3 lines maximum. This is a hard cap. If a 4th line arrives while 3 are displayed, the priority system (§4) determines which line yields.

3.2 Stack Direction

Bottom-up. The newest line appears at the bottom of the monologue region (closest to the dialogue box). Older lines shift upward. This keeps the freshest thought spatially adjacent to the dialogue it may contradict.

  [oldest line — fading out]        ← shifts up, fading
  [middle line]                     ← shifts up
  [newest line — fading in]         ← appears here
  ─────────────────────────────────
  [dialogue box]                    ← bottom 20% of screen

3.3 Shift Animation

When a new line enters and pushes older lines upward, the vertical shift takes 0.2 seconds (ease-out). Lines do not teleport to their new position.

3.4 Line Spacing

4px vertical gap between stacked lines. At 13px font size, this gives 17px per line slot — compact but legible.

---

4. Priority System

4.1 Priority Tiers

Monologue lines belong to one of three tiers, in descending priority:

Priority	Tier	Examples
1 (highest)	Observation	Entity recognition, anomaly detection, item discovery, environmental deduction
2	Atmosphere	Zone commentary, ambient thought, character reflection, idle musing
3 (lowest)	Tutorial	System hints, control reminders, first-time explanations

4.2 Overflow Behavior

When a new line arrives and the display is at capacity (3 lines):

1. If the new line's priority is higher than the lowest-priority displayed line: The lowest-priority displayed line immediately begins its fade-out (compressed to 0.3s instead of normal 1.0s). The new line enters at the bottom after the evicted line clears.

2. If the new line's priority is equal to or lower than all displayed lines: The new line is deferred — queued and displayed when a slot opens naturally. Maximum queue depth: 5 lines. If the queue is full, the lowest-priority queued line is silently dropped.

3. Same-priority collision: Within the same tier, newer lines take precedence over older ones. An observation evicts an older observation before it evicts an atmosphere line.

4.3 Urgent Override

Urgent monologue lines (observation tier only) always display immediately, evicting the lowest-priority visible line regardless of tier match. If all 3 visible lines are observation-tier, the oldest observation line is evicted.

---

5. Fade Animation

5.1 Timing

Each line fades independently — lines do not synchronize their lifecycles.

Phase	Duration	Easing
Fade-in	0.3s	Ease-out (quick arrival, not instant)
Hold	4.0s	—
Fade-out	1.0s	Ease-in (slow, contemplative departure)

Total visible duration: 5.3 seconds per line.

5.2 Opacity Curve

• Fade-in: 0% → target opacity (85% standard, 100% urgent) over 0.3s
• Hold: Target opacity sustained for 4.0s
• Fade-out: Target opacity → 0% over 1.0s

5.3 Eviction Fade

When a line is evicted by a higher-priority line (§4.2), its fade-out is compressed from 1.0s to 0.3s. This fast exit makes room for urgent content without feeling jarring.

5.4 Rapid Succession

If multiple monologue lines fire within 0.5 seconds of each other (e.g., multi-part observation), each line staggers by 0.15 seconds. The second line begins its fade-in 0.15s after the first, the third 0.15s after the second. This prevents a wall of text appearing simultaneously while keeping the burst feeling connected.

---

6. Character Differentiation

6.1 Design Principle

The smuggler and detective occupy the same world, see the same events, but experience them through different cognitive registers. Monologue is where this divergence is most visible. Per D-043 ("functional warmth"), the smuggler's interior world is warmer — social awareness, practical assessment. The detective's is cooler — analytical distance, procedural framing.

This is expressed through color temperature only. Size, position, stacking, animation, and font are identical between characters. The difference is subtle and accumulative — not a jarring mode switch.

6.2 Color Summary

Character	Standard	Urgent	Register
Detective	#d0d4e0 at 85%	#e0e8f8 at 100%	Cool blue-grey. Institutional. Observational.
Smuggler	#d8d0c4 at 85%	#f0e4d4 at 100%	Warm cream-grey. Social. Practical.

6.3 Implementation Note

The active character's lattice_profile (from ObserverSnapshot) determines which color set is used. lattice_augmented (detective) → cool palette. lattice_baseline (smuggler) → warm palette. No runtime switch within a session — character is selected at game start.

---

7. Line Length Constraint

7.1 Hard Limit

80 characters per line, maximum. This is a display constraint, not a guideline.

At 13px Michroma on a 1080p display with 50% max text width (960px), 80 characters fits comfortably with margin. Lines exceeding 80 characters will be truncated at the last word boundary before the limit — no mid-word breaks.

7.2 Copy Team Contract

All monologue content authored for The Settled Reach must respect this constraint:

• Maximum: 80 characters per line (including spaces and punctuation)
• Target: 40–65 characters per line (comfortable reading rhythm)
• Minimum: No minimum, but lines under 20 characters should be rare — they waste visual space

Multi-line monologue thoughts (e.g., a two-part observation) should be authored as separate lines, each respecting the 80-character limit, delivered via the rapid succession stagger (§5.4).

7.3 Validation

Content tooling should flag lines exceeding 80 characters at authoring time, not at runtime. Runtime truncation is a fallback, not a workflow.

---

8. D-033 Cross-Reference — Color Clash Analysis

8.1 Entity Relationship Colors

State	Hex	Saturation	Lightness
Unknown/Neutral	#4a9ebb	~45%	~52%
Known/Friendly	#6bc9a6	~40%	~60%
Person of Interest	#e8c547	~75%	~59%
Hostile/Dangerous	#d45d5d	~55%	~60%
Static objects	#8b8ba0	~10%	~58%

8.2 Monologue Text Colors

Variant	Hex	Saturation	Lightness
Detective standard	#d0d4e0	~15%	~85%
Detective urgent	#e0e8f8	~38%	~92%
Smuggler standard	#d8d0c4	~12%	~81%
Smuggler urgent	#f0e4d4	~30%	~89%

8.3 Clash Assessment

No clashes. Monologue text occupies the high-lightness, low-saturation range (L: 81–92%, S: 12–38%). Entity colors occupy the moderate-lightness, moderate-to-high saturation range (L: 52–60%, S: 10–75%). These color spaces do not overlap.

The closest potential overlap is between static object grey (#8b8ba0, low saturation) and monologue text — but the lightness gap (58% vs 81%+) maintains clear separation, and monologue text on z-layer 7 never spatially overlaps with entity sprites on z-layer 3.

8.4 Warm Amber Adjacency

The smuggler's urgent text (#f0e4d4) and the Person of Interest amber (#e8c547) share a warm register. This is thematically appropriate — the smuggler's heightened awareness (urgent monologue) coincides with the visual system flagging someone as noteworthy. They are not visually confusable: the text is desaturated near-white cream, while amber is a saturated gold-yellow at much lower lightness.

---

Appendix A — Decision Cross-References

Decision	Relevance to this spec
D-016	Monologue as core perception/atmosphere system. Defines function and character variance.
D-033	Entity relationship colors. Cross-referenced in §8 for clash avoidance.
D-043	"Functional warmth" art direction. Grounds character color differentiation (§6).
D-044	Visual hierarchy (entity > object > structure). Monologue must not compete.
D-049	Z-level rendering stack. Monologue is z-layer 7 (§2.4).
D-061	Dialogue box layout. Monologue spatial relationship defined in §2.3.
D-066	Dual-scale grid. Positioning uses screen-relative units, not tile units.
D-067	Recognition chime fires at cognitive delay onset, coinciding with urgent monologue bloom.

Appendix B — Quick Reference for Copy Team

Constraint	Value
Max characters per line	80 (hard limit)
Target characters per line	40–65 (comfortable)
Max visible lines	3
Line hold duration	4.0 seconds
Total visible time	5.3 seconds
Multi-line stagger	0.15s between lines
Priority: observation > atmosphere > tutorial	Observation always displays; tutorial may be deferred