settled-reach/docs/sprints/sprint-23/visual.md

Sprint 23: Terrain — Visual Tasks

Goal: Build the walkable Sova world under the authored content, complete the storyteller engagement layer, and add the debug console — clearing the path to v0.1 integration in Sprint 24.

Branch: visual Agents: Araminta (art direction, tile authoring)

---

New Tickets

#	Title	Blocked by
#582	Author tile map: The Terminal (logistics hub)	#577 (server tile format)
#583	Author tile maps: The Last Shift, maintenance corridors, and gate corridor	#577 (server tile format)

Use tooling/db/ticket show <id> for full descriptions.

---

Key Decisions

• decisions/content.md — D-093 (Sova Transit District — full spatial spec with tile dimensions, zone palette, corridor widths, zone-by-zone breakdown)
• decisions/content.md — D-025 (functional cluster: 15-40 tile connected spaces, internal sightlines, public/private zones)
• decisions/architecture.md — D-094 (spatial hierarchy: chunk 32×32 sim tiles = 16×16 visual tiles at 2x retina, D-066), D-066 (dual-scale grid: 0.5m sim, 1m visual)
• decisions/architecture.md — D-110 (z-levels: z=0 maintenance corridors, z=1 main structures, z=2 observation gallery)

---

Open Questions to Resolve Early

• Tile format (day 1–2): Server ticket #577 must publish the tile format before authoring begins. Coordinate with Dudley. The format is expected to be: tiles: array of strings, one char per tile. Do not author tile data until the format is confirmed and documented in server/src/content/types.rs.

---

Notes

Tile format primer

The server will confirm a format like:

tiles:
  - "WWWWWWWWWW"
  - "WFFFFFFFFFFW"
  - "WFFFFFFFFFFW"
  - "WWWWWWWWWW"

Characters: F=floor (walkable), W=wall (blocks movement/LOS), V=void (empty space outside the location boundary), R=restricted (walkable but access-tier restricted). Left-to-right = +x, top-to-bottom = +y. Origin (0,0) = top-left corner of the tile_bounds bounding box.

Do not use any other characters until the server documents them.

#582 — The Terminal tile map

Source materials:

• #311 (done): Spatial layout — The Terminal. Tile-level floor plan with sightline analysis. Sprint 12.
• D-093: Terminal dimensions = 44×28 visual tiles. Zone palette surface hex: #7a8490, fog tint: #0d1520.
• Access tiers: main corridor = public, work floor = credentialed, restricted storage = restricted.
• Key spatial features:
  • Scanner bays (entry — public)
  • Main corridor (chokepoint — high sightline value)
  • Manifest processing (work floor)
  • Break room (social site — NPC off-hours presence)
  • Supervisor office (window faces main corridor — LOS design requirement)
  • Restricted storage (smuggling ops — R tiles for access restriction)

Output: Complete content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/locations/the-terminal.yaml with:

• canonical_id: van-maanens-star.sova.transit.location.the-terminal
• display_name: "The Terminal"
• tile_bounds: { x_min: 0, y_min: 0, x_max: 43, y_max: 27, z: 1 } (z=1 per D-093)
• tiles: [...] — the 44×28 grid
• sightlines: { open: false, notes: "supervisor office window faces main corridor; LOS critical for investigation" }
• social_site: "logistics-hub" (links to the template)

Sightline requirement: The supervisor office window must be placed so that the player standing in the main corridor has LOS to the office interior. This is investigatively critical — it is how the player first suspects the supervisor. Do not place it behind a wall that would block shadowcasting.

#583 — The Last Shift, maintenance corridors, gate corridor

Three YAML files. All blocked on #577 tile format; can author all three in parallel once format is confirmed.

The Last Shift (the-last-shift.yaml)

• Source: #312 (done), Sprint 12
• D-093: 28×22 visual tiles + 6m east extension (= ~6 visual tiles). Total footprint: ~34×22.
• Zone palette: #6b4018 (warm dark brown — converted maintenance area), fog tint: #200c04
• Key features: long bar counter (high visibility — staff can see all tables), corner booth (observation premium — sees bar + card table + entrance + back room), scattered tables, news ticker display (F tiles), back room with alley exit (R or F tiles — navigable, but the back exit is the key traversal route)
• z=1 (main structure per D-093)

Maintenance corridors (maintenance-corridors.yaml)

• Source: #313 (done), Sprint 12
• D-093: Corridor width = 2 visual tiles (maintenance standard). z=0 (Era 1, below main structures).
• Zone palette: #4e5054 (dark utilitarian grey), fog tint: #101214
• Key features: restricted storage (shared with Terminal — use R tiles), maintenance hatch (connects z=0 to z=1 — note: cross-z connection is a future movement feature; for now just tile the spaces), transition corridor 40m between hub and bar district (~40 visual tiles length at 1m/tile)
• Design principle (D-093 G-08): the ring operates here; all spaces must read as mundane maintenance unless you know what to look for. No obviously suspicious tile arrangements.

Gate corridor (gate-corridor.yaml) — new file

• Source: D-093 gate cluster zone spec
• D-093: Gate cluster 40×32 visual tiles, z=1 main + z=2 observation gallery
• Zone palette: #b8bec4 (neutral cool — institutional grey), fog tint: #0a1222
• Seven zones (author these as continuous tile grid, walls between zones):
  • Aperture chamber: 8×4 (restricted — R tiles)
  • Freight staging: 24×8 (private — use F tiles, access enforced by NPCs not tile kind)
  • Passenger arrival: 12×8 (semi-public — F)
  • Freight customs: 20×10 (semi-private, 3–5 lanes of 2-visual-tile width separated by wall stubs)
  • Pedestrian customs: 12×10 (semi-public, 3 lanes of 1-visual-tile width)
  • Gate concourse: 40×8 (public — wide open, 8vt corridor width per D-093)
  • Observation gallery: z=2, 32×10 (Commission-only — R tiles; separate tile_bounds entry with z:2)
• D-093 cross-z LOS: gallery rail = transparent low wall. Model this as a separate z=2 tile grid with R floor tiles (navigable but restricted access). The LOS cross-z behavior is handled by the server; just provide the tile data.
• Add gate-corridor to content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/district.yaml locations list.

Cross-z note: Author two sections in the gate-corridor YAML if the format supports multiple tile_bounds (one at z=1, one at z=2). If the format only supports a single z-level per Location, author two separate files: gate-ground.yaml and gate-gallery.yaml. Confirm with Dudley when the format is published.

---

Dependency Chain

#577 (server: tile format published, day 1-2)
  → #582 (Terminal)     — can start same day format is confirmed
  → #583 (Last Shift + maintenance + gate)  — parallel with #582

Both tile authoring tickets can run in parallel once #577 publishes the format. Expect 2–3 days of authoring work per ticket given the complexity of the gate corridor.

---

PR Workflow

tea pr create --repo jpmschweitzer/settled-reach --login schweitz \
  --title "feat(visual): author tile maps for Sova Transit District" \
  --description "body" --base main --head visual

---

Sprint Completion (Visual Criteria)

1. the-terminal.yaml has complete tile data — 44×28 grid, all zones represented, sightlines documented.
2. the-last-shift.yaml has complete tile data — corner booth placement satisfies observation affordance.
3. maintenance-corridors.yaml has complete tile data — z=0, maintenance aesthetic, restricted storage marked.
4. gate-corridor.yaml (or equivalent) has complete tile data for all 7 zones including z=2 observation gallery.
5. district.yaml locations list updated to include gate-corridor.
6. Server can boot production startup and load tile data from all four locations without error.