the-sunken-reach/docs/ENCOUNTERS.md

# Encounters

How encounters work in this app: the two kinds of scene, who can be in one,
how a battle is run, and how rewards are handed out.

This describes the code as it stands. The rules live in
`backend/src/routes/encounters.routes.js`. Related:
[CHARACTERS.md](CHARACTERS.md), [MONSTERS.md](MONSTERS.md),
[NPCS.md](NPCS.md), [WEAPONS.md](WEAPONS.md), [ITEMS.md](ITEMS.md).

## Contents

1. [The basics](#1-the-basics)
2. [Battle or quest](#2-battle-or-quest)
3. [Status](#3-status)
4. [The scene and DM notes](#4-the-scene-and-dm-notes)
5. [Who is in the scene](#5-who-is-in-the-scene)
6. [Hit points](#6-hit-points)
7. [Initiative, turns and rounds](#7-initiative-turns-and-rounds)
8. [Conditions](#8-conditions)
9. [Rewards](#9-rewards)
10. [What each side sees](#10-what-each-side-sees)
11. [Permissions](#11-permissions)
12. [What is not modelled](#12-what-is-not-modelled)

---

## 1. The basics

- An encounter is one **scene** the DM runs: a fight, or a meeting with
  people who want something.
- Encounters belong to a campaign and are listed on the campaign page. The DM
  creates them and sees all of them.
- A player only sees an encounter that **one of their own characters is in**.
  Until the DM adds their character it is not in their list and its page will
  not open, so scenes the DM is still preparing stay hidden, name included.
  Taking their character out hides it again.
- The encounter page updates live for everyone who has it open.
- The DM runs everything. Players watch, and see less than the DM does.

## 2. Battle or quest

Every encounter has a mode, chosen when it is created and switchable at any
time from the top of the page.

| | Battle | NPC quest |
|---|---|---|
| For | A fight | A scene built around people and an objective |
| Layout | Everyone in one list, in initiative order | Three groups: "People you meet", "The party", "Creatures" |
| Rounds and turns | Yes | No |
| Initiative | The d20 roll, typed in per combatant; the bonus is added | The same; each group lists highest first |
| Start button | Begin Battle | Begin Quest |
| End button | End Battle | Complete Quest |

Everything else (hit points, conditions, rewards, the scene description, DM
notes) works the same in both.

## 3. Status

| Status | Meaning | How to get there |
|---|---|---|
| Planning | Being set up | Every new encounter starts here |
| In progress | Being played | Begin Battle / Begin Quest, or Reopen |
| Complete | Finished | End Battle / Complete Quest |

Status is a label. Nothing is locked when an encounter is complete: the DM
can still change HP, add people and award rewards. Encounters cannot be
renamed from the screen.

### Location

The DM can give an encounter a location from the campaign's list, with the
picker at the top of the page. While the encounter is **in progress** its
characters are at that location: beginning it, changing its location, or
adding a character to it moves them there. Each place a character is moved to
(this way or by the DM on the sheet) is remembered, and a player can see only
the locations one of their own characters has been to — on the campaign page
under "Places You've Been", and on the encounter itself. Archiving or deleting
the encounter does not take a visited place away again.

### Order, archive and delete

**Order.** The campaign page lists encounters in the **campaign order**, which
the DM arranges with the ▲ and ▼ buttons and everyone sees. A new encounter
goes to the top. The "Sort by" menu re-sorts the list by name, status, type or
date instead; that choice is remembered per browser and changes nothing for
anyone else. ▲ and ▼ only show while sorting by campaign order.

**Archive.** "Archive" (on the list or the encounter page) puts an encounter
away without changing it. It moves to the DM's "Archived" section and
disappears from the players' list; a player whose character is in it can still
open its page from a bookmark. "Restore" puts it back on the list.

**Delete.** "Delete" (on the encounter page, or on an archived encounter in
the list) removes the scene, who was in it and its reward list, after a
confirmation. There is no undo. Rewards already handed out stay with the
characters, and characters keep their current HP.

## 4. The scene and DM notes

| Box | For | Who sees it |
|---|---|---|
| The Scene / Quest | Describing the battlefield, or what is being asked of the party | Everyone |
| DM Notes | Tactics, secrets, what happens if the party fails | **DM only** |

Both save when the DM clicks out of the box.

## 5. Who is in the scene

The DM adds people from the "Add to the scene" panel.

| Kind | Comes from | Can be added more than once |
|---|---|---|
| Character | The campaign's finished characters | No |
| Monster | The campaign's monster list ([MONSTERS.md](MONSTERS.md)) | Yes |
| NPC | The campaign's NPC list ([NPCS.md](NPCS.md)) | No |

Each has a card. The card's left edge is coloured by kind, and it shows:

- **Characters:** level, species and class; HP, AC, speed, initiative bonus,
  passive perception, proficiency bonus and spell save DC. Under "details":
  ability scores, saves, the weapons and spells the character can use (with
  attack and damage numbers), and special abilities. The name links to the
  character sheet.
- **Monsters:** for the DM, AC, speed, attack and damage, and under "details"
  ability scores, trait and notes.
- **NPCs:** role, attitude and description; for the DM also AC, attack,
  damage and DM notes.

Details start open for the DM and closed for players. Weapons and spells
above a character's level are left out, because the character cannot use
them.

The DM removes someone with "Remove" on their card. Removing whoever is on
turn passes the turn to the next combatant.

## 6. Hit points

The DM types an amount and clicks Damage or Heal on a card.

| Combatant | Where the HP lives |
|---|---|
| Character | On the **character sheet**. The encounter shows the sheet's HP and changes it directly, so the two always agree. Max HP comes from the sheet. |
| Monster | In the encounter, per copy. Starts at the monster's max. |
| NPC | In the encounter. An NPC with no HP set has no health bar. |

- HP always stays between 0 and max.
- **What players see of it.** A character's HP is always shown in numbers. For
  monsters and NPCs it depends on the campaign setting "Players see the exact
  hit points of monsters and NPCs": on (the default) shows the numbers, off
  shows only the health bar. The DM always sees the numbers.
- At 0 HP a monster or NPC is marked **Down** and dimmed. It keeps its place
  in the order; nothing is removed automatically.
- A **character** at 0 HP is **Dying** instead, and its card grows a death-save
  box: see below.
- A character's temporary HP is shown beside its HP but is not used up
  automatically.

### A character at 0 HP

The full rules are in [CHARACTERS.md](CHARACTERS.md), section 7; the box on
the card is the same one as on the sheet, and both change the same character.

- **Dying.** The box shows two tallies, Saved and Failed, three pips each.
  Type what the d20 showed and click **Death save**: 10 or more is a success,
  less is a failure, a 1 is two failures, a 20 puts the character back up at
  1 HP. The DM can do this for anyone; a player for their own character.
- **Damage while down** is one failed save, added when the DM clicks Damage.
  For a critical hit the DM clicks the next Failed pip to add the second.
- **Stabilise** stops the saves without a roll (a Medicine check, a spell).
  Three successes do the same. A stable character stays at 0 HP.
- **Heal** on a dying or stable character puts them back up and clears the
  tallies.
- **Dead** after three failures, or when one blow leaves as much as the
  character's max HP still to take after reaching 0. Healing is refused; the
  DM clicks **Revive at 1 HP**.
- The DM can click any pip to set a tally by hand.

Nothing rolls or advances by itself: the app does not prompt for a save when
the turn comes round, and a dying, stable or dead character keeps its place
in the order.

## 7. Initiative, turns and rounds

Initiative is entered in battles and quests alike. Turns and rounds are for
battles only.

- Each combatant has an **initiative roll** field. Type what the d20 showed,
  1 to 20; the field accepts nothing else. The app does not roll the die, but
  it adds the bonus for you and shows the total, which can go past 20 (a 20 on
  the die with a +3 bonus is 23): a character's initiative
  bonus from their sheet, a monster's Dexterity modifier, nothing for an NPC.
- The DM can enter the roll for anyone, when adding them or on the card. A
  player can enter the roll for **their own character** on its card.
- The list is ordered by the total, highest first; ties keep the order they
  were added in. Anyone who has not rolled yet waits at the bottom.
- The bonus is worked out when the roll is entered. If a character's sheet
  changes afterwards, enter the roll again to pick up the new bonus.
- **Begin Battle** puts the first combatant on turn. Their card is
  highlighted and the header names them.
- **Next Turn** passes the turn to the next in the order. After the last
  combatant it returns to the top and the **round** goes up by one.
- **Next Round** skips straight to the top of the next round.

### Targets

Combatants can be marked as **targets**: whoever is being attacked (or
healed) right now. One target is an ordinary attack; more than one is an
**area attack**.

- Click **🎯 Target** beside a combatant's name to mark them; click it again
  to unmark. Each one marked is added to the targets.
- The **DM** can mark anyone at any time, in a battle or a quest. A **player**
  can while their own character is on turn in a battle, so they can show the
  DM who they are going for.
- A target's card is outlined in red for everyone and reads "Targeted by
  <whoever is on turn>".
- While anyone is marked the DM gets an **attack bar** above the list, which
  stays in view while scrolling. It shows who is attacking whom, each target's
  AC and HP, and the attacker's attacks: a character's equipped weapons (all
  of them if none are equipped) and damaging spells, or a monster's or NPC's
  attack and damage. The amount box is ready to type in; **Damage** (or
  Enter) and **Heal** change HP exactly as the buttons on a card do.
- Targets stay marked after damage, for a second attack. They are cleared
  when the turn or round moves on, when the encounter begins, ends or is
  reopened; a target that is removed from the encounter is unmarked.

**Area attacks**

An attack on several targets is harder to land and its damage is shared.

- **Harder to hit.** Every target's AC counts as **2 higher for each target
  beyond the first**:

  | Targets | Added to each AC |
  |---|---|
  | 1 | 0 |
  | 2 | +2 |
  | 3 | +4 |
  | 4 | +6 |

  The attack bar shows the AC to beat with the penalty already added
  ("17 (15 +2)"), and each target's card says "area attack, AC +2".
- **Who was hit.** Each target has a tick box, ticked to begin with. Untick
  anyone the roll missed; they take nothing.
- **Sharing the amount.** Type the total. "Split between those hit" (the
  default) shares it evenly, any remainder going one point each to the first
  targets marked: 7 between three is 3, 2 and 2. "Full amount to each" gives
  every target hit the whole amount. Each target's share is shown before it
  is applied.
- A target with no hit points to track is left out of the sharing.

The app does not roll the attack or decide whether it hits: the DM compares
the roll with the AC shown and types the damage. The +2 is fixed in the code
(`AREA_AC_STEP` in `frontend/src/pages/EncounterPage.tsx`).

## 8. Conditions

The DM adds a condition to any card from the "+ Condition" list, and removes
one by clicking its ✕. Everyone sees them.

The list: Blinded, Charmed, Deafened, Frightened, Grappled, Incapacitated,
Invisible, Paralyzed, Petrified, Poisoned, Prone, Restrained, Stunned,
Unconscious, Concentrating.

Conditions are labels to remind the table. They do not change any numbers,
and they do not expire on their own.

## 9. Rewards

The DM lines up loot in the Rewards panel, on any encounter at any time.

| Reward | What the DM sets |
|---|---|
| Gold | An amount |
| Weapon | A weapon from the pool, a level (not below its starting level), a quantity |
| Item | An item from the pool, a level, a quantity |

Each can carry a short note ("Goblin chief's purse").

**A reward does nothing until it is awarded**, and it can be awarded once.

| Button | What happens |
|---|---|
| Award (pick a character) | The whole reward goes to that character. It can be any finished character in the campaign, not only those in the encounter. |
| Split (gold only) | Shared evenly between the characters in the encounter. Any remainder goes one gold each, highest initiative first: 101 gold between two is 51 and 50. |

- **Gold** is added to the character's balance with a money-log entry reading
  "Reward: <encounter name>".
- A **weapon or item** is added to what the character holds, at the reward's
  level, stacking with any they already have. If the character is below that
  level they hold it but cannot use it yet.
- Removing a reward from the list does **not** take back what was awarded.
- Spells cannot be rewards; the DM grants those on the character sheet.

Until a reward is awarded only the DM can see it. Afterwards players see what
it was and who received it.

## 10. What each side sees

| | DM | Players |
|---|---|---|
| Scene description | Yes | Yes |
| DM notes | Yes | Never |
| Characters | Full card | Full card |
| Monsters | Full stat block | Name, HP, conditions |
| NPCs | Everything | Name, role, attitude, description, HP bar |
| Rewards | All | Only awarded ones |
| Controls (add, damage, turns, rewards) | Yes | None |

The server only sends a player what the right-hand column lists, so hidden
information cannot be dug out of the page.

## 11. Permissions

| Action | DM | Players |
|---|---|---|
| Create an encounter | Yes | No |
| See and open an encounter | Yes, all of them | Only ones their own character is in |
| Change mode, status, scene or DM notes | Yes | No |
| Rearrange, archive, restore or delete encounters | Yes | No |
| See archived encounters in the list | Yes | No |
| Add or remove anyone | Yes | No |
| Change HP or conditions | Yes | No |
| Enter an initiative roll | Yes, for anyone | For their own character only |
| Mark targets | Yes, any time | On their own character's turn |
| Enter a death save, or stabilise | Yes, for anyone | For their own character only |
| Set death-save tallies by hand, revive the dead | Yes | No |
| Advance turns and rounds | Yes | No |
| Add, remove or award rewards | Yes | No |

People outside the campaign cannot open its encounters.

## 12. What is not modelled

- Rolling initiative, attacks, damage or saves (use the dice roller, bottom
  left of every page)
- Applying an attack's damage automatically
- Death saves for monsters and NPCs, and prompting for a save on a dying
  character's turn
- Conditions with durations or mechanical effects
- Maps, positions, distances and areas of effect
- Experience points and encounter difficulty
- Spells as rewards
- Renaming an encounter from the screen
- A log of what happened during the encounter