settled-reach/docs/design/insert-hud-wireframe-v01.md

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

title	description	type	status	ticket	decision_refs	author	created	updated	superseded_by
Insert/HUD Wireframe and Visual Specification — v0.1	Neural lattice insert HUD layout, entity markers, border arrows, and interaction states for the diegetic UI	design	superseded	#314	D-013 D-014 D-019 D-031 D-033 D-048 D-049 D-051 D-056 D-057 D-059 D-065 D-066 D-117	Araminta	2026-02-24	2026-03-13	D-169

SUPERSEDED (2026-06-12, cascade-refocus sweep): superseded by D-169 (implant UI component library) + D-170 (HUD visibility groups). Kept as historical record; do not build against it.

Insert/HUD Wireframe and Visual Specification — v0.1

Ticket: #314 Author: Araminta (Visual Designer) Date: 2026-02-24 Status: Active — feeds #263 (time display client implementation) and #151 (minimap rendering) Visual grammar reference: docs/design/visual-grammar-v01.md (§7 Neural Insert Overlay)

Sprint 26 / D-117: Detective archetype removed. Detective-specific sections (§3.3, §4.2, §5.2, §10.2, §10.3) have been deleted. Remaining content reflects the base lattice profile (smuggler/observer). Smuggler variant retained as reference for the tycoon observer insert design.

---

1. System Architecture

The insert HUD is not a UI panel bolted onto the game. It is the player character's neural lattice — Settled Reach technology that overlays computational data onto the character's perception. Every element on z-layer 6 is diegetic: the character is experiencing this information through their implant, not reading a game interface.

This has direct design consequences:

• The insert does not appear/disappear — it activates and deactivates. The character's lattice is always there; they choose when to engage it.
• Labels use the character's vocabulary, not the game's. The smuggler's insert calls it "The Last Shift."
• The same underlying ObserverSnapshot feeds both variants. One parameterized system: lattice_profile on the snapshot determines which visual mode renders. Stig builds one HUD framework, not two. The variants are rendering configurations, not separate systems.

1.1 Technical Parameters

Parameter	Value
lattice_profile	lattice_baseline
Line weight	1px
Annotation density	Sparse — essential markers only
Passive opacity	60%
Active opacity	85%
Bloom	2–3px gaussian at 40% blend
Chrome color	#c8d0e0

1.2 Z-Layer Position

Insert HUD lives entirely on z-layer 6. It renders above fog (z-layer 5) and below monologue/UI (z-layer 7). The fog shader does not mask it — insert data is computational, not perceptual. Entity markers can appear in fogged areas if the lattice has position data.

---

2. Screen Layout

Base resolution: 1920×1080px

The HUD has four zones:

┌─────────────────────────────────────────────────────────────────────────────┐
│ [STANCE]                                               [PERCEPTION] [TIME] │  ← HUD chrome band (y: 0–80px)
│                                                                             │
│                                                                             │
│                         WORLD VIEW                                          │
│              (insert entity markers rendered here,                          │
│               positioned at entity world locations)                         │
│                                                                             │
│                ↑  ↑  ↑  ↑   border arrows appear here                      │
│ ←              (for off-screen known POIs)                      →           │
│                ↓  ↓  ↓  ↓                                                   │
│                                                                             │
│ [INVENTORY]                                                     [INVENTORY] │  ← inventory band (y: 816–864px)
├─────────────────────────────────────────────────────────────────────────────┤
│                    DIALOGUE BOX (z-layer 7, when active)                    │  ← bottom 20% (y: 864–1080px)
│              [NPC speech]                                                   │
│              [response options]                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Coordinate system: Origin (0,0) is top-left. X increases rightward, Y increases downward. All pixel values at 1920×1080 base; Godot 4 DPI scaling handles other resolutions.

Dialogue box: The bottom 20% (216px) is reserved when dialogue is active. Insert overlay remains visible at 60% of its normal opacity when dialogue is open — the lattice keeps running, the character keeps perceiving. The insert does not suppress during dialogue.

---

3. Time Display

Feeds: Ticket #263 (client time display implementation)

3.1 Position and Dimensions

Property	Value
Container x	1720px → 1904px (right-inset 16px, 184px wide)
Container y	16px → 64px (48px tall)
Background	#0e1218 at 40% opacity — barely-there panel behind text
Typeface	Michroma Regular 400
Alignment	Right-aligned text, right-inset 8px within container

This position is intentionally unremarkable. The player should find it without hunting for it.

3.2 Smuggler Variant

