jpmschweitzerandClaude Opus 4.6
bccdcfcdcb
Standardized YAML frontmatter on all 115 sprint briefing files across sprints 1-26 with title, description, type, status, sprint number, and team fields. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
126 lines
9.2 KiB
Markdown
126 lines
9.2 KiB
Markdown
---
|
|
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
|