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

---
title: "Sprint 23 — Visual Briefing"
description: "Author tile maps for The Terminal, The Last Shift, maintenance and gate corridors"
type: sprint
status: archived
sprint: 23
team: "visual"
---

# 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:

```yaml
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

```bash
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.