Single line: the time. Informal, just the clock.

                                                           09:42

Property	Value
Text	{HH}:{MM} — 24-hour format, always two digits each
Font size	24px
Color	#c8d0e0 (insert chrome)
Opacity	80% passive, 100% when insert active and entity hover
Y position	Center within container, ~y: 32px

No annotation. The smuggler's lattice gives them the time. That's it.

3.3 Insert-Off Behavior

When insert_active == false:

• Time display dims to 50% of passive opacity
• Background panel disappears entirely
• Text remains — the character always knows what time it is, even without active lattice engagement. Time is ambient lattice output, not targeting output.

The time display is the one persistent insert element. Everything else goes dark on insert deactivation.

---

4. Entity Markers

Entity markers appear at each entity's world position — rendered in world space on z-layer 6. They are not minimap icons in a panel; they annotate the world the player is looking at.

4.1 Smuggler Variant — Social Network View

The smuggler sees their world as a social network. People are dots. Labels are familiar names.

Dot specification:

Property	Value
Shape	Filled circle
Diameter	6px
Color	D-033 relationship color for this NPC
Bloom	2–3px gaussian at 40% blend
Passive state	60% opacity
Active state (hover)	100% opacity + bloom brightens
All non-hovered on hover	40% opacity (focus effect)

The dot sits at the entity's sprite anchor point (center-bottom of the 64×64 canvas). It does not float; it attaches to the entity.

Label specification:

Named NPCs (Kael, Lera, Sera, etc.) always show a casual label. Generic NPCs show no label unless hovered.

Property	Value
Typeface	Michroma 11px
Color	#c8d0e0 at 70% passive, 100% on hover
Position	8px above the dot, horizontally centered
Format	First name only for Known NPCs: Kael
Format	Location nickname for POIs: The Last Shift, Kael's usual spot
Background	None — label is direct on world view. Keep it legible against zone palettes.

Relationship colors applied:

NPC state	Dot color	Label format
Unknown	#4a9ebb teal	No label (generic)
Known/Friendly	#6bc9a6 green	First name
Person of Interest	#e8c547 amber	First name + ? suffix: Torek?
Hostile	#d45d5d red	First name

The smuggler does not see "Person of Interest." To them, amber means "something's off about this person" — not a case file designation.

---

5. Location Labels

Location labels appear at POI anchor points in world space — the entrance tile or center tile of a known location.

5.1 Smuggler Variant

Casual labels, written in the smuggler's vocabulary. These are their personal pins.

Location	Label text
The Last Shift (bar)	The Last Shift
The Terminal (logistics hub)	The Terminal
Maintenance corridor (smuggling space)	B-7 drop (or specific pin label)
Kael's regular position	Kael's usual spot

Property	Value
Typeface	Michroma 12px
Color	#c8d0e0 at 50% — location labels are backgrounded, not foregrounded
Position	Centered on location anchor, 16px above entity-level (below any entity markers at that location)
Visibility	Always visible for known locations, fades in on discovery

---

6. Border Arrows (Off-Screen Navigation)

When a known POI or tracked entity is outside the current viewport, a border arrow appears at the screen edge pointing toward them.

The camera is locked to the player character (D-014). Border arrows are the only navigation affordance for off-screen known locations. There is no minimap panel.

6.1 Arrow Specification

