docs(workshops): add 5 architecture spike workshop briefs

Workshop briefs for the larger spikes identified by the architecture review audit: knowledge graph & information boundaries, observer snapshot pipeline, NPC AI state machines, save/load architecture, and map authoring pipeline. Each includes participants, key questions, input documents, and expected outputs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-11 21:36:02 +01:00
parent e1a3913060
commit 1920f002a1
6 changed files with 380 additions and 0 deletions
@@ -0,0 +1,75 @@
+# Map Authoring Pipeline Workshop Brief
+
+**Goal:** Define how v0.1 maps (5-8 hand-crafted buildings per world, 150x150 tiles, 2-3 z-levels) are authored, stored, and loaded by both server and client.
+**Ticket:** #355 (epic)
+**Priority:** MEDIUM — Sprint 2-3 target
+**Participants:** Tyre (architecture lead), Stig (client rendering), Araminta (visual design), Dudley (server loading), Qatux (docs), Si (tickets)
+**Source:** Architecture Review Audit 2026-02-11, Tyre R-09
+
+## Context
+
+D-014 specifies 3 worlds with ~150x150 tile maps, 2-3 z-levels, and 5-8 hand-crafted buildings per world. The chunk-based `WalkabilityMap` exists (`server/src/simulation/movement.rs`) for collision, but there is no:
+- Tile type system (floor, wall, door, furniture, etc.)
+- Visual tile data (what the client renders)
+- Map authoring tool or format
+- Map loading pipeline for either server or client
+
+The audit recommends **Tiled editor** (mature, cross-platform, JSON export) but this needs validation against the project's specific requirements (z-levels, entity spawn points, per-tile metadata like walkability and LOS blocking).
+
+## Key Questions to Resolve
+
+### Authoring Tool
+1. Tiled vs Godot TileMap editor vs hand-authored YAML/JSON? (Audit recommends Tiled)
+2. If Tiled: which export format? (JSON, TMX/XML, CSV?)
+3. How are buildings authored separately and placed into the world map?
+4. How are z-levels represented? (Separate layers? Separate files? Tiled group layers?)
+
+### Tile Data Model
+5. What tile types exist? (floor, wall, wall_half, door, window, furniture, decoration?)
+6. What per-tile metadata is needed? (walkable, blocks_los, blocks_sound, interaction_type?)
+7. How do tiles map to the WalkabilityMap? (Direct 1:1? Computed from tile properties?)
+8. How are tile visuals defined? (Sprite atlas indices? Named references? Autotile rules?)
+
+### Map Format
+9. What's the canonical map format the server loads? (Tiled JSON? Custom binary? TOML?)
+10. Does the client load the same format or a different one? (Server = collision/logic, client = visual)
+11. How are entity spawn points defined in the map? (NPC start positions, item placements)
+12. How are social sites (D-025) tagged in the map? (Zone markers, named regions)
+
+### Loading Pipeline
+13. How does the server load maps into the chunk-based system?
+14. How does the client load maps into TileMapLayer nodes?
+15. Is hot-reload supported for iteration? (Edit map, reload in running game)
+16. How are map assets versioned? (Save files reference map version?)
+
+### Visual Design
+17. What is the tile size? (16x16, 32x32, 64x64?)
+18. How does the v0.1 visual grammar (D-003, v0.1 placeholder art) apply to tiles?
+19. How do zone-specific color palettes (per Araminta's visual grammar) affect tile rendering?
+20. How does fog overlay interact with the tile layers? (Audit recommends TileMapLayer for fog)
+
+## Input Documents
+
+| Document | What to read | Why |
+|----------|-------------|-----|
+| `decisions/scope.md` | D-012 (chunks), D-014 (map spec) | Map requirements |
+| `decisions/scope.md` | D-025 (social site templates) | Location definitions |
+| `server/src/simulation/movement.rs` | WalkabilityMap, chunk system | Existing server-side map code |
+| `client/scenes/main.tscn` | Current scene structure | Where tilemap nodes go |
+| `client/scripts/rendering/world_renderer.gd` | World rendering stub | Client rendering entry point |
+| Spatial layout tickets (#311-313) | Bar, logistics hub, smuggling spaces | Specific buildings to author |
+
+## Expected Outputs
+
+1. **Decision: D-0XX — Map Authoring Pipeline** — Tool choice, format, loading pipeline
+2. **Tile type specification:** Enum of tile types with properties (walkable, blocks_los, etc.)
+3. **Map format schema:** Documentation of the canonical format both sides load
+4. **Authoring guide:** How to create a new building/location using the chosen tool
+5. **Tickets:** Implementation tasks (server loader, client loader, tile type system, first test map)
+6. **Proof of concept:** One building loaded and rendered in both server and client
+
+## Workshop Format
+
+Two rounds:
+- **Round 1:** Each participant analyzes from their domain (Tyre: format/loading, Stig: client rendering, Araminta: visual requirements, Dudley: server integration)
+- **Round 2:** Cross-review, tool evaluation, finalize pipeline