settled-reach/docs/design/environmental-text-standards.md

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

title	description	type	status	ticket	decision_refs	author	created	updated
Environmental Text Visual Standards	Visual rules for signage, terminals, and news tickers rendered as world-layer text in Sova Transit	design	active	#334	D-036 D-043 D-044 D-049 D-051 D-066	Araminta	2026-02-20	2026-02-20

Environmental Text Visual Standards

Version: v0.1 (Sprint 14) Author: Araminta (Visual Designer) Date: 2026-02-20 Ticket: #334 Status: Active — constrains world-layer text implementation and copy authoring Foundation: Visual Grammar v0.1 (§5), Text Display Hierarchy (#316), Decisions D-036, D-049, D-043

---

1. What Environmental Text Is (and Isn't)

Environmental text is text that exists in the physical world of Sova Transit District — on walls, above terminals, scrolling across displays. It is not HUD, not dialogue, not monologue. It is part of the same world layer that contains crates, chairs, and NPCs.

The key distinction: if a sign would survive the neural insert being switched off, it is environmental text. If it requires the insert to display, it belongs in the HUD layers.

In practice, environmental text renders in the world layer (z-layers 2–4) and is subject to overhead occlusion rules. It is NOT exempt from the fog shader — if a sign is in an unexplored area, the player cannot read it.

All environmental text renders in Michroma — the same typeface as all other game text. The fiction is that all text in the world is mediated through the character's insert perception layer. There is no "world handwriting" typeface separate from the insert-layer font.

---

2. Signage

2.1 Character Limits

Sign type	Max characters	Notes
Zone identifier (primary)	20 chars	Facility name, zone designation
Zone identifier (secondary)	30 chars	Sublevel, sector, unit designation
Directional/wayfinding	15 chars	Single-line, all-caps convention
Safety/notice	40 chars	Two-line max, 20 chars per line
Personal/informal (posted notice)	60 chars	More casual, can be three lines

Hard limit rationale: Signs at 64px tile width render at 11px Michroma. At this size, ~10–12 characters fit per 64px. Signs wider than ~3 tiles (192px) become disproportionately large relative to the world. Character limits enforce realistic sign-making.

2.2 Visual Treatment

Property	Value	Notes
Font	Michroma Regular 400	No exceptions
Font size	11px	At 1080p base
Z-layer	2 (wall surface) or 4 (overhead)	Depends on mounting position
Primary color	#8899aa	Concordat Standard signage
Informal color	#9aa890	Van Maanen's Star vernacular or personal notices
Opacity	70% for formal, 65% for informal	World layer — subordinate to entities
Case	ALL CAPS for formal zone signage	Standard for institutional text
Case	Mixed case for informal and vernacular	More human, less bureaucratic

2.3 Mounting Position

Wall-mounted (z-layer 2): Signage on vertical wall surfaces renders as part of the wall face. Y-sorted with the wall, not with entities. The sign appears at approximately 1.5–2 visual tile height (upper third of wall face in the tilt view).

Overhead (z-layer 4): Suspended signs, hanging banners, and ceiling-mounted displays render in the overhead layer. These are subject to the semi-transparent occlusion rule (70% opacity when above entities/player). An NPC walking under a suspended sign becomes partially visible through the sign's opacity.

Floor-mounted (z-layer 0–1): Painted floor markings, directional arrows, hazard lines. These render under everything and are walked over. No occlusion consideration.

2.4 Bilingual Sign Treatment

When a sign has both Concordat Standard and Van Maanen's Star vernacular text:

• Concordat Standard: primary size (11px), 70% opacity
• Van Maanen's Star vernacular: secondary size (9px), 50% opacity, rendered below the primary line
• Both in Michroma. The size + opacity difference signals language register without a separate "handwriting" font.
• 2px vertical gap between language lines.

Only signs explicitly serving both audiences carry both languages. Official Commission signage is Concordat Standard only. The Last Shift menu and informal worker notices are Van Maanen's Star vernacular only.

---

3. Terminals

3.1 Two-State Model

Terminals exist in two visual states depending on player proximity and interaction.

State 1 — Ambient (player at range, not interacting):

The terminal sprite displays a short ambient identifier: equipment type + designation code. This is always visible within LOS, no interaction required. It is the equivalent of a label on a machine — something a worker in this district would glance at to orient themselves.

Property	Value
Content	1–2 words + code (e.g., "MANIFEST — TK-07")
Font	11px Michroma
Color	#8899aa
Opacity	60%
Z-layer	4 (overhead, above terminal sprite)
Visibility range	Within LOS, up to ~4 visual tiles (~256px at 64px/tile)

State 2 — Active (player adjacent, Observe/Interact triggered):

When the player triggers Observe on a terminal, the full content becomes readable. This is the only time environmental text content transitions — the ambient identifier expands to full text.

Property	Value
Content	Full terminal display — up to ~12 lines
Font	13px Michroma
Color	#a8b8c8
Opacity	85%
Z-layer	4
Max width	200px floating block
Text wrapping	Word-wrap within 200px
Dismissal	Player moves away (WASD)

Transition between states: No animation. The ambient identifier is replaced by the active block when the Observe verb fires. The opacity increase (60% → 85%) and size increase (11px → 13px) signal the mode change without a sliding panel.

3.2 Terminal Content Format

Terminal text is formatted as structured data — this is a computer display, not prose.

[HEADER LINE IN ALL CAPS]
Field:    Value
Field:    Value
---
Additional section

The Michroma font at 13px with #a8b8c8 at 85% renders this structure clearly. Colon-separated fields mimic insert data formatting and reinforce the diegetic conceit.

Character limits per line: ~25 characters at 200px max width, 13px Michroma. Content authors should target 20 characters per line for comfortable reading.

3.3 Terminal Icon (Insert Layer)

When the player's insert is active and a terminal is within interaction range (~2 visual tiles), the insert may overlay a small geometric icon on the terminal — a 4px cross or bracket indicating "this is interactive." This is insert data (z-layer 6), not environmental text (z-layer 4). It renders regardless of whether the player is looking at the terminal.

The insert icon uses the standard insert chrome color (#c8d0e0 at 80% opacity). If the terminal has flagged data (e.g., manifest discrepancy), the icon shifts to amber #e8c547.

---

4. News Tickers

4.1 Overview

News tickers are ambient scrolling text elements attached to specific display fixtures in the scene. They are world-layer content — not HUD overlays. The player must physically approach and observe them.

News tickers serve two functions:

1. World texture: Makes the station feel like a living, connected place (Commission bulletins, interstellar news)
2. Incidental information: Occasionally carries plot-relevant data the player can discover by paying attention

The player is never required to read a news ticker to progress. When a ticker carries relevant information, the character's monologue will comment on it (via observe_anomaly or enter_location trigger) — the player doesn't have to stare at a scrolling display.

4.2 Visual Treatment

Property	Value
Z-layer	4
Font	10px Michroma
Color	#8899aa
Opacity	55%
Language	Concordat Standard
Scroll direction	Right-to-left
Scroll speed	30px/second
Loop	Yes — repeating
Pause on proximity	Yes — when player within 2 visual tiles, scroll pauses

Why 55% opacity: Tickers are the most ambient environmental text element. They must not draw attention during active gameplay. A player engaged with NPCs should not be distracted by scrolling text in their peripheral vision. 55% opacity makes them effectively invisible until the player deliberately turns toward them.

Pause on proximity: When the player stands within 2 visual tiles of a ticker display, the scroll pauses to allow reading. This rewards deliberate attention without requiring the player to chase scrolling text.

4.3 Content Length

News ticker content is authored in segments:

• Segment: A complete sentence or news item, max 80 characters
• Gap: A ———— separator between segments (3–4 em-dashes, full width)
• Loop depth: 3–5 segments per ticker. More segments means longer before repeating — less metagameable.

Segments scroll sequentially separated by the gap. The player who watches a full loop has seen all content for that ticker.

4.4 Fixture Attachment

Each news ticker is attached to a specific fixture sprite (terminal, display panel, wall screen). The ticker text renders in a Rect overlaid on the upper portion of the fixture sprite. The fixture artist marks the text bounds when designing the fixture.

For v0.1 (colored rectangle stage), the ticker is a floating text element positioned above the fixture's placeholder rectangle. When sprite art arrives, the artist provides the correct text bounds.

---

5. Rendering Rules Summary

5.1 Z-Layer Assignment

Text sub-type	Z-layer	Occlusion?	Fog-affected?
Floor signage	0–1	No (under entities)	Yes
Wall signage	2	Via y-sort	Yes
Terminal ambient ID	4	Semi-transparent occlusion	Yes
Terminal active display	4	Semi-transparent occlusion	Yes
News ticker	4	Semi-transparent occlusion	Yes
Insert terminal icon	6	No (insert layer)	No

Fog-affected: Yes means the text is invisible in unexplored areas. The player cannot read a sign they haven't walked past. This is correct and intentional.

5.2 Entity Occlusion Rule

Environmental text on z-layer 4 (overhead) renders at 70% opacity maximum — the same rule as all overhead layer content. An entity moving below an overhead sign remains partially visible through the sign. This is the "local information gap within a known space" design (D-049 §4.4).

Environmental text on z-layer 2 (wall surface) is y-sorted with entities. If an entity is standing in front of a wall sign, the sign is occluded by the entity. This is correct — the entity is always the primary visual element (D-044).

5.3 Text Never Occludes Entities

Entities are always visually dominant (D-044: entity > object > structure). Environmental text never achieves enough opacity to obscure entity colors. If a layout choice places text where it would overlap an entity, the text loses — reduce opacity or reposition. The entity's D-033 color must remain readable.

---

6. Language by Context — Decision Matrix

Location	Formal element	Informal element
The Terminal (logistics hub)	Concordat Standard	Van Maanen's Star vernacular where workers have added personal notices
The Last Shift (bar)	Concordat Standard (Commission notices, if any)	Van Maanen's Star vernacular (menu, worker notices, personal signs)
Maintenance corridors	Concordat Standard (safety markings)	Van Maanen's Star vernacular (informal worker notes)
Cargo containers	Concordat Standard (manifests, labels)	None
Personal effects area	Neither — no formal signage	Van Maanen's Star vernacular if labeled

Decision rule: Formal = the institution did it. Informal = a person did it. The institution writes in Concordat Standard. People write in Van Maanen's Star vernacular. When you're not sure, ask who made the sign.

---

Appendix A — Decision Cross-References

Decision	Relevance
D-036	Sova Transit District / Van Maanen's Star. Concordat Standard vs Van Maanen's Star vernacular framework.
D-043	"Functional warmth" art direction. Environmental text is world texture, not decoration.
D-044	Visual hierarchy. Environmental text is subordinate to entities at all times.
D-049	Z-level rendering stack. Layer assignments for all text types.
D-051	Settling is placement. Environmental text density reflects the district's history.
D-066	Dual-scale grid. 64px tiles → ~10–12 characters per tile at 11px Michroma.

Appendix B — Quick Reference for Copy Team

Format	Max chars/line	Lines	Language
Zone signage (primary)	20	1	Concordat Standard
Zone signage (secondary)	30	1	Concordat Standard
Directional	15	1, ALL CAPS	Concordat Standard
Safety notice	20	2	Concordat Standard
Informal posted notice	20	3	Van Maanen's Star vernacular
Terminal active (per line)	25	Up to 12	Either, per context
News ticker (per segment)	80	1	Concordat Standard

Appendix C — Quick Reference for Stig

Sub-type	Z-layer	Font	Size	Hex	Opacity
Formal signage	2 or 4	Michroma	11px	#8899aa	70%
Informal signage	2 or 4	Michroma	11px	#9aa890	65%
Terminal ambient	4	Michroma	11px	#8899aa	60%
Terminal active	4	Michroma	13px	#a8b8c8	85%
News ticker	4	Michroma	10px	#8899aa	55%
Insert terminal icon (active)	6	—	4px glyph	#c8d0e0	80%
Insert terminal icon (flagged)	6	—	4px glyph	#e8c547	80%