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

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

title	description	type	status	workshop	agent	round	created
Araminta Round 4 — Heritage Grammar and Vessel Visuals	Heritage grammar authoring, vessel visual grammar, rooftop bar clause, and D-record sign-off	workshop	archived	generator-architecture	araminta	4	2026-02-27

Generator Architecture Workshop — Round 4: Araminta

Heritage Grammar Authoring, Vessel Visual Grammar, Rooftop Bar Clause, D-Record Sign-off

Author: Araminta (Visual Designer) Date: 2026-02-27 Workshop: Generator Architecture (Ticket #562) Responding to: Round 3 notes (Qatux), OQ-R4-D, vessel architecture, lead directives Status: Round 4 — final convergence

---

Opening: Four Items, All Closeable

This is my shortest round by design. Three of my four assignments are new specification work; the fourth is a review pass. I'm not going to repeat the grammar I established in Rounds 1–3. I'll reference it and move forward.

---

1. OQ-R4-D: Heritage Grammar Overlay — Authoring Workflow and Runtime Pipeline

The Core Question

Miri asks: per-heritage modifier objects that chunk fill applies, or lookup tables within terrain palette assets?

Neither exclusively. The right answer is data-driven modifier objects — structured like per-heritage objects (typed, blendable) but stored as content files (TOML/YAML), not hardcoded in the palette assets or the code.

Here's why each pure option fails:

• Lookup tables in palette assets: Heritage grammar gets duplicated across every terrain type that uses it. A Vine heritage modifier rule gets written once for farmland, again for wilderness, again for coastal, again for urban. Inconsistency accumulates. Updating "all Vine farms" means touching every terrain palette.
• Hardcoded per-heritage modifier objects: Changing a modifier or adding a new heritage variant requires a code change and rebuild.

The hybrid: HeritageModifier structs defined in TOML/YAML content files, loaded at startup, blended at chunk fill time.

The Data Structures

Content file (TOML — designer-authored, one file per heritage root):

# content/heritage/vine.toml
[heritage_modifier]
root = "Vine"
applicable_terrain = ["T1_farmland", "T2_industrial_farm", "T3_wilderness",
                      "T4_grassland", "T6_beach", "T8_desert", "Urban", "Orbital"]
# Modifiers below are overrides/additions to the base terrain palette defaults.

[floor]
variant_preference = ["worn_path", "mossy_edge", "pressed_earth"]
# "worn_path" is a floor tile variant in the terrain asset library

[objects]
object_set = "vine_heritage_outdoor"
# Identifies a named set in the object asset library.
# The object set contains: trellises, planters, outdoor seating clusters,
# seasonal decoration markers, communal fire infrastructure, door frame plants.
arrangement = "organic_cluster"
# "organic_cluster" is an arrangement algorithm identifier, not hardcoded.
# Valid values: grid, organic_cluster, edge_accent, radial, scattered

[overhead]
density_factor = 0.65     # 0.0-1.0 relative to terrain type's max overhead budget
character = "personal_organic"
# Valid values: institutional, personal_organic, personal_functional, seasonal, sparse, none

[gathering]
space_probability = 0.40  # chance of a gathering space in any outdoor quarter

[lighting]
temperature_adjustment_k = 800    # Kelvin added to zone baseline (positive = warmer)
fixture_character = "personal"    # personal | functional | institutional | absent

[boundaries]
fence_type = "trellis_wood"       # references fence asset set
boundary_height = "low"           # low | medium | high | wall

[social]
# How this heritage root modifies the social texture visible in the space
exterior_welcome_signal = true    # buildings present welcoming elements toward the street
privacy_orientation = "outward"   # outward | inward | neutral
accumulation_character = "warm_organic"  # warm_organic | functional | austere | ordered

A designer writes this file. No code changes for new heritage variants or adjustments.

The full 10-root modifier table, summarized as authoring targets:

Root	Object set	Arrangement	Overhead character	Temp adj. (K)	Gathering prob.	Boundary	Exterior signal
Frost	frost_heritage	grid	sparse	-600	0.10	low_wire	false
Vine	vine_heritage	organic_cluster	personal_organic	+800	0.40	trellis_wood	true
Stone	stone_heritage	edge_accent	personal_functional	0	0.25	permanent_stone	false
Tide	tide_heritage	radial	seasonal	+200	0.55	low_open	true
Iron	iron_heritage	grid	institutional	-200	0.30	shared_infra	false
Dust	dust_heritage	scattered	functional	0	0.20	weatherproof	false
Spice	spice_heritage	zone_divided	personal_organic	+400	0.25	medium_defined	true
Salt	salt_heritage	grid	sparse	-100	0.15	functional	false
Arc	arc_heritage	grid	functional	-100	0.30	labeled_markers	false
Jade	jade_heritage	edge_accent	personal_organic	+100	0.20	refined_low	true

Arrangement algorithm summary:

• grid: Evenly spaced, parallel orientations. Objects align to grid.
• organic_cluster: Grouped irregular spacing, varied orientations. Objects face each other.
• edge_accent: Objects placed at spatial boundaries (building edges, path margins, corners).
• radial: Objects arranged relative to a central gathering point.
• scattered: Low-correlation positions, minimal clustering.
• zone_divided: Objects define distinct spatial sub-zones within the quarter.

Runtime Pipeline — What Chunk Fill Looks Up

Chunk fill receives:
  ChunkFillSpec {
    zone_id,
    era,
    chunk_seed,
    society_profile: SocietyProfileRef  ← includes heritage blend
  }

Step 1: Load base terrain palette
  palette = load_base_palette(zone_id.terrain_type)

Step 2: Blend heritage modifiers
  For each (root, weight) in society_profile.heritage.roots:
    modifier = load_heritage_modifier(root)
  blended = blend_modifiers(modifiers_with_weights)
  // Blending rules:
  //   Continuous values (temperature_adjustment_k, density_factor, gathering_probability):
  //     weighted average
  //   Discrete values (object_set, arrangement, fence_type):
  //     weighted probabilistic selection (dominant root wins most of the time)
  //   Boolean values (exterior_welcome_signal):
  //     weighted probability (60% Frost / 40% Vine: 40% chance of welcome signal)

Step 3: Apply blended modifier to palette
  working_palette = apply_modifier(palette, blended)

Step 4: Fill quarter using working_palette + era + chunk_seed
  (existing fill logic — place floor tiles, objects, overhead elements, lighting)

Blend example: 60% Frost / 40% Vine farmland

• temperature_adjustment_k: (0.6 × -600) + (0.4 × +800) = -360 + 320 = -40K (barely cooler than baseline — the two largely cancel)
• density_factor: (0.6 × sparse_default) + (0.4 × 0.65) = moderate overhead
• arrangement: Frost wins probabilistically (60%). Grid arrangement, but some organic cluster elements from Vine's 40% share appear in the overhead layer.
• exterior_welcome_signal: 40% chance — the farm presents a slightly inviting exterior, but the Frost efficiency still dominates the floor plan.

The output is a farm that's functional and ordered (Frost dominant) but with a few organic touches — a trellis here, an informal seating corner there — that tell you Vine heritage is also present.

What an Artist/Designer Authors

Three asset types feed the heritage modifier system:

1. Object sets (artist-authored, tagged by heritage root) An object set is a named collection of placeable objects in the asset library. The artist creates objects appropriate to each heritage root's aesthetic and tags them. Adding new Vine heritage objects to the base game means adding them to the vine_heritage_outdoor object set — no modifier file change needed.

2. Heritage modifier files (designer-authored TOML, one per root) The ten files described above. A designer can adjust behavior by editing these files. No code changes. If a heritage modifier is added (future expansion), one new TOML file is all that's needed.

3. Terrain palette base files (artist-authored, one per terrain type) The base terrain palette with default object density, lighting, and floor tiles. The heritage modifier overrides these defaults — anything not overridden uses the terrain palette default. This means a terrain type only needs to specify its own defaults; heritage grammar is applied on top.

The One Design Rule That Must Be Stated Explicitly

Rule: The heritage modifier is applied at chunk fill time (Phase 2), not at district skeleton time (Phase 1). The DistrictSkeleton carries society_profile: SocietyProfileRef. Phase 2 chunk fill reads the heritage blend from the profile and applies the modifier. This means the heritage grammar is visible in the tiles but never stored as a structural generator decision — it's a visual expression, not a spatial constraint.

Exception: gathering_probability from the heritage modifier can influence Phase 1 quarter pre-assignment (whether a quarter is pre-assigned as "outdoor gathering space"). If so, the heritage modifier must be partially evaluated at block planning time for that specific parameter. All other modifier parameters apply at Phase 2 only.

---

2. Vessel Visual Grammar

The Answer: Modifiers, Not New Base Palettes

Vessels use existing zone palettes. What distinguishes a vessel visually is not a different material vocabulary — it's a different spatial grammar. The material inside a luxury cabin is the same amber-warm bar palette. The material inside a cargo hold is the same maintenance-grey. What's different is the envelope, the proportion, and the bounded-environment signals.

Rule: vessels are existing-palette spaces with five additional visual grammar rules.

The Five Vessel Visual Grammar Rules

Rule V-1: Exterior hull is vessel-identity material, not zone palette.

The outer hull/skin of any vessel uses a specific material that identifies the vessel as a vessel:

• Spacecraft: #2a2e32 (dark cold metal, Era-appropriate surface texture — Era 1 = riveted plate, Era 2 = welded panels, Era 3 = smooth composite)
• Trains: livery color applied to the exterior — muted version of the operating company's identity color, within saturation rules
• Ships/boats: #2a2820 (weathered dark hull, salt-worn)

The exterior hull material applies only to the outermost layer visible from outside. Interior spaces use zone palettes normally.

Rule V-2: Window tiles provide exterior context.

Where a vessel has windows (train windows, porthole, cockpit view), the window tile is a special element:

• On the floor layer, the window gap shows a z=0 background buffer — a scrolling or static exterior visual
• In transit: the exterior buffer shows appropriate passing environment (stars, landscape, water)
• Docked: the exterior buffer shows the dock environment (warehouse wall, station hull)
• The window frame is vessel-hull material, the opening is the contextual reveal

Rule V-3: Vessel spaces use a compression modifier.

The same zone palette, but proportionally tighter:

• Overhead height budget reduced by 30% (same z=4 elements, but lower effective ceiling)
• Object density increased within the same floor area (the space is used intensively)
• Corridor minimums still apply (V-05 rules), but vessel corridors bias toward minimum width

This compression modifier communicates "bounded mobile environment" without requiring new palettes.

Rule V-4: Section transitions use vessel-identity threshold elements.

Where one vessel section (train car, ship compartment) connects to another, the threshold is:

• Door frame in vessel-hull material (not zone palette)
• A visible width reduction at the threshold (the door opening is narrower than the corridor)
• The threshold material is constant across the vessel — it marks every internal boundary

This makes internal navigation feel like moving through a vessel, not a building.

Rule V-5: Class stratification is expressed through proportion, not palette.

In a passenger vessel with multiple service classes:

• First class: higher overhead clearance (+20% overhead budget), wider aisles (+2 vt), warmer lighting temperature (+400K)
• Standard class: base compression modifier
• Economy/crew: maximum compression (-10% further from standard), colder lighting (-200K)

Same palette. Different proportions. A player who knows the grammar can read service class instantly from spatial feel.

Vessel-Specific Surface Cases

Train cars (BoundedLinear): Each car is a short, rectangular interior space. The key visual grammar element is the visible car sequence — the window at each car end shows the next car, creating a visual depth cue (you can see through multiple cars from the right position). This is implemented as a window tile facing the coupling direction showing the next car's interior.

Spaceship corridors (InterSystem): No exterior context visible during transit — black void or star-field through windows. Artificial lighting dominant (no ambient from outside). Institutional palette for working spaces; residential palette for crew quarters. The compression modifier is strongest here — corridors are minimal-width, spaces are used entirely.

Ship cabins (BoundedMaritime): Port-side windows show harbor environment when docked; ocean/sky when at sea. The marine weathering texture (visible on hull material) is the primary "you're on a ship" signal. The rocking motion (client-side animation) is Inigo's domain, not mine.

---

3. Rooftop Bar Clause — Public vs. Restricted Rooftop Visual Grammar

The Tension and Its Resolution

Gestalt's guarantee: every tall structure (z_band_count ≥ 3) must have a roof zone classified Insider or BreachOnly accessible by non-obvious route.

The lead wants rooftop bars: public social destinations on tall buildings.

These are not in conflict if we amend the guarantee correctly.

Amended guarantee: Every tall structure must have a roof zone that constitutes a discovery — something worth reaching the top for. That discovery can be:

• A public destination (rooftop bar, garden, observation deck) — accessed via obvious route, classified Public or Semi-Public
• A restricted discovery (operational rooftop, private access) — accessed via non-obvious route, classified Insider or BreachOnly

Both satisfy the intent: the top of the building is not just mechanical infrastructure. The access tier varies; the discovery does not.

Structural rule: A building can have both. A skyscraper with a public rooftop bar at z_band top AND a restricted antenna/comms level above it satisfies both playstyle needs. The rooftop bar is the destination for social/tycoon/investigation players. The above-the-bar maintenance level is the discovery for the breach/assassin player.

Rooftop Bar Visual Grammar (S3 and S4 Height Tiers)

A rooftop bar at S3 (11-30 floors) or S4 (30+) is visible from above and must communicate "social destination, open to arrival."

Floor material: Warm pavers or composite decking — lighter and warmer than the industrial-default rooftop. Not the zone palette floor — this is a curated outdoor surface. Hex: #2a2018 (warm dark slate/composite), visually distinct from the #181c22 cold building roof tiles.

Perimeter barrier (z=2): A designed railing or low wall around the outdoor area — thin (1-tile), warm material (matching the bar zone palette's furniture material). The barrier communicates "this is a social edge, not a fall hazard." Visually distinguishable from the functional parapet of an institutional rooftop by material and continuity (it's a designed feature, not a structural necessity).

Seating clusters (z=2): Small furniture objects — tables and chairs at human scale. At S3/S4 heights, these are small enough that from the ground-level view they're just warm texture. From the adjacent building observation deck or elevator approach, they're readable as social furniture. High-value visual cue: the seat arrangement creates clusters (2-4 chairs around a table), not rows.

Service structure (z=2): A bar counter, or a small pavilion structure housing the service area. This is the anchor of the rooftop social space — the visible sign that this was designed to serve people, not just stand on.

Lighting signature (z=4): Warm pendant fixtures or string lights — the most visually distinctive element. Temperature #f0b840 (amber, the bar zone palette) with 80% radius of a ground-floor bar fixture. From a nearby elevated position (adjacent building, observation floor), this warm lighting cluster at height is readable as "social gathering above."

Access indicator: A visible stairhouse or elevator shaft entrance at z=2/4 — not hidden, not service-hatch scale. The access is designed as part of the social space, not an afterthought.

Restricted Rooftop Visual Grammar (Contrast)

The restricted rooftop must read as not-welcome at a glance:

Floor material: Zone-standard cold industrial roof tile (#181c22 blue-grey). No warm deviation.

Perimeter barrier (z=2): Functional parapet — same material as building structure, no warmth, no design intent beyond preventing falls. Or absent (exposed edge with safety mesh).

z=2 objects: Mechanical equipment (HVAC clusters, antenna bases, sensor arrays, junction boxes). These objects face away from a human observer — they're not oriented to be seen, they're oriented to function.

Lighting (z=4): Cold work lights only, if present — or absent. Temperature #c0d0e0 (cold), directed down. No ambient warmth.

Access indicator: Service hatch, maintenance door — small, flush with the floor, visually minimized. Or a locked stairway access door marked with institutional signage.

The Visual Grammar Test

A player approaching a tall building from the street should be able to read, from the roof's visible lighting signature at night:

• Warm amber cluster, designed railing visible = rooftop bar / social destination
• Cold/dark, mechanical silhouette = restricted / breach route

At S4 heights, the warm glow of a rooftop bar is visible from 12+ tiles away as a warm point-light cluster elevated against the dark building mass. That visual signal is navigation — a player who wants a social destination looks for the warm light at height.

---

4. Final Visual Sign-off — 12 D-Ready Items

Reading through each item and flagging wording, additions, or changes needed before the D-record is written.

---

D-READY-1: DistrictLayoutMode — Grid and Organic Support

✓ Correctly captured. Visual grammar confirmed: 45° wall variants, 12 vt landmark interval, 4–14 vt street width range, face-defined blocks.

Wording flag: The D-record must state the 45° rotation cap as a hard technical constraint, not a design preference. Language: "Maximum block rotation is ±45° from district grid orientation. This limit is non-negotiable — beyond 45°, tile-based pathfinding produces unacceptable movement artifacts. Organic districts produce the visual impression of curved streets through angular jogs, not smooth curves."

---

D-READY-2: Guarantee Tier System — Universal / Full-Only / Conditional

✓ Visual grammar correctly captured. The horizon view corridor is confirmed as a Tier 2 guarantee for coastal districts.

Wording addition needed: Add the rooftop destination clause (Section 3 above) as a Tier 2 guarantee: "Every tall structure (z_band_count ≥ 3) must contain a roof zone that constitutes a discovery — either a public destination (Public/Semi-Public access tier) or a restricted discovery (Insider/BreachOnly access tier, accessible by non-obvious route). Both types are valid; neither is mandatory over the other."

---

D-READY-3: TrianglePurpose Enum

No visual grammar implications. ✓ No changes.

---

D-READY-4: WallBackside / TileBehindState

✓ Three visual cases confirmed: adjacent room, infrastructure cavity, perimeter breach.

Wording addition: "Infrastructure cavity contents are Era-tagged: Era 1 = power conduit only; Era 2 = power + water/coolant + comm lines; Era 3 = full bundle (all types, more densely bundled). The infrastructure color codes are standardized across all zones — power #c8b840, water/coolant #4888c8, comm/data #b8b8b8, structural beam #3a3e42. These colors apply regardless of zone palette."

---

D-READY-5: Dynamic Modification via Overlay

✓ Five-stage destruction visual correctly captured.

Addition needed — trauma event → visual stage mapping:

The D-record should include the mapping from ModificationType::TraumaEvent subtypes to starting destruction stage:

Trauma event subtype	Starting visual stage	Scope
PhysicalDestruction	Stage 2 (Fresh Aftermath), decaying to Stage 3 over game-time	Area or district
ViolenceEvent	Stage 2 (limited area — 1–4 chunks), stabilizes to Stage 3 quickly	Local
EconomicDisruption	No destruction stage — Economic Stress quarter modifier applied instead	District-wide
PoliticalShock	No destruction stage — Faction presence modifier (overlay)	District-wide
MigrationShock	No destruction stage — Settlement vs. Economic Stress balance shifts	District-wide

The rule: Destruction stages apply only to events that physically alter structures. Economic/political/migration trauma is expressed through the quarter fill modifier system (D-READY-6), not through destruction stages.

---

D-READY-6: ZonePalette Modifier System

✓ 8 base terrain types, 3 modifier axes confirmed.

Wording addition needed: Explicitly name T1 and T2 as the two farmland base palettes addressing the industrial/rustic distinction:

"T1 (Temperate Farmland): warm organic ground ambient, natural lighting regime. T2 (Industrial/Greenhouse Farmland): cool grey-green ambient, artificial lighting regime. The ambient regime difference (natural vs. artificial) is the primary visual distinction between rustic and industrial farming at the base palette level. Heritage root modifiers further differentiate them at the grammar level."

---

D-READY-7: Horizon View Corridor as Coastal Guarantee

✓ Fully confirmed. ≥8 vt unobstructed view corridor. Mandatory negative space reservation.

Wording clarification: The view corridor is negative space — an instruction to not place blocking structures, not a placed object. "The generator reserves a view corridor of minimum 8 visual tiles from the nearest public street to the water's edge. No building, tree, or z=4 element may occupy this corridor. A low z=2 element (railing, bench, bollard) marks the waterfront point as a designed viewing location."

---

D-READY-8: Assassin Lens Spatial Guarantees (A-1 through A-4)

✓ Correctly captured. The spatial guarantees don't require new visual elements — existing grammar serves the assassin.

Wording note: Guarantee A-1 (Elevated Vantage) requires clarification about what "clear LOS cone" means visually. Add: "An elevated vantage position must have a direct sightline — no z=4 overhead elements within the LOS cone between the vantage point and the Traffic Chokepoint. The generator ensures this by tagging the LOS corridor as an overhead-clear zone during block planning."

---

D-READY-9: Heritage Grammar Overlay for Non-Urban Palettes

Status: Not yet lockable — this round provides the authoring workflow that was missing.

See Section 1 above for the full specification. The D-record needs:

1. The HeritageModifier struct definition (from Section 1)
2. The 10-root modifier table (from Section 1)
3. The authoring workflow description (from Section 1)
4. The rule: heritage modifier applied at Phase 2 chunk fill, with one exception (gathering_probability for Phase 1 pre-assignment)

With Section 1 above, this item is now lockable.

---

D-READY-10: Non-Urban Informal Zone Typology

✓ Correctly captured. Miri's three types resolved.

Addition — visual grammar for each informal zone type:

The D-record should include how each type reads visually:

Informal zone type	Visual signature
social_permission	Normal zone palette, but gathering infrastructure present (covered space, seating). The space looks designed for use, not abandoned. The signal is the gathering element, not absence of official markers.
physical_distance	Sparse objects, low overhead. Floor tile: terrain-appropriate but less maintained (no worn path markers — the path is made by walking, not cleared). The isolation IS the visual — this space has no design attention.
utilitarian_cover	Functional work objects. Normal zone palette. The informal zone reads as work space — the cover story is the visual appearance. There is no obvious sign that this space serves unofficial purposes; the player must infer from context.

---

D-READY-11: Vertical Scale Architecture

✓ Height tier system (S1–S4), shadow lengths, rooftop vocabulary all confirmed.

Addition for the D-record: The Rooftop Bar Clause from Section 3 above should be incorporated as a sub-rule of the vertical scale architecture decision. Specifically: "The roof zone at tier S3+ must be assigned a social character during block planning: PublicDestination | RestrictedDiscovery. This character determines the visual grammar applied at chunk fill time."

---

D-READY-12: Trauma Events as EraModification Subtypes

✓ Correctly captured from Miri's work.

Addition — visual stage mapping already provided in D-READY-5 wording above. The two D-records cross-reference.

One wording clarification: The "active modification state" that decays toward baseline — this decay is visual. As time passes (in-game hours/days), the destruction stage advances from Stage 2 → Stage 3 → Stage 4 → Stage 5. The decay rate is heritage-root-dependent (Frost: faster visible recovery; Tide: faster social recovery; Arc: lingers institutionally). This decay schedule should be in the D-record as a visual parameter: trauma_visual_decay_rate: slow | medium | fast per heritage root, defaulting to medium.

---

Summary

OQ-R4-D (Heritage Grammar Overlay): Resolved. Authoring workflow: ten TOML modifier files (one per heritage root), each specifying object sets, arrangement algorithm, overhead character, lighting temperature adjustment, and gathering probability. Runtime: blend modifiers at chunk fill time by heritage weight (continuous values: weighted average; discrete values: weighted probabilistic selection). Phase 1 exception: gathering_probability evaluated at block planning for quarter pre-assignment. Item D-READY-9 is now lockable.

Vessel Visual Grammar: Vessels use existing zone palettes with five additional rules: (1) exterior hull is vessel-identity material; (2) window tiles reveal exterior context; (3) compression modifier tightens proportions; (4) section transitions use vessel-identity threshold elements; (5) service class is expressed through proportion, not palette change. No new base palettes required.

Rooftop Bar Clause: Gestalt's guarantee amended — "discovery zone at the top" replaces "Insider/BreachOnly" as the mandatory requirement. Public rooftop destinations (rooftop bar, garden) satisfy the guarantee equally with restricted ones. Visual distinction: warm amber lighting + social furniture (public) vs. cold mechanical silhouette (restricted). Both readable at a glance from adjacent elevation.

D-record sign-off: All 12 items reviewed. Five wording additions/clarifications flagged. D-READY-9 was the only item not previously lockable — it is now, with Section 1 providing the missing authoring workflow. The trauma → visual stage mapping (D-READY-5/12) is new and must be included in the D-records.

---

Araminta — Round 4 complete. All four assignments closed. Standing by for D-record production.