---
title: "Sprint 21 — Joint Briefing"
description: "Template instantiation coordination, cross-template triangles, save/load flow"
type: sprint
status: archived
sprint: 21
team: "joint"
---

# Sprint 21: Instantiate — Joint Coordination

**Goal:** The template system becomes executable — templates spawn NPCs, assign triangles, and place them in world space; cross-template triangles link social sites; the client gains save/load game flow; and the generator pipeline gets its architectural design.

## Pre-Sprint Decisions

No blocking pre-sprint decisions are required. All selected implementation tickets have their upstream decisions confirmed.

| Decision | Status | Impact |
|----------|--------|--------|
| D-025 (social site as atomic template unit) | Confirmed | Server #159/#166/#161 schema and instantiation shapes |
| D-024 (NPC 10-axis model, 2 triangles minimum per template, 1 cross-template) | Confirmed | Server #108/#109 triangle requirements |
| D-087 (v0.1 triangle config: 3 active forks, 2 passive tensions) | Confirmed | #108 must produce triangle types consistent with T1-T5 fork taxonomy |
| D-089 (self-contained forks, no cross-triangle cascade) | Confirmed | #108 cross-template triangle uses reference links, not shared state |
| D-085 (per-game save directories) | Confirmed | Client #257 save/load flow writes to `user://saves/<game-id>/` |
| D-020 (Godot = pure renderer) | Confirmed | Client #257 never constructs save data — sends command, receives file bytes |
| D-059 (fog: five layers, shader-based) | Confirmed | Visual #564 tuning target — alpha values must match D-059 layer specs |
| D-066 (dual-scale grid, 6-8 sim tile fog gradient) | Confirmed | Visual #564 must not alter `CLEAR_THRESHOLD`/`PERIPHERAL_LOW` constants that define gradient width |

**One open question to monitor:**
- **Q-036 (district skeleton as generator output)** — actively being resolved in #562 this sprint. Resolution will gate #144 (Chunk generation system) and shape the Sprint 22 map pipeline tickets. SI will create follow-up tickets once #562 closes.

## Planning Ticket

| # | Title | Team | Agents |
|---|-------|------|--------|
| #562 | Generator architecture workshop — district/block/chunk pipeline | planning | Gestalt, Tyre, Miri, Araminta, Nigel, Qatux, SI |

**#562 — Generator architecture workshop**

Workshop brief: `docs/workshops/generator-architecture/workshop-brief.md`

**Purpose:** Establish the top-down procedural generator pipeline architecture — from geography down to individual chunk fill — that will power the 300-world model. The v0.1 Transit District is hand-authored; this workshop defines what the generator must be able to reproduce and what stub interfaces v0.1 must leave behind.

**Context documents to read before the discussion:**
- `decisions/content.md` — D-025 (social site template as atomic unit)
- `decisions/scope.md` — D-012 (chunk-based map system), D-036 (Sova as v0.1 setting)
- `decisions/questions.md` — Q-036 (district skeleton as generator output), Q-037 (generator pipeline phases), Q-039 (gate topology generation)
- `docs/design/sova-station-profile.md` — district types and 6-district layout
- `docs/design/spatial-layout-terminal-v01.md`, `docs/design/spatial-layout-bar-v01.md` — hand-authored chunk cluster examples
- `decisions/architecture.md` — D-093/D-094 (Sova spatial hierarchy: chunk/block/district naming and sizes)

**Three rounds:**
1. **Domain Inventory** — each participant states what their domain requires from the generator (Gestalt: gameplay loop guarantees; Tyre: technical constraints on chunk size and hierarchy depth; Miri: cultural/economic variation inputs for 300 worlds; Araminta: visual coherence constraints on chunk fill and sub-chunk quarter system; Nigel: variation and replayability guarantees).
2. **Pipeline Proposals** — propose pipeline stages, name the spatial hierarchy levels with tile dimensions, describe the district skeleton data structure.
3. **Convergence** — resolve conflicts, lock spatial hierarchy, define district skeleton output format, set v0.1/generator boundary, draft D-record.

