60 lines
3.6 KiB
Markdown
60 lines
3.6 KiB
Markdown
|
# Glossary — TTRPG Initiative Tracker
|
||
|
|
|
||
|
|
Domain terms used throughout the app, shared turn logic, tests, and docs. Keep
|
||
|
|
these definitions stable so logs, UI labels, and code agree.
|
||
|
|
|
||
|
|
## Combat structure
|
||
|
|
|
||
|
|
| Term | Meaning |
|
||
|
|
|------|---------|
|
||
|
|
| **Initiative** | The ordered sequence determining who acts next. Rolled once at the start of an encounter; re-rolled only on a new encounter or explicit DM re-roll. |
|
||
|
|
| **Round** | One full pass through initiative — every active participant gets exactly one turn. N participants (PCs + NPCs + monsters + features) = N turns per round. Round counter increments when initiative wraps back to the first participant. |
|
||
|
|
| **Turn** | A single participant's initiative slot within a round. One participant acts. As many turns per round as there are participants. |
|
||
|
|
| **Initiative slot** | Synonym for turn's position in the ordered list. |
|
||
|
|
| **Top of round** | The first turn of a round (round counter increments here). |
|
||
|
|
|
||
|
|
Example: encounter with 8 participants (3 PCs + 4 monsters + 1 NPC).
|
||
|
|
|
||
|
|
```
|
||
|
|
Round 1: turn 1 (Fighter) → turn 2 (Goblin1) → ... → turn 8 (Merchant)
|
||
|
|
Round 2: turn 1 (Fighter) → ... → turn 8 (Merchant) [round counter +=1 at top]
|
||
|
|
```
|
||
|
|
|
||
|
|
## Participants
|
||
|
|
|
||
|
|
| Term | Meaning |
|
||
|
|
|------|---------|
|
||
|
|
| **Participant** | Any combatant tracked in initiative. Has HP, initiative roll, conditions, and an `isActive` flag. |
|
||
|
|
| **PC** (Player Character) | Controlled by a player. On death → death saves (not removed from initiative). |
|
||
|
|
| **NPC** (Non-Player Character) | DM-controlled ally/neutral (e.g. merchant, quest-giver). May or may not roll initiative. |
|
||
|
|
| **Monster** | Hostile DM-controlled combatant. On death → typically removed from active initiative or marked dead. |
|
||
|
|
| **Feature / Lair** | Environmental or legendary effect that occupies an initiative slot (e.g. lair action at initiative 20). |
|
||
|
|
|
||
|
|
## Participant state
|
||
|
|
|
||
|
|
| Term | Meaning |
|
||
|
|
|------|---------|
|
||
|
|
| **HP** (Hit Points) | Current health. `currentHp` / `maxHp`. At 0 → dying or dead (rules differ by type). |
|
||
|
|
| **Initiative mod** | Bonus added to d20 initiative roll. `defaultInitMod`. |
|
||
|
|
| **Conditions** | Temporary status effects (stunned, prone, poisoned, etc.) applied/toggled during play. Array on participant. |
|
||
|
|
| **isActive** | Whether the participant is in the active initiative rotation. Set false on death (CURRENT behavior — see M4 skip-bug fix). |
|
||
|
|
| **Death save** | PC-only mechanic. Successes/failures tracked at 0 HP. 3 fails → dead; 3 successes → stable. |
|
||
|
|
|
||
|
|
## Views
|
||
|
|
|
||
|
|
| Term | Meaning |
|
||
|
|
|------|---------|
|
||
|
|
| **Admin view** (`/`) | DM interface. Full create/edit/combat control. |
|
||
|
|
| **Player view** (`/display` or `?playerView=true`) | Read-only second-screen display for players. Shows current turn, HP bars, conditions, round. No DM controls. |
|
||
|
|
| **Active display** | The single `activeDisplay/status` doc controlling what the player view shows (which campaign/encounter, hide-player-HP flag). |
|
||
|
|
|
||
|
|
## Backend / storage
|
||
|
|
|
||
|
|
| Term | Meaning |
|
||
|
|
|------|---------|
|
||
|
|
| **Adapter** | `src/storage/{firebase,ws,memory}.js`. Contract boundary between App and backend. App only calls `storage.*`, never raw SDK/fetch. |
|
||
|
|
| **Path normalization** (`norm()`) | Strip firebase prefix (`artifacts/{APP_ID}/public/data/`) → bare canonical path (`campaigns/X`). Runs inside every adapter method. |
|
||
|
|
| **Generic KV doc store** | Backend stores opaque JSON at arbitrary path strings. No shape-specific endpoints. Backend = firebase mirror, not REST API for app entities. |
|
||
|
|
| **Layer 1 test** | App vs firebase mock. Proves adapter call shape. |
|
||
|
|
| **Layer 2 test** | ws adapter vs live backend. Proves translation + path identity. |
|