ttrpg-initiative-tracker/docs/ENCOUNTER_BUILDER.md

# Encounter Builder — DM Interface Guide

How a DM (or LLM automating the DM role) builds and runs encounters via the UI and storage layer. Covers entity model, build flow, combat controls, and the storage paths backing each action.

## Entity model

Three nested entities. All stored as opaque JSON docs in the KV store (generic doc store — see `docs/DEVELOPMENT.md`).

```
Campaign
  └─ Encounter(s)
       └─ Participant(s)
```

Plus two global docs:
- `activeDisplay/status` — controls player view (which campaign+encounter, hide-HP flag)
- `logs/{id}` — append-only action log entries

### Campaign

Path: `artifacts/{APP_ID}/public/data/campaigns/{campaignId}`

| Field | Type | Notes |
|---|---|---|
| `name` | string | |
| `playerDisplayBackgroundUrl` | string | optional, image URL for player display bg |
| `ownerId` | string | user id |
| `createdAt` | ISO string | |
| `players` | array | campaign-level character roster (templates, NOT combatants) |

Campaign characters = reusable templates. Default HP + init mod. Added to any encounter via ParticipantManager. Not combatants themselves.

### Encounter

Path: `artifacts/{APP_ID}/public/data/campaigns/{campaignId}/encounters/{encounterId}`

| Field | Type | Notes |
|---|---|---|
| `name` | string | |
| `createdAt` | ISO string | |
| `participants` | array | the combatants (see below) |
| `round` | int | 0 = not started |
| `currentTurnParticipantId` | string\|null | who acts now |
| `isStarted` | bool | combat active |
| `isPaused` | bool | frozen turn order (add/remove/edit allowed) |
| `turnOrderIds` | array | participant ids in turn order = participants[] order (1-list model) |

### Participant

Object in `encounter.participants[]`:

| Field | Type | Notes |
|---|---|---|
| `id` | string | `generateId()` |
| `name` | string | |
| `type` | `'character'` \| `'monster'` | character = PC (death saves), monster = hostile/NPC |
| `originalCharacterId` | string\|null | links back to campaign character if type=character |
| `initiative` | int | rolled once at add (`rollD20() + mod`). Stored value, not re-derived. |
| `maxHp` | int | |
| `currentHp` | int | 0 = dead/dying |
| `isNpc` | bool | monster flagged NPC (display color, no death saves) |
| `conditions` | array | condition ids from `CONDITIONS` list |
| `isActive` | bool | in turn rotation? false = skipped by nextTurn |
| `deathSaves` | int | PC only, 0-3 fails |
| `isDying` | bool | death animation flag (player display) |

## Build flow (UI)

Admin view at `/`. Steps:

### 1. Create campaign
- Click **Create Campaign** button
- Enter name + optional background URL
- Submits → `setDoc(campaigns/{id}, { name, playerDisplayBackgroundUrl, ownerId, createdAt, players:[] })`

### 2. Select campaign
- Click campaign card → `setSelectedCampaignId(campaign.id)`
- Now managing: CharacterManager + EncounterManager visible

### 3. Add campaign characters (optional templates)
CharacterManager section. Per character:
- **Name**
- **Default HP** (`DEFAULT_MAX_HP` = 10)
- **Init Mod** (`DEFAULT_INIT_MOD` = 0)

→ `updateDoc(campaign, { players:[...existing, newChar] })`

These are reusable across encounters. Add to encounter later (auto-rolls initiative).

### 4. Create encounter
- Click **Create Encounter**
- Enter name
→ `setDoc(campaigns/{cid}/encounters/{eid}, { name, createdAt, participants:[], round:0, currentTurnParticipantId:null, isStarted:false, isPaused:false })`

### 5. Add participants
ParticipantManager section. Two paths:

**Monster/NPC:**
- **Monster Name** (`placeholder: "e.g., Dire Wolf"`)
- **Init Mod** (`MONSTER_DEFAULT_INIT_MOD` = 2)
- **Max HP** (`DEFAULT_MAX_HP` = 10)
- **Is NPC?** checkbox (flag, changes display color)
- Click **Add to Encounter**
- Initiative auto-rolled: `rollD20() + mod`

**Character (from campaign roster):**
- Select character from dropdown
- Click **Add to Encounter**
- OR **Add All (Roll Init)** — bulk-adds all campaign chars, each rolls own initiative