**Required outputs:**
- D-record in `decisions/architecture.md`: pipeline stages, spatial hierarchy, sub-chunk quarter rules, multi-block reservation protocol, district skeleton data structure, v0.1/generator boundary
- Resolution of Q-036 (district skeleton as atomic output — yes/no + formal definition)
- Resolution of Q-037 scope (which phases land in which version window)
- Follow-up implementation tickets: chunk data structure update (#143), district skeleton schema, zoning pass stub, block generation stub

**SI role in this workshop:** Create follow-up tickets from the D-record outputs and assign to Sprint 22 candidates. Update Q-036 and Q-037 status in `decisions/questions.md`.

## Sprint Completion Proof

The sprint is done when all of the following are observable:

1. **Template instantiation pipeline end-to-end:** Load a Tier 2 YAML from `server/data/templates/`, call the instantiation engine, assert NPCs spawn with correct roles, `TemplateOwnership` set, and 2+ `TriangleState` components generated. `cargo test -p server -- instantiation` passes.

2. **Cross-template triangle produced:** A test world with two instantiated templates (logistics hub + bar) generates exactly 1 cross-template `TriangleState` with role assignments spanning both templates. `cargo test -p server -- cross_template_triangle` passes.

3. **Triangle validation catches bad inputs:** Unit tests confirm that a triangle failing conflict viability, relationship coherence, or interest divergence returns a typed `ValidationError`, not a panic.

4. **Save/load round-trip works end-to-end:** F5 in-game writes a quicksave file to `user://saves/<game-id>/quicksave.sav`. F6 reloads it. Player position and NPC state (including open doors from #246) match the save. `make ci-client` passes.

5. **Environmental interaction:** A Door entity in a test world toggles walkability on player interaction. An Examinable entity returns examine text. Door state survives a save/load round-trip (open_doors persists in `SaveStateV1`).

6. **Error handling does not crash:** Sending a malformed IPC message mid-session produces a structured `SimError` response and leaves the server running. Integration test asserts this.

7. **Fog shader tuned:** Fog Theater gauntlet room — entities in peripheral zone are visibly dimmed but not opaque; deep fog shows a readable zone temperature tint; vision cone edge is soft. `make ci-client` passes.

8. **Generator architecture decided:** #562 closes with a confirmed D-record, Q-036 marked resolved, Q-037 scope defined. SI creates Sprint 22 candidate tickets for the chunk/district pipeline implementation.

## Test Plan Alignment (D-030)

Sprint 21 is Phase 3+ territory. The template instantiation system introduces the first simulation structures that compose content from YAML definitions into live ECS entities.

| Ticket | Test scope | Priority |
|--------|------------|----------|
| #159 | Unit: YAML round-trip, full Tier 2 document | High |
| #166 | Unit: spawn + TemplateOwnership, TemplateReferenceMap entries | High |
| #161 | Integration: YAML → instantiation engine → ECS entities + triangles | High |
| #108 | Unit: cross-template role assignment, reference link creation | High |
| #109 | Unit: all three validation failure modes + passing case | High |
| #85 | Integration: malformed input → SimError, server survives | High |
| #246 | Unit: Door walkability toggle, examine text return | High |
| #257 | End-to-end: F5 save → F6 load → state match | High |
| #561 | Regression: `make ci-client` passes at new file path | Medium |
| #564 | Visual: Fog Theater gauntlet room manual check | High |
| #274 | Regression: `make ci` passes with scripts at new paths | High |

## Cross-Team Integration Points

| Server ticket | Client dependency | Notes |
|---------------|-------------------|-------|
| #246 (`open_doors` in `SaveStateV1`) | #257 (save/load round-trip) | Server must add `open_doors: Vec<StableId>` to save struct before client can verify state restored correctly |
| #85 (`SimError` message type) | #257 (loading screen) | Loading screen should handle `SimError` gracefully — show error state, not spinner forever |

| Planning ticket | Downstream impact | Notes |
|-----------------|-------------------|-------|
| #562 (generator architecture) | #143, #144 (chunk system) | D-record output gates Sprint 22 chunk pipeline work |

The #246/#257 dependency is soft — client can stub the door state verification in save/load tests until #246 lands.

## Deferred to Sprint 22

Natural Sprint 22 candidates once this sprint's foundation lands:

- **#155** (Hand-crafted location authoring) — build the v0.1 Transit District locations in Godot tilemap; requires #153 (done) and the district topology from that D-record
- **#188** (Triangle instantiation in v0.1 content) — wire the 5 v0.1 triangles into the instantiation engine; requires #161
- **#162** (Storyteller module activation) — draw Tier 1 modules from pool at game start; requires #161
- **#143** (Chunk data structure) — blocked until #562 workshop defines the spatial hierarchy
- **#176** (NPC pool generation: flat/mundane/entangled ratio) — requires #161 instantiation engine
- Generator pipeline tickets — created by SI from #562 D-record outputs