diff --git a/docs/workshops/README.md b/docs/workshops/README.md index b69600d35..78fa98f15 100644 --- a/docs/workshops/README.md +++ b/docs/workshops/README.md @@ -19,3 +19,9 @@ docs/workshops/ |----------|-------|--------| | [Content Architecture](content-architecture/) | 17 | Complete | | [v0.1 Gap Analysis](v01-gap-analysis/) | 18 | Complete | +| [Content Gap Analysis v0.1](content-gap-analysis_v0_1/) | — | Complete | +| [Knowledge Graph & Information Boundaries](knowledge-graph-information-boundaries/) | — | Brief ready | +| [Observer Snapshot Pipeline](observer-snapshot-pipeline/) | — | Brief ready (blocked by Knowledge Graph) | +| [NPC AI State Machines](npc-ai-state-machines/) | — | Brief ready | +| [Save/Load Architecture](save-load-architecture/) | — | Brief ready | +| [Map Authoring Pipeline](map-authoring-pipeline/) | — | Brief ready | diff --git a/docs/workshops/knowledge-graph-information-boundaries/workshop-brief.md b/docs/workshops/knowledge-graph-information-boundaries/workshop-brief.md new file mode 100644 index 000000000..6781b951a --- /dev/null +++ b/docs/workshops/knowledge-graph-information-boundaries/workshop-brief.md @@ -0,0 +1,71 @@ +# Knowledge Graph & Information Boundaries Workshop Brief + +**Goal:** Design the knowledge data structure that replaces `InformationInventory { known_facts: Vec }` — the pillar-1 mechanic foundation for asymmetric information. +**Ticket:** #351 (epic) +**Priority:** CRITICAL — Sprint 2 blocker +**Participants:** Tyre (architecture lead), Gestalt (mechanics), Paula (narrative), Dudley (implementation), Qatux (docs), Si (tickets) +**Source:** Architecture Review Audit 2026-02-11, Consensus Recommendation #12 + +## Context + +The architecture audit independently identified the knowledge graph as the **most important and least specified critical system**. Both Tyre and Troblum rated it CRITICAL. + +D-010 principle 2 says: "every piece of game state is tagged with who knows it." The current implementation in `server/src/npc/mod.rs` has `InformationInventory { known_facts: Vec }` — a placeholder that cannot support observation, monologue, dialogue, or success criteria. + +This system is load-bearing for: +- D-010: Multiplayer-ready information boundaries +- D-011: Fog of perception (what returns when you leave) +- D-017: Perception modes (what different modes reveal) +- D-028: Tagged line pools (access-tier dialogue) +- D-033: Entity color from relationship state +- Q-016: Knowledge hierarchy (`suspects` < `knows_of` < `knows_details`) + +## Key Questions to Resolve + +### Data Structure +1. What does "entity A knows about entity B" look like as a Rust struct? +2. How is knowledge confidence tracked? (Q-016: hierarchy levels) +3. How does knowledge decay over time? (D-011: "fog returns when you leave") +4. How are non-entity facts tracked? (locations, events, relationships between others) + +### Knowledge Flow +5. How does knowledge enter the graph? (Direct observation, told by NPC, inferred) +6. How does the `KnowledgeSource` affect confidence? +7. Can knowledge be wrong? (Misinformation, outdated information) +8. How do NPCs share knowledge with each other? (Gossip, reports, investigations) + +### Performance +9. At 80 Active NPCs, each knowing about ~50 entities, what's the memory budget? +10. How is the knowledge graph queried efficiently for observer snapshot generation? +11. Does knowledge graph update need spatial partitioning? (Only update knowledge for nearby entities) + +### Game Mechanics Integration +12. How does the knowledge graph drive monologue triggers? (D-019, tickets #119-122) +13. How does knowledge state affect dialogue access tiers? (D-028) +14. How do social triangles interact with knowledge? (Does knowing about a triangle change behavior?) + +## Input Documents + +| Document | What to read | Why | +|----------|-------------|-----| +| `decisions/perception.md` | D-011, D-015-D-019 | Perception system requirements | +| `decisions/architecture.md` | D-010 (principles), D-024 (NPC model), D-026 (simulation tiers) | Architecture constraints | +| `decisions/content.md` | D-028 (tagged line pools), D-033 (entity color) | Content system dependencies | +| `decisions/questions.md` | Q-016 (knowledge hierarchy), Q-017 (triangle pressure) | Open questions this workshop should resolve | +| `server/src/npc/mod.rs` | Current NPC component model | What exists today | +| `server/src/perception/mod.rs` | Perception plugin stub | Where this code will live | +| `docs/audits/architecture-review-2026-02-11.md` | Tyre R-01, Troblum section 4 | Detailed analysis and proposals | + +## Expected Outputs + +1. **Decision: D-0XX — Knowledge Graph Data Model** — Rust struct definitions for `KnowledgeGraph`, `EntityKnowledge`, `KnowledgeConfidence`, `KnowledgeSource` +2. **Decision: Resolution of Q-016** — Knowledge hierarchy levels with concrete enum values +3. **Design document:** Knowledge flow specification (how knowledge enters, propagates, decays) +4. **Tickets:** Implementation tasks broken down from the design +5. **Performance budget:** Memory and query time targets at 80 NPCs + +## Workshop Format + +Two rounds, following project convention: +- **Round 1:** Each participant independently analyzes the questions from their domain perspective +- **Round 2:** Cross-review, debate, and synthesis into concrete decisions diff --git a/docs/workshops/map-authoring-pipeline/workshop-brief.md b/docs/workshops/map-authoring-pipeline/workshop-brief.md new file mode 100644 index 000000000..d40ca2c3d --- /dev/null +++ b/docs/workshops/map-authoring-pipeline/workshop-brief.md @@ -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 diff --git a/docs/workshops/npc-ai-state-machines/workshop-brief.md b/docs/workshops/npc-ai-state-machines/workshop-brief.md new file mode 100644 index 000000000..069b4bf4f --- /dev/null +++ b/docs/workshops/npc-ai-state-machines/workshop-brief.md @@ -0,0 +1,77 @@ +# NPC AI State Machines Workshop Brief + +**Goal:** Specify the 4 Background-tier state machines (schedule, mood, relationships, job) — states, transitions, day phase integration, and tick budgets. +**Ticket:** #353 (epic) +**Priority:** HIGH — Sprint 3 target +**Participants:** Gestalt (mechanics lead), Paula (narrative), Dudley (implementation), Tyre (architecture), Nigel (emergent play), Qatux (docs), Si (tickets) +**Source:** Architecture Review Audit 2026-02-11, Tyre R-06 + +## Context + +D-026 defines four simulation tiers. Background-tier NPCs (500-2,000) run "state machine ticks" at 1/game-minute frequency. D-026 mentions "4 state machines: schedule, mood, relationships, job" but provides no specification of states, transitions, or interactions. + +The NPC component model (D-024, `server/src/npc/mod.rs`) defines 10 axes including `DailyRoutine`, `MoodState`, `RelationshipWeb`, and `Occupation` — but these are type stubs without behavior logic. + +This workshop must produce state machine specifications that are: +- **Implementable** — Clear states and transition rules Dudley can code +- **Interesting** — State interactions that produce emergent NPC behavior (Gestalt, Nigel) +- **Narratively grounded** — State changes that create observable drama (Paula) +- **Performant** — Within the 1/game-minute update budget for 500+ NPCs (Tyre) + +## Key Questions to Resolve + +### Schedule FSM +1. What are the schedule states? (work, home, social, sleep, commute, errand?) +2. How do day phases (D-031: morning, afternoon, evening, night) drive transitions? +3. How do schedules vary by NPC type? (worker, socialite, loner, authority figure) +4. What makes an NPC deviate from their routine? (Events, mood, relationship pressure) + +### Mood FSM +5. What are the mood states? (calm, stressed, suspicious, friendly, hostile, afraid?) +6. What events trigger mood transitions? (Observation, confrontation, social pressure) +7. How does mood affect schedule? (Stressed NPC skips social time? Suspicious NPC changes route?) +8. How does mood affect dialogue access? (D-028 tag system integration) + +### Relationship FSM +9. What are the relationship states? (stranger, acquaintance, friend, ally, rival, enemy?) +10. How do relationships change? (Repeated interaction, shared knowledge, betrayal, trust) +11. How do social triangles (D-024) create relationship pressure? +12. How does Q-017 (triangle pressure threshold) feed into relationship transitions? + +### Job FSM +13. What are the job states? (idle, working, break, commute, off-duty?) +14. How does job interact with schedule? (Job state constrains schedule options) +15. How do different occupations (dock worker, security, merchant, bureaucrat) vary? +16. How does job state affect what the NPC knows? (Location access, information exposure) + +### Cross-Machine Interactions +17. How do the 4 machines communicate? (Shared blackboard? Event bus? Direct reads?) +18. What's the priority when machines conflict? (Mood says "flee" but schedule says "work") +19. How do Active-tier NPCs differ from Background-tier? (Full AI vs state machine only) +20. How does tier transition preserve state? (Active NPC drops to Background — which state is kept?) + +## Input Documents + +| Document | What to read | Why | +|----------|-------------|-----| +| `decisions/architecture.md` | D-026 (simulation tiers), D-031 (time/day phases) | Tier and timing constraints | +| `decisions/scope.md` | D-024 (NPC model), D-025 (social sites) | NPC components and locations | +| `decisions/content.md` | D-028 (tagged line pools), D-034 (THE FRIEND) | Content dependencies | +| `decisions/questions.md` | Q-016, Q-017 | Open questions about knowledge hierarchy and triangle pressure | +| `server/src/npc/mod.rs` | Current component stubs | What exists today | +| `server/src/simulation/tier.rs` | Tier system stub | Where tier logic lives | + +## Expected Outputs + +1. **Decision: D-0XX — NPC State Machine Specification** — States, transitions, and interaction rules for all 4 machines +2. **Decision: Resolution of Q-017** — Triangle pressure threshold mechanics +3. **State diagram:** Visual state machines for each FSM (can be Mermaid diagrams) +4. **Transition tables:** For each FSM, a table of (current_state, event) -> new_state +5. **Performance budget:** Per-NPC update cost at Background tier frequency +6. **Tickets:** Implementation tasks for each FSM + cross-machine integration + +## Workshop Format + +Two rounds: +- **Round 1:** Each participant designs the machines from their domain (Gestalt: mechanics, Paula: narrative weight, Nigel: emergent play, Tyre: performance, Dudley: implementation feasibility) +- **Round 2:** Cross-review and reconcile — especially where mechanics vs narrative vs performance conflict diff --git a/docs/workshops/observer-snapshot-pipeline/workshop-brief.md b/docs/workshops/observer-snapshot-pipeline/workshop-brief.md new file mode 100644 index 000000000..ebb922dea --- /dev/null +++ b/docs/workshops/observer-snapshot-pipeline/workshop-brief.md @@ -0,0 +1,80 @@ +# Observer Snapshot Generation Pipeline Workshop Brief + +**Goal:** Design the algorithm for "what does entity X perceive this tick?" — the server-side pipeline that computes ObserverSnapshot from world state. +**Ticket:** #352 (epic, blocked by #351) +**Priority:** CRITICAL — Sprint 2 blocker +**Participants:** Tyre (architecture lead), Dudley (implementation), Troblum (algorithm review), Qatux (docs), Si (tickets) +**Source:** Architecture Review Audit 2026-02-11, Consensus Recommendation #13 +**Dependency:** Workshop 1 (Knowledge Graph) must complete first — this pipeline consumes the knowledge graph. + +## Context + +Both audit reviewers independently flagged the observer snapshot pipeline as CRITICAL and unspecified. The `ObserverSnapshot` wire type exists (`server/src/bridge/types.rs`) but the algorithm that populates it does not. + +This pipeline IS the game loop from the client's perspective. Every tick, the server must: +1. Determine what the observer can see (spatial + LOS) +2. Determine what the observer can hear (sound propagation) +3. Filter visible state through the observer's knowledge graph +4. Assemble the snapshot for transmission + +The pipeline must run within the 100ms tick budget at 80 Active NPCs (D-026). + +## Key Questions to Resolve + +### Pipeline Stages +1. What are the exact stages? (spatial query → LOS → sound → knowledge filter → assembly?) +2. Which stages can be parallelized? (bevy_ecs system parallelism) +3. What order do stages run in the bevy_ecs schedule? + +### Spatial Query +4. How does the spatial index (ticket #340, SpatialIndex trait) feed into perception? +5. What's the perception range? Fixed or variable by perception mode (D-017)? +6. How do z-levels affect spatial queries? (D-014: 2-3 z-levels) + +### Line of Sight +7. Which shadowcasting algorithm? (Q-018 — may resolve here or separately) +8. How do vision cones (D-015: forward/peripheral/behind) modify base LOS? +9. How do perception modes (D-017: thermal, camera, etc.) alter what's "visible"? +10. What is the LOS cache strategy? (Per-tick full recompute vs incremental?) + +### Sound Propagation +11. How does three-range sound (D-018) map to the spatial query? +12. Does sound propagation through walls need a separate algorithm? +13. How are sound events created and consumed within a tick? + +### Snapshot Assembly +14. What fields does ObserverSnapshot need beyond the current `tick` + `Vec`? +15. How is fog grid data encoded? (Bitfield? Per-tile enum?) +16. When should delta compression be introduced? (Design interface now, implement later?) + +### Performance +17. What's the per-tick budget breakdown? (e.g., spatial 5ms, LOS 20ms, sound 5ms, assembly 10ms) +18. Can perception updates be staggered across ticks for NPCs far from the player? +19. How many LOS queries can run within budget at 150x150? + +## Input Documents + +| Document | What to read | Why | +|----------|-------------|-----| +| `decisions/perception.md` | D-011, D-015, D-016, D-017, D-018, D-019 | Full perception spec | +| `decisions/architecture.md` | D-010, D-020, D-026, D-030, D-031 | Architecture + time constraints | +| `server/src/bridge/types.rs` | ObserverSnapshot, VisibleEntity types | Current wire format | +| `server/src/perception/mod.rs` | Perception plugin stub | Where this code will live | +| `server/src/simulation/movement.rs` | WalkabilityMap | Tile data available for LOS | +| `docs/audits/architecture-review-2026-02-11.md` | Tyre R-02, R-04; Troblum section 5 | Detailed proposals | +| Workshop 1 output | KnowledgeGraph design | Knowledge filtering input | + +## Expected Outputs + +1. **Decision: D-0XX — Observer Snapshot Pipeline** — Stage definitions, ordering, bevy_ecs system layout +2. **Decision: Resolution of Q-018** — Shadowcasting algorithm choice (or defer to separate spike) +3. **Algorithm specification:** Pseudocode for each pipeline stage +4. **Performance budget:** Per-stage timing targets at 80 Active NPCs +5. **Tickets:** Implementation tasks per stage +6. **ObserverSnapshot v2 schema:** Extended wire format with fog, sound, monologue fields + +## Workshop Format + +Two rounds: +- **Round 1:** Each participant independently analyzes the pipeline from their perspective +- **Round 2:** Cross-review, reconcile performance budgets, finalize algorithm choices diff --git a/docs/workshops/save-load-architecture/workshop-brief.md b/docs/workshops/save-load-architecture/workshop-brief.md new file mode 100644 index 000000000..f18ca3f9a --- /dev/null +++ b/docs/workshops/save-load-architecture/workshop-brief.md @@ -0,0 +1,71 @@ +# Save/Load Architecture Workshop Brief + +**Goal:** Design the save/load system — serialization strategy, versioning, migration, and relationship to tier serialization. +**Ticket:** #354 (epic) +**Priority:** MEDIUM — must resolve before vertical slice +**Participants:** Tyre (architecture lead), Dudley (implementation), Troblum (evaluation), Qatux (docs), Si (tickets) +**Source:** Architecture Review Audit 2026-02-11, Tyre R-08 + +## Context + +Save/load is not addressed in any existing decision document or ticket. Both audit reviewers flagged this as a gap that must be resolved before the vertical slice. + +The audit consensus recommends a **custom SaveState struct** over bevy_reflect, with versioning and migration. Troblum notes this creates a third data model alongside ECS components and ObserverSnapshot — every NPC component change requires updating 3 places. + +D-026 defines tier serialization for State-saved NPCs (~1-2KB per frozen entity). The save/load system must interoperate with this — a full save includes all tiers, while tier serialization handles individual NPC state-save/restore during gameplay. + +## Key Questions to Resolve + +### Serialization Strategy +1. Custom `SaveState` struct vs bevy_reflect vs hybrid? (Audit recommends custom) +2. What is serialized? (All ECS components? Only authoritative state? Derived state rebuilt on load?) +3. What format? (bincode for speed, MessagePack for debuggability, JSON for human-readability?) +4. How large is a typical save? (15 NPCs x 1-2KB + map state + knowledge graphs + game clock) + +### Versioning +5. What version scheme? (Semantic? Monotonic integer?) +6. How are migrations handled? (Forward-only? Rollback support?) +7. What triggers a version bump? (Any component change? Only breaking changes?) +8. How is backwards compatibility tested? + +### Tier Integration +9. How does full-save serialization relate to tier serialization (#96)? +10. State-saved NPCs are already serialized blobs — does save/load wrap these directly? +11. Active-tier NPCs need full component serialization — same format as State-saved, or different? +12. How does the knowledge graph serialize? (Per-entity? Separate table?) + +### Architecture +13. Where does save logic live? (bevy_ecs system? Separate module outside the schedule?) +14. How is save triggered? (Manual save, autosave, checkpoint?) +15. What about save corruption? (Checksums? Atomic writes? Backup previous save?) +16. Quick save vs named saves — different mechanisms or same with different metadata? + +### Client-Side +17. Does the client need save/load awareness? (Save menu, load screen, save file browser) +18. How does save/load interact with the IPC bridge? (Pause simulation, serialize, resume?) +19. Are save files portable across platforms? (Q-007 implications) + +## Input Documents + +| Document | What to read | Why | +|----------|-------------|-----| +| `decisions/architecture.md` | D-010, D-020, D-026 | Architecture constraints, tier system | +| `server/src/npc/mod.rs` | NPC component model | What needs serializing | +| `server/src/simulation/tier.rs` | Tier system stub | Existing serialization infrastructure | +| `server/src/simulation/rng.rs` | SimRng (ChaCha20 seed) | RNG state must be saved for determinism | +| `server/src/simulation/time.rs` | SimulationTime | Game clock state | +| `server/Cargo.toml` | serde, rmp-serde dependencies | Available serialization tools | + +## Expected Outputs + +1. **Decision: D-0XX — Save/Load Architecture** — Strategy, format, versioning scheme +2. **SaveState schema:** Rust struct definitions with serde derives +3. **Migration strategy:** How version N saves load in version N+1 +4. **Integration spec:** How save/load interacts with tier serialization +5. **Tickets:** Implementation tasks (server save system, client save UI, save format tests) + +## Workshop Format + +Two rounds: +- **Round 1:** Each participant analyzes from their domain (Tyre: architecture, Dudley: implementation, Troblum: risk and alternatives) +- **Round 2:** Cross-review, resolve trade-offs, finalize schema