# 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