# 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