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'` \| `'npc'` \| `'monster'` | character/NPC = death saves, monster = dead at 0 HP |
| `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/stable by `status` |
| `conditions` | array | condition ids from `CONDITIONS` list |
| `isActive` | bool | in turn rotation? false = skipped by nextTurn |
| `status` | `'conscious'` \| `'dying'` \| `'stable'` \| `'dead'` | death-save source of truth |
| `deathSaveSuccesses` | int | character/NPC only, 0-3 successes |
| `deathSaveFailures` | int | character/NPC only, 0-3 failures |

## Path normalization

App passes firebase-prefixed paths (`artifacts/{APP_ID}/public/data/campaigns/...`). Server-mode adapter `norm()` strips prefix → bare canonical (`campaigns/...`).

- **UI / app code** → prefixed paths (`getPath.*` helpers)
- **REST API / direct DB / scripts** → bare canonical paths (`campaigns/...`)

Mixing = empty results. If `GET /api/collection?path=artifacts/.../campaigns` returns `[]`, you used the prefixed form. Drop the prefix.

## 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 (sets `type: 'npc'`, keeps monster/DM-control color, enables death saves)
- 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,
  conditions:[], isActive:true, status:'conscious', deathSaveSuccesses:0, deathSaveFailures:0 }
```

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

During active combat, cross-current-pointer drag is blocked to avoid skip/double-act ambiguity. Paused combat can reorder same-initiative ties freely.

## Build flow (API / scripts)

Same logical steps as UI, via REST. For LLM agents or seed scripts.

**Server mode only.** REST endpoints (`/api/*`) exist only when tracker runs
with `REACT_APP_STORAGE=server` (bundled Express backend mounted). Firebase
SDK mode has no HTTP backend — data lives in Firestore via in-browser SDK,
different auth + write paths. This section does not apply to firebase mode.

Confirm server mode before scripting:
```bash
curl -s <HOST>/api/collection?path=campaigns | head -c 200
```
JSON array = server mode. HTML (SPA shell) = firebase mode or backend not
mounted — API path won't work.

### REST endpoints

| Method | Path | Body / Query | Action |
|---|---|---|---|
| `GET` | `/api/doc` | `?path=` | read one doc |
| `PUT` | `/api/doc` | `{path, data}` | replace doc |
| `PATCH` | `/api/doc` | `{path, patch}` | shallow merge, create-on-miss |
| `DELETE` | `/api/doc` | `?path=` | delete one doc |
| `GET` | `/api/collection` | `?path=` | list docs under collection |
| `POST` | `/api/collection` | `{path, data}` | addDoc: auto-id under collection |
| `POST` | `/api/batch` | `{ops:[{type:'set'\|'update'\|'delete', path, data?}]}` | atomic multi-write |

All paths bare canonical (no `artifacts/...` prefix).

### id format

`generateId()` = `crypto.randomUUID()` (fallback `id_{Date.now()}_{rand10}`). Use either. Server `POST /api/collection` generates its own UUID — fine for campaigns/encounters. Participants are inline array items; generate their ids client-side so they're stable across batch writes.

### Object templates

Encounter doc (full, for `PUT` / batch `set`):
```js
{
  name: 'Barrowdeep 1 - Antechamber',
  createdAt: new Date().toISOString(),
  participants: [],          // inline, NOT a sub-collection
  round: 0,
  currentTurnParticipantId: null,
  isStarted: false,
  isPaused: false,
  ruleset: '5e',
}
```

Participant object (item in `encounter.participants[]`):
```js
{
  id: generateId(),
  name: 'Ankheg',
  type: 'monster',            // 'character' | 'npc' | 'monster'
  originalCharacterId: null,  // set only if type==='character'
  initiative: rollD20() + initMod,  // rolled ONCE at add; stored, not re-derived
  maxHp: 45,
  currentHp: 45,              // start at full
  conditions: [],
  isActive: true,
  status: 'conscious',
  deathSaveSuccesses: 0,      // character/npc only
  deathSaveFailures: 0,       // character/npc only
}
```

### Initiative semantics

- Default: `initiative = rollD20() + initMod` (d20 ∈ [1,20], roll fresh per participant).
- Manual override (e.g. pre-rolled values): set `initiative` directly, skip the roll.
- Fixed at add time. NOT re-derived from `initMod` after — `initMod` is not stored on participant.

### Recipe: build encounters for a campaign

1. **Find campaign id by name:**
```bash
curl -s "$HOST/api/collection?path=campaigns" \
  | jq -r '.[] | select(.name=="2026 D&D") | .id'
```
2. **Build encounter docs + participants client-side** (object templates above), roll initiative per participant.
3. **Write all encounters in one batch:**
```bash
curl -s -X POST "$HOST/api/batch" \
  -H 'Content-Type: application/json' \
  -d '{"ops":[{"type":"set","path":"campaigns/CID/encounters/EID1","data":{...}},{"type":"set","path":"campaigns/CID/encounters/EID2","data":{...}}]}'
```
4. **Verify:**
```bash
curl -s "$HOST/api/collection?path=campaigns/CID/encounters" | jq '.[] | {name, count: (.participants|length)}'
```

Participants go inline in the encounter doc — there is no `participants` sub-collection. A single batch `set` per encounter writes the whole roster atomically.

## 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`
- No re-sort after start; 1-list order remains source of truth
- Inactive (`isActive:false`) participants are skipped, but stay in slot

### 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)` for living/dying/stable participants; normal heal does not affect dead participants
- Character/NPC at 0 HP → `status:'dying'`, death-save controls, unconscious condition
- Monster at 0 HP → `status:'dead'`, `isActive:false`
- Massive damage (`damage >= currentHp + maxHp`) → dead

### Death saves (character/NPC only, at 0 HP)
Action buttons: Success, Fail, Nat1, Nat20, Stabilize.
- Success: +1 success; 3 successes → stable/unconscious at 0 HP
- Fail: +1 failure; 3 failures → dead
- Nat1: +2 failures
- Nat20: 1 HP, conscious, counters reset
- Stabilize: stable/unconscious at 0 HP, counters reset
- Revive: dead → 0 HP, stable/unconscious, active

### 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 participants hidden (including auto-inactive dead monsters and DM-hidden 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** = slot by initiative into participants[] + sync
- **Toggle active** = flip `isActive` only, stay in slot
- **Remove** = drop from participants[] + sync, advance current if needed

No re-sort after `startEncounter`.

## Storage paths quick reference

Bare canonical (server mode). App code prefixes these with `artifacts/{APP_ID}/public/data/` — adapter strips it.

```
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
```

REST mapping: `campaigns/{cid}` doc → `GET/PUT/PATCH/DELETE /api/doc?path=campaigns/{cid}`. Collection parent (`campaigns`, `campaigns/{cid}/encounters`) → `GET/POST /api/collection?path=...`.

## 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 become inactive automatically and are skipped. Remove via trash icon to clean list.
- Dead characters/NPCs stay active until DM marks inactive, removes, or revives them.
- Player display auto-follows Start Combat. Manual control via Open Player Window.

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