settled-reach/docs/workshops/generator-architecture/araminta-round1.md

title, description, type, status, workshop, agent, round, created

title	description	type	status	workshop	agent	round	created
Araminta Round 1 — Visual Coherence Constraints	Visual coherence constraints for chunk fill and zone palette requirements	workshop	archived	generator-architecture	araminta	1	2026-02-27

Generator Architecture Workshop — Round 1: Araminta

Visual Coherence Constraints for Chunk Fill

Author: Araminta (Visual Designer) Date: 2026-02-27 Workshop: Generator Architecture (Ticket #562) Source documents: visual-grammar-v01.md, spatial-layout-terminal-v01.md, spatial-layout-bar-v01.md, spatial-layout-gate-v01.md, spatial-layout-smuggling-corridors-v01.md, decisions/content.md (#153 D-record = D-093/D-094), decisions/architecture.md

---

What the Visual Domain Requires from the Generator

The visual grammar (visual-grammar-v01.md) establishes a system where the environment communicates location, not drama (D-045). This places a strong constraint on the generator: every piece of generated content must resolve to a zone palette, a zone era, and an access tier. Without those three anchors, generated chunks will look random regardless of how technically correct the spatial math is.

My domain requirement is simple: the generator must produce chunks that a player can read at a glance. Read = know where they are, know what tier of access they're in, know where the walls and cover are, and know where people might be watching from. Everything below serves that requirement.

---

1. Visual Coherence Constraints for Chunk Fill

1.1 Zone Palette Is the Primary Coherence Anchor

Each chunk inherits a single zone palette. Zone boundaries are set at block level (64×64 visual tiles), not chunk level. A chunk does not have a mixed palette. If two zones meet at a block boundary, the visual transition happens between chunks, never within a chunk.

Locked zone palettes (D-093, visual grammar §1):

Zone	Floor hex	Ambient	Fixture color	Era
Gate cluster	#b8bec4 (surface)	#0a1222 fog tint	#f2f4ff cold LED	Era 3
Terminal	#1a1e24	#0d1520	#c8d8f0 cool institutional	Era 1/2
Bar	#1e1912	#200c04	#f0b840 amber	Era 3
Maintenance	#181818	#101214	#d0d8e0 cold dim	Era 1
Transition corridor	#181818 (neutral industrial) → #1e1912 gradient over 40m	varies	sparse cool	Era 1

Rule: The generator applies the zone palette to every floor tile and wall face in the chunk. It cannot introduce off-palette materials without an "era modification" flag (see §1.3). An institutional zone chunk with warm amber flooring is a visual error.

1.2 Lighting Fixture Placement Determines Room Scale

This is the most underappreciated visual constraint: room width is functionally constrained by fixture radius.

From the visual grammar:

• Terminal (institutional): fixture radius 8–10 visual tiles. A room wider than ~20 visual tiles needs a second fixture row.
• Bar (social): fixture radius 5–6 visual tiles. Rooms wider than ~12 visual tiles go dark between pools — which is intentional for private zones, but not for public ones.
• Maintenance: fixture radius 4–5 visual tiles. Gaps between pools are expected and desirable (abandoned, sparse aesthetic).

Generator rule: Chunk fill must place at minimum 1 lighting fixture per zone-appropriate coverage radius². Rooms that exceed 2× coverage radius without a fixture read as broken infrastructure in institutional zones and as suspicious in any zone. The generator's room-dimension choices must respect fixture-coverage budgets for the zone.

1.3 Era Tags Produce Material Variation Without Palette Violation

Buildings within a block share an era tag. The era tag modifies surface materials while staying within the zone palette range:

• Era 1: Base palette. Older composite panels, original construction.
• Era 2: Retrofit elements. Same floor tile base; surface-mounted conduits, junction boxes, modified partitions in #6d7178 (slightly warmer than Era 1's #7a7f85, different production run). Visible as overlay elements on layer 4.
• Era 3: Newer construction. Cleaner materials, Commission-grade or commercial finish. Gate cluster is pure Era 3: #b8bec4 surfaces, uniform LED-white overhead. Bar is Era 3 built by an individual (Lera): same era code, but density of accumulated modifications distinguishes it from institutional Era 3.

Generator rule: Assign era at block generation time, not chunk fill time. Chunk fill inherits era from block. Adjacent blocks can have different eras; the visual transition manifests at block boundary chunks via setbacks, service alleys, or material seams.

1.4 Saturation Hierarchy Must Be Preserved

D-044 visual hierarchy: entity (40–60% saturation) > objects (15–30%) > structure (5–15%).

The generator cannot introduce decorative or accent materials that approach entity saturation. Generated floor markings, zone signage, and accent walls must stay in the 5–15% structure tier. If the generator places anything in the 15–30% object tier as environmental decoration (painted walls, colored service doors), it must not exceed D-052 favorite color saturation rules.

Hard constraint: No generated structural or decorative element uses a hex color with saturation above 30%. This is not a style preference — it's a system requirement. If the environment reaches entity saturation levels, the player loses the ability to read NPCs by color (D-033 system breaks).

1.5 Outline Consistency Is Absolute

#333340 is the universal outline for all sprites, all zones, all layers. Non-negotiable. Generated content inherits this. The generator does not produce zone-specific outlines or context-specific outlines. Consistency is what makes the visual grammar feel like a coherent world rather than a patchwork of assets.

1.6 LOS Anchor Interval Constraint

From locked spatial rules (V-05, Workshop #153): structural breaks (walls, pillar clusters) must occur at maximum 16 visual tile intervals in open spaces, with quarter boundaries as the primary anchor points.

Why this matters for chunk fill: Without LOS anchor placement rules, the generator can produce open-floor chunks that are visually incoherent and gameplay-broken simultaneously. A 32×32 visual tile chunk filled with open floor provides no cover, no investigation positions, no spatial drama. The LOS anchor rule is both a visual coherence rule (prevents visual emptiness) and a gameplay rule (prevents cover-free spaces).

Generator rule: Every quarter (16×16 visual tiles) must contain at minimum one structural break that interrupts east-west or north-south LOS across the quarter. This can be a wall partition, a pillar cluster, a furniture arrangement, or a zone transition boundary. The break does not need to be at the exact quarter boundary — it can be within 4 visual tiles of it.

---

2. How the Sub-Chunk Quarter System Produces Plausible Streetscapes

2.1 Quarter Dimensions and Their Spatial Meaning

A chunk is 32×32 visual tiles (32m). Divided into 4 quarters: each quarter is 16×16 visual tiles (16m).

16m × 16m is a meaningful spatial unit:

• A small shop or office fits in one quarter (with walls and a narrow corridor)
• The Terminal's scanner bay cluster (rows 6–9, ~16×4 visual tiles) is a functional sub-quarter
• The bar's corner booth zone (NW, rows 1–5, ~8×5) occupies roughly one-third of a quarter

The quarter is the minimum viable building unit. A single-quarter building has room for one social zone, one access entry, and minimal interior subdivision. Two-quarter buildings have room for a public face and a semi-private back. Four-quarter buildings (full chunk) support the complexity of the Terminal or Gate Cluster.

2.2 Street Generation Must Precede Quarter Fill

Streetscapes are coherent only if streets are determined before buildings. The generator sequence for visual coherence:

1. Block level: Determine street network (which block edges are street-facing, which are back-of-block)
2. Chunk level: Determine which chunks within the block contain buildings vs. open space vs. street continuation
3. Quarter level: Determine which quarters are filled (building footprint) vs. empty (courtyard, alley, service access)
4. Fill level: Place zone-appropriate floor, wall, furniture, and overhead elements within filled quarters

Rule: Building facades must face the nearest street edge. The generator never places a primary building entrance on the back-of-block side. This is what makes a block look like a block rather than a random cluster of structures.

2.3 Facade Rhythm Along a Block Face

Adjacent filled quarters on a street-facing block edge cannot have identical facade treatments. The visual grammar requires variation without chaos:

• Vary doorway position (west side / center / east side of facade) between adjacent buildings
• Vary facade depth: some buildings set back 2–3 visual tiles from the block edge, others flush
• Alternate overhead element density (pipes, signage) between adjacent quarters

What the hand-authored examples tell us:

• The Terminal's entry facade (row 01): two doorways spread across 44 visual tiles, with solid wall between them. Rhythm: solid | door | long solid | door | solid.
• The Gate Cluster's concourse south wall (row 33): the primary district-facing facade is essentially unbroken, with the district entry at ground level. Scale communicates institutional weight.
• The Bar's main entrance (row 01): one primary door (west) + one emergency exit (east). Asymmetric, which reads as organic (functional warmth).

Generator rule: Randomly placing doorways produces facades that look like generated content. The generator should select from a small set of facade templates per zone/era/access-tier combination, then apply allowed variation parameters (doorway count, setback, overhead density). Do not treat facade generation as free parameter space.

2.4 Access Tier Gradient Is Spatial, Not Random

Hand-authored locations consistently follow a gradient: public street face → semi-public entry zone → semi-private interior → private back zones. This is not just a gameplay rule; it's what produces plausible architecture.

Terminal: Entry lobby (PUBLIC) → Scanner bays (PUBLIC MONITORED) → Main corridor (SEMI-PUBLIC) → Work zones (SEMI-PRIVATE/PRIVATE) Bar: Entry (PUBLIC) → Main tables (PUBLIC) → Bar counter zone (SEMI-PRIVATE) → Back room (PRIVATE) Gate cluster: Concourse (PUBLIC) → Customs lanes (SEMI-PRIVATE) → Staging (PRIVATE) → Aperture (RESTRICTED)

Generator rule: The access tier gradient runs north-south or from the street-facing edge inward. The public face is always the face with the most exterior exposure. The private back is always the face furthest from public circulation. Quarters are tagged with access tiers before fill content is selected. Fill content must be appropriate to the tier (no open seating in private zones, no locked doors in public zones without authority-gated reason).

---

3. Quarter Merge Rules: What Decides Fill vs. Empty, and Shape

3.1 Three Merge Types and Their Visual Logic

2×2 merge (full chunk = 32×32 visual tiles): Used for major institutions: primary logistics hubs, government facilities, large commercial buildings. The Terminal is roughly this scale (44×28 — slightly larger than a single chunk, suggesting it spans into a second chunk or uses a non-standard block configuration). The Gate Cluster (40×32) is essentially a full-chunk structure. Visual requirement: 2×2 merges need a legible building boundary on all four sides. The generator must place a clear facade (wall + doorway treatment) on each exposed edge, not just the street-facing side.

1×2 merge (half chunk = 16×32 or 32×16 visual tiles): Used for medium-scale spaces: medium offices, workshops, larger commercial venues. This is the most common merge type in a working-class district. Visual requirement: The long edge of a 1×2 merge is the primary facade. The short edges are either party walls (shared with adjacent building, no exterior treatment) or service edges (minimal, utilitarian). The generator must determine which axis is the long facade axis from the street orientation.

L-shape merge (3 quarters): This is the "functional warmth" shape — the building that grew organically. The Bar's bathroom corridor extension is a real-world example of L-shape emergence: original rectangular structure + later addition that breaks the rectangle. Visual requirement: L-shapes need a visual explanation for the notch. Options:

• The notch is a service alley (narrow, maintenance-access, darker floor)
• The notch is a courtyard or outdoor area (open, possibly furniture)
• The notch is a later-era addition seam (visible material change at the join)

The generator cannot produce L-shapes where the notch is simply empty floor with no visual or functional justification. The notch must be assigned a purpose type.

3.2 Empty Quarter Types

An empty quarter is not just "no building here." It must be one of:

Empty type	Visual treatment	Lighting	Access tier
Open plaza	Open floor, zone palette, possibly benches	Zone-appropriate fixtures	Public
Service alley	Narrow (4–6 visual tiles wide), dark floor, minimal fixtures	Sparse, cold	Semi-private to restricted
Courtyard / garden	Open floor, overhead vegetation (layer 4), possibly planters	Natural or warm ambient	Semi-private (enclosed), public (open)
Vehicle / cargo staging	Open floor with [CT]-type dock markers, sparse overhead	Industrial, zone palette	Semi-private
Structural gap (undeveloped)	Bare floor, no furniture, possibly temporary barriers	No fixtures = very dark	Restricted by default

Generator rule: Assign empty type at quarter planning time. Use zone and access tier to constrain the available empty types. A gate cluster zone cannot have a courtyard/garden (wrong era, wrong function). A residential zone cannot have cargo staging.

3.3 Fill vs. Empty Ratio by District Density

The generator needs a "density" parameter per block, derived from zoning and economic tier inputs:

Density	Filled quarters per block	Expected visual character
High (industrial/commercial core)	12–16 of 16	Dense block faces, few gaps, tall overhead layers
Medium (mixed-use, working class)	8–12 of 16	Regular gaps (alleys, small plazas), varied building scales
Low (residential fringe, transitional)	4–8 of 16	Open courtyards, gardens, undeveloped quarters common

No block should have all 16 quarters filled. There is always at least one empty quarter per block for service access. This is the generator's hard floor rule: a block with no alleys is architecturally implausible and breaks NPC routing for maintenance-tier characters.

---

4. How Multi-Block Structures Read at Their Edges

Multi-block structures (gate terminals, horizon station access points, government complexes, stadiums, parks) span multiple chunks and must resolve their edges differently from single-chunk buildings.

4.1 The Scale Communication Problem

A multi-block structure must communicate its scale before the player reaches it. At a glance, it must read as "larger than a single building." The mechanisms:

1. Unbroken facade length: A single-chunk building facade is max 32 visual tiles wide. A multi-block structure has a facade spanning 64, 96, or 128 visual tiles. This length reads as institutional weight. The generator must not break this facade with building-scale interruptions (separate doorways that read as separate buildings). Long facades with wide-spaced feature doorways.

2. Elevated overhead layer (layer 4): Multi-block structures can have overhead elements that span chunk boundaries — roof structures, elevated walkways, ducts — that signal continuity. A single-chunk building has overhead elements bounded by its chunk. A multi-block structure's overhead layer crosses chunk seams.

3. Setback buffer zone: Multi-block structures almost always have a setback from the street — a cleared zone, a plaza, or a service perimeter. This setback is part of the block reservation at the zoning pass. The setback communicates "this building doesn't need to compete for street frontage."

4.2 Edge Chunk Treatment

The chunks at the edges of a multi-block structure face a specific visual challenge: they're part of a large building but they're adjacent to the district circulation system.

Required edge treatments:

• Corner chunks: Special facade treatment. Not a flat wall turning a 90° corner. Options: angled setback, corner feature (pillar, commission emblem, material accent in zone palette), or service access recessed into the corner.

• Entry chunks: The chunk containing the primary entrance to a multi-block structure. Entry facade must be ≥ 3× the width of the connecting corridor (from V-05). For a district street connecting at 4–6 visual tiles wide, the entry facade must be 12–18+ visual tiles wide with at minimum 2 access doors. The Gate Cluster's concourse south wall (40 visual tiles wide with 2+ entry points) demonstrates this correctly.

• Party wall chunks: Chunks on the boundary between a multi-block structure and adjacent single-chunk buildings. The multi-block structure's wall on this edge needs no decorative treatment — it reads as a party wall, which is architecturally correct and visually clean.

• Back-of-building chunks: Maintenance access for multi-block structures. These chunks face the service spine or maintenance corridors. Visual treatment: utilitarian, dark, Era 1 base materials, minimal lighting. Do not apply the public-facing material treatment to service edges.

4.3 Zone Continuity Across Chunk Boundaries

A multi-block structure has one zone palette for its entire footprint. The generator must not allow zone-palette variation between the chunks of a single multi-block structure. The Gate Cluster is uniformly #b8bec4 / cold LED throughout all 40×32 visual tiles. No amber warmth creeps in from the adjacent transit corridor.

Hard rule: Chunk seams within a multi-block structure are invisible at the visual grammar level. Floor tiles, wall materials, and lighting temperature are continuous. The only things that can change at a chunk seam within a building are: functional zones (staging vs. customs vs. concourse) with their associated furniture and overhead elements, not base materials.

---

5. Visual Consistency Rules to Prevent Districts from Looking Random

5.1 The Three Consistency Anchors

A generated district avoids looking random if every chunk can be traced back to three consistent sources: its zone palette, its era, and its access tier gradient. These three together determine:

• What materials appear on the floor and walls
• What modifications and overlays exist
• What kind of furniture and overhead elements are placed
• How light is distributed

If the generator maintains consistency on these three anchors across all chunks in a district, visual coherence follows automatically. Randomness appears when chunks are filled without reference to these anchors.

5.2 Street Network as Visual Spine

The district's street network is the visual skeleton. Every building facades toward it; every service access routes away from it. The street network determines orientation for the entire district.

Visual rules for generated streets:

• Street floor tile uses a dedicated transitional material (not the adjacent building's floor palette — streets are shared infrastructure, not zone-specific)
• Street width by type: maintenance corridor 2vt, internal building 2–4vt, district street 4vt, transition corridor 6vt, gate concourse 8vt (locked in V-05)
• Street lighting: zone-appropriate fixtures placed at regular intervals (every 8–12 visual tiles for primary streets, every 16–20 for secondary)
• Street intersection treatment: clear visual signal that two streets meet (material change at the crossing tile, or a pillar/feature at the corner)

5.3 Landmark Anchors and District Readability

Hand-authored districts have visual landmarks that orient the player: the terminal's institutional facade, the bar's amber light spill, the gate cluster's administered cold white. Generated districts need the same.

Generator rule: Each district should have minimum 1 landmark structure per block cluster (4 blocks = 1 district quadrant). A landmark structure is a multi-block structure or a building with distinctive visual treatment. The generator reserves landmark slots at the district planning pass, before block generation. Landmark structures get the full multi-block edge treatment (§4).

Without landmark anchors, generated districts produce visual monotony where every block looks like every other block. The landmark is not about decoration — it's about navigation and spatial orientation.

5.4 Facade Variation Budget

Adjacent buildings on the same block face must vary in at least 2 of these 5 parameters:

1. Primary entry position (west / center / east of facade)
2. Facade depth (flush / 1–2vt setback / 3–4vt setback)
3. Overhead element density (sparse / moderate / dense)
4. Building height expression (single overhead layer / double overhead layer with structural bridge)
5. Era modification markers (none / minor / heavy)

If adjacent buildings vary in only 1 or 0 parameters, the block face looks copy-pasted. The generator's facade parameter selection must check the adjacent quarter's choices before committing.

5.5 Lighting Temperature Is Zone-Specific, Not Building-Specific

The lighting temperature in the visual grammar is set by zone, not by individual buildings. A bar inside an institutional zone gets institutional lighting, not amber. The only exception is player-facing hand-authored social sites where lighting is an authored decision (The Last Shift's amber is Lera's decision, not the zone's character).

Generator rule: Generated buildings inherit their lighting temperature from the zone palette. The generator does not assign lighting temperatures at the building level. Lighting is a zone property.

This is important because the palette gradient rule (locked in Workshop #153) creates visual territory:

• Gate/official: cool white → cargo/functional: grey-navy → transit neutral: dark → social warm: amber

A player walking through a generated district should feel the temperature gradient shift as they move from institutional zones into residential or social zones. This gradient is the district's visual fingerprint.

5.6 The "Settled" Principle — Placement Density Communicates Character

D-051 ("settling is placement"): spaces feel inhabited when they have accumulated objects, not when they have large open areas. Empty space reads as abandoned or transitional. Filled space reads as active.

For the generator, this translates to a placed-object density budget per quarter:

Zone type	Objects per quarter (typical)	Notes
Institutional (terminal, gate)	High: 8–14 large objects (terminals, cargo containers, desks)	Functional accumulation
Social (bar, market)	Medium-high: 6–10 objects (tables, seating, service equipment)	Personal accumulation
Residential	Medium: 4–8 objects (furniture, personal items)	Domestic accumulation
Maintenance / service	Low: 1–4 objects (utility equipment, sparse)	Functional minimum
Transit / corridor	Very low: 0–2 objects (signage, benches only)	Movement spaces stay clear

The generator must not produce empty rooms. An empty room is an authored decision (the restricted storage room is sparse by design — contraband doesn't advertise itself). A generated empty room is an unfinished room. If the zone/access tier combination doesn't justify a sparse object count, the generator adds zone-appropriate clutter.

---

Summary: What the Generator Must Guarantee from a Visual Perspective

The following visual properties are non-negotiable outputs of any generator pipeline:

1. Every chunk belongs to exactly one zone palette. No mixed-palette chunks. Zone boundaries are block-level decisions.

2. Every block has an era tag. Era modifies surface materials within zone palette bounds. Adjacent blocks may have different eras; the visual transition is handled at block boundary chunks.

3. Access tier gradient runs from street face inward. Public front, private back. This determines facade treatment, interior subdivision, and furniture selection.

4. Corridor widths are enforced by type (V-05): maintenance 2vt, internal building 2–4vt, district street 4vt, transition 6vt, gate concourse 8vt. The generator cannot produce corridors narrower than these minimums.

5. LOS anchors exist at max 16vt intervals. Every quarter contains at minimum one structural break.

6. No generated element exceeds structure-tier saturation (15%). Entity visual hierarchy is inviolable.

7. All outlines are #333340. No exceptions.

8. Empty quarters have assigned types. Empty is not null — it is plaza, alley, courtyard, staging, or undeveloped, each with specific visual treatment.

9. Multi-block structure facades are unbroken and wide. Entry facade ≥ 3× connecting corridor width, minimum 2 access doors.

10. Lighting temperature is zone-assigned, not building-assigned. The zone palette determines fixture color temperature. Buildings do not override this.

11. Adjacent filled quarters on a street face vary on at minimum 2 facade parameters. Facade variation is enforced, not random.

12. Every district quadrant has at minimum 1 visual landmark. Landmark slots are reserved at district planning pass before block generation.

---

These constraints are derived from the hand-authored v0.1 content (Terminal, Bar, Gate Cluster, Smuggling Corridors), the confirmed visual grammar (visual-grammar-v01.md), the locked spatial rules from Workshop #153 (V-05), and the D-records cited throughout. Any generator proposal that violates these constraints will produce visually incoherent output regardless of how correct the spatial math is.