Property	Value
Shape	Equilateral triangle, apex pointing toward screen edge
Size	12px × 10px
Inset from edge	8px
Color	Matches the POI's relationship color (D-033), or #c8d0e0 chrome for neutral known locations
Opacity	60% passive, 100% on hover
Label on hover	Location name (using appropriate variant's label format), Michroma 10px, appears inside-screen adjacent to arrow

Clustering: When multiple POIs are off-screen in similar directions, arrows stack with 4px gap. Maximum 6 arrows per edge before clustering into a count indicator: +3 (Michroma 10px, chrome color).

Decay: If the character has only Suspects confidence about a location (not KnowsOf), the border arrow renders at 30% opacity with a dashed border (1px alternating 2px on / 2px off). "Something might be there."

6.2 Arrow Behavior

Border arrows appear for Known/Friendly NPCs and personal pins. The arrow color is the NPC's relationship color. The label is casual. Unknown NPCs do not generate border arrows.

---

7. Inventory Indicators (Smuggler Only)

Per D-065: the smuggler can carry up to 3–4 physical items. Icons appear in the lower-right corner, above the dialogue band.

Property	Value
Position	x: 1904px (right inset 16px), y: 816px → 856px
Icon size	40×40px
Gap between icons	8px horizontal, right-to-left stacking
Opacity	80% passive, 100% on hover
Empty slots	Not displayed — icons only appear when items are carried
Z-layer	6 (insert layer), but icons are physical objects, not lattice data

Item icons (placeholder descriptions for #314 — actual sprites are a separate ticket):

• Manifest copy: document silhouette
• Corridor access token: hexagonal tag silhouette
• Personal comm log: communication device silhouette

Icons do not disappear when insert is off — they are physical items, not lattice annotations. The character still has pockets whether or not their insert is active.

---

8. Stance Indicator

Both variants show the current movement stance. This is ambient information — the player set it, but may have forgotten.

Property	Value
Position	x: 16px → 180px, y: 826px → 856px (lower-left, above dialogue band)
Typeface	Michroma 11px
Color	#c8d0e0 at 50% — intentionally quiet
Content	Current stance label: WALK / CAREFUL / SPRINT / CROUCH
Behavior	Fades to 30% when dialogue is active

The stance indicator never hides; it just dims. It is the quietest element in the HUD.

---

9. Interaction States

9.1 Insert Active — Default State

Full overlay as described in §3–§8. Entity markers, location labels, border arrows, time display, stance indicator, inventory icons all render at their passive opacity values.

9.2 Insert Inactive (D-056/D-057)

When insert_active == false:

Element	State
Entity markers	Hidden
Location labels	Hidden
Border arrows	Hidden
Bloom	Off — no gaussian pass
Time display	Dims to 50% of passive opacity, background panel disappears
Stance indicator	Remains — 30% opacity
Inventory icons	Remain — physical, not insert data
Cursor	Shape still changes on entity proximity (subconscious physical response per D-056)

The world goes quiet. The character still moves, still perceives physically, still has their items. But the lattice stops annotating.

9.3 Entity Hover (Insert Active)

When the player's cursor enters an entity's interaction radius:

1. Hovered entity's marker brightens to 100% opacity + bloom intensifies to 60%
2. All other entity markers dim to 40% opacity
3. Interaction verb appears: Michroma 13px, D-033 color of the target, positioned 16px above the entity marker
4. Entity label brightens to 100%

The interaction verb is the primary affordance for engagement. The verb appears on the insert layer — it disappears when insert is off, and is unaffected by fog (since it's z-layer 6).

Verb examples: Talk, Observe, Follow, Confront, Examine

9.4 Dialogue Active

When a dialogue interaction is in progress:

Element	Change
Dialogue box	Appears at bottom 20% (y: 864–1080), z-layer 7
Monologue (if active)	Floats above dialogue box at y: ~800–860, z-layer 7
Insert overlay	Reduces to 60% of active opacity — still visible, lattice still running
Entity markers	Remain visible but dimmed 40%
Hovered entity marker	Stays bright — the conversation target stays highlighted
Inventory icons	Remain visible
Time display	Remains
Stance indicator	Dims to 30%

The insert doesn't close during dialogue. The character is still aware of their surroundings.

9.5 High Perception Load (D-059)

When multiple perception modes are active simultaneously, the insert shows diegetic interference:

Property	Value
Effect	Horizontal scan-line distortion
Intensity	5% — subtle, peripheral
Behavior	Periodic (not constant), short bursts, random intervals 2–8 seconds
Applies to	All insert elements simultaneously
Does NOT apply to	UI z-layer 7 (monologue, dialogue)

This is a visual warning, not a mechanical penalty. The player reads it as "the lattice is working hard." It should not be alarming; it should be ambient.

---

10. Wireframe Mockups

10.1 Smuggler Variant — The Last Shift, Evening

The smuggler is in the bar. Kael is nearby (green — Known/Friendly). An unknown dock worker is in the corner (teal). The bar is a known location.

┌─────────────────────────────────────────────────────────────────────────┐
│ CAREFUL                                                         09:42   │
│                                                                         │
│                    ↑ The Last Shift (bar: border direction)             │
│                                                                         │
│                                                                         │
│       ●             ●                                                   │
│     Kael        [player]                      ●                         │
│      (green)     (cream)                   (teal)                       │
│                                                                         │
│                   The Last Shift                                         │
│                (chrome label, centered)                                 │
│                                                                         │
│                                                                         │
│                                                           [manifest][token]│
├─────────────────────────────────────────────────────────────────────────┤
│                     [dialogue box — inactive]                           │
└─────────────────────────────────────────────────────────────────────────┘

Legend:
● = entity dot marker (6px)   Kael = label (Michroma 11px, chrome)
The Last Shift = location label (Michroma 12px, 50% chrome)
[manifest][token] = inventory icons (40×40px, lower-right)
09:42 = time display (Michroma 24px, upper-right)
CAREFUL = stance (Michroma 11px, lower-left, 50%)

---

11. Color Reference Summary

All colors from visual-grammar-v01.md §1.5 and §3.2. Reproduced here for implementation reference.

Use	Hex	Notes
Insert chrome (default)	#c8d0e0	Time display, labels, stance, grid
Entity — Unknown	#4a9ebb	Cool teal. Default NPC state.
Entity — Known/Friendly	#6bc9a6	Soft green. Trusted network.
Entity — POI	#e8c547	Warm amber. Flagged.
Entity — Hostile	#d45d5d	Muted red. Subjective danger.
Player	#e8e0d0	Warm cream.
Unexplored wireframe	#333340	Not used in HUD chrome directly — world layer use
Time panel background	#0e1218 at 40%	Barely-there. Matches zone ambient palette.

Saturation rule: Entity D-033 colors must remain the most saturated elements on screen at all times. Nothing in the insert chrome may compete with entity color saturation (D-044, §3.6 of visual grammar). The chrome is cool grey-white — it frames entity colors, never rivals them.

---

12. Typography Reference

All text is Michroma Regular 400 (Google Fonts). No exceptions (visual-grammar-v01.md §5.4).

Role	Size	Color	Opacity (passive / active)	Z-layer
Time display	24px	#c8d0e0	80% / 100%	6
Entity label (hover)	11px	#c8d0e0	70% / 100%	6
Location label	12px	#c8d0e0	50% / 70%	6
Interaction verb	13px	D-033 target color	95% (always active)	6
Stance indicator	11px	#c8d0e0	50% / 60%	6
Border arrow label (hover)	10px	#c8d0e0	0% / 100% (hover-only)	6

---

13. What This Document Does Not Cover

These are deliberately out of scope for #314. Separate tickets own them.

• Perception mode overlay visual design — thermal, camera feed, etc. (#315 area, depends on D-017/D-048 full spec)
• Monologue display system — typography animation, stacking (#315)
• Sound indicator visual design — fog-edge ping pulse (#317)
• THE FRIEND visual treatment — special relationship visual affordances (#318)
• Minimap panel (if a panel approach is ever adopted — currently border arrows handle navigation, no panel exists in v0.1)
• World map / inter-location navigation — a different system entirely
• Cursor states — specified in D-056, not repeated here

---

Appendix A — Integration Notes for Stig (#263)

For the time display implementation (#263):

1. The time display container is at x: 1720–1904, y: 16–64 (right-inset 16px from 1920px width). These are your anchor coordinates.
2. The ObserverSnapshot needs to expose current game time (hours, minutes) and current day phase. Consult D-031 for the tick-to-time mapping (10 ticks = 1 game-minute).
3. Time display text must be right-aligned within the container. Don't center it — it should feel like a readout in the upper-right corner.
4. The background panel (#0e1218 at 40%) should be a simple NinePatchRect or ColorRect — minimal, no rounded corners.
5. When insert_active == false: set time display modulate.a = 0.5 * passive_opacity and hide the background panel. The text stays; the container chrome disappears.

For the entity marker system (future tickets):

• One marker scene, parametrized by shape (circle), size, color, bloom intensity
• All entity markers use the baseline dot (circle) — no diamond/POI shapes in the base profile
• Bloom intensity driven by relationship color from D-033

---

Appendix B — Decision Cross-References

Decision	Relevance
D-013	Diegetic insert/POI navigation. The HUD IS the neural insert.
D-014	Minimap spec: "dots when close, border arrows for known distant POIs"
D-019	Camera tilt — sprites authored for shallow tilt. Markers sit above entity anchor.
D-031	Time system — tick-to-time mapping, day phases. Feeds §3.
D-033	Entity color = relationship to player. All marker colors source from this.
D-048	Neural insert visual design. Bloom spec, character variants.
D-049	Z-layer 6 = insert overlay. Z-layer 7 = UI/monologue.
D-051	"Settling is placement." Object density as meaning. Insert labels reflect this.
D-056	Cursor states persist when insert-off.
D-057	Entity interaction labels suppressed when insert-off.
D-059	Perception load → scan-line interference at 5%.
D-065	Inventory: 40×40px icons, smuggler-only in v0.1.
D-066	Dual-scale grid. Entity markers anchor to visual tile positions.