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:

{ 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.