**Duplicate guard:** same `originalCharacterId` blocked (alerts "already in this encounter"). Monsters no dedup.

Participant object added:
```js
{ id, name, type, originalCharacterId, initiative, maxHp, currentHp:maxHp,
  isNpc, conditions:[], isActive:true, deathSaves:0, isDying:false }
```

### 6. Reorder before start (tie-break)
Pre-combat only (`!isStarted || isPaused`). Drag handles shown for **tied initiative** values only. Drop reorders `participants[]` + `turnOrderIds`.

Post-start drag: see BUG-13/14 in `TODO.md` (cross-init + pointer semantics untested).

## Combat flow (UI)

InitiativeControls panel (sticky, right side).

### Start
- **Start Combat** button (disabled if no active participants)
- Sorts ALL participants by initiative (1-list: `participants[]` = display + turn order)
- `round=1`, `currentTurnParticipantId` = first active, `isStarted=true`, `isPaused=false`
- Sets `activeDisplay` → this campaign+encounter (player display syncs)
- Initiative fixed at start. NOT re-derived from mod after.

### Next Turn
- **Next Turn** button (disabled if paused)
- Advances to next active participant in `turnOrderIds`
- Wraps at end → `round += 1`, re-sorts active by initiative at round start
- Dead (`isActive:false`) skipped, stay in rotation

### Pause / Resume
- **Pause Combat** → `isPaused=true`, Next Turn disabled
- While paused: add/remove participants, adjust HP, edit initiative, reorder ties
- **Resume Combat** → `isPaused=false`, no re-sort (1-list: turnOrderIds already current)

### HP adjustments (combat only)
Per-participant input + buttons:
- Number input
- **Damage** (HeartCrack icon) — `currentHp = max(0, hp - amt)`
- **Heal** (Heart icon) — `currentHp = min(maxHp, hp + amt)`
- Death: hp→0 sets `isActive:false`, PC gets `deathSaves` tracking

### Death saves (PC only, at 0 HP)
3 buttons. Click marks fail. 3 fails = dead. Reset on revive/heal.

### Conditions
- Click participant → expand conditions picker (all 22 from `CONDITIONS`)
- Active conditions show as badges, click to remove

### End combat
- **End Combat** button → resets `isStarted:false`, `round:0`, `currentTurn:null`, `turnOrderIds:[]`
- Clears `activeDisplay` (player view goes blank)

## Player display

Separate view at `/display` or `?playerView=true`. Read-only second screen.

What it shows:
- Current encounter name
- Round + current turn participant
- All participants in `participants[]` order (drag order, NOT init-sorted — BUG-15 fix)
- HP bars, conditions, death saves
- Inactive monsters hidden (pre-staged reserves)

Driven by `activeDisplay/status` doc. Controlled by **Open Player Window** button (sets active campaign+encounter) or Start Combat (auto-sets).

## 1-list turn order model

Key architecture. `turnOrderIds === participants.map(p => p.id)` always. Single source of truth.

- **Display** = `participants[]` order (AdminView + DisplayView, no re-sort)
- **Turn rotation** = `turnOrderIds` (mirrors participants[])
- **Drag** = source of truth, overrides initiative
- **Add mid-combat** = append to participants[] + sync (BUG-14: init-insert broken post-drag)
- **Toggle active** = flip `isActive` only, stay in slot
- **Remove** = drop from participants[] + sync, advance current if needed

No re-sort after `startEncounter` except round-wrap (re-sorts active by init at top of round).

## Storage paths quick reference

```
campaigns/{cid}                              campaign doc
campaigns/{cid}/encounters/{eid}             encounter doc (participants[])
campaigns/{cid}/encounters/{eid}/participants  ❌ NOT a path — participants inline
activeDisplay/status                         player display control
logs/{logId}                                 action log entry
```

## DM tips

- Initiative rolled ONCE at add time. Stored. Edit via EditParticipantModal to override.
- Pause before big roster changes (adds/removes). Resume re-syncs cleanly.
- Campaign chars = templates. Edit campaign char doesn't touch encounter participants (already added).
- Dead monsters stay in rotation, skipped. Remove via trash icon to clean list.
- Player display auto-follows Start Combat. Manual control via Open Player Window.

See `docs/GLOSSARY.md` for domain terms, `TODO.md` for known bugs.