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, MONSTERS.md, NPCS.md, WEAPONS.md, ITEMS.md.

Contents

1. The basics
2. Battle or quest
3. Status
4. The scene and DM notes
5. Who is in the scene
6. Hit points
7. Initiative, turns and rounds
8. Conditions
9. Rewards
10. Trade
11. What each side sees
12. Permissions
13. 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; once in progress, those who have had their turn move to "Next Round" at the bottom	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
Trade (section 10)	No	Yes, while in progress

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.

The list shows ten encounters a page, with Prev and Next beneath it, and the DM's archived list is paged the same way. The order runs on across pages: moving the last encounter on a page down carries it to the top of the next.

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, except dead ones	No
Monster	The campaign's monster list (MONSTERS.md)	Yes
NPC	The campaign's NPC list (NPCS.md)	No

Finding your own character. A player's own characters stand out: their cards have a blue border and background and say "★ Your character", and a row of buttons at the top of the page names each one with its HP ("★ Aria · 12/12 HP", plus "your turn" when it is) and scrolls to its card. The DM sees the same for any character of their own.

Inventory. A character's card has an "🎒 Inventory" button for the DM and for that character's own player. It opens the character panel on that character: everything they hold, what is equipped and what each thing does (CHARACTERS.md, section 14). The floating 🧙 button opens the same panel from anywhere. A card's details also list what the character's equipped gear is doing; the AC, speed and other numbers on the card already include it.

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 weapon and items the character has equipped (with attack and damage numbers), the spells they can cast, and special abilities. A weapon that is not equipped is not on the card and cannot be used; "No weapon equipped" shows when there is none. Equipping is changed from "🎒 Inventory", at any point in the scene. 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.

A dead character cannot be added to any encounter: they are left out of the list to pick from and the server refuses them, until they are revived. A character who dies stays in the encounters they were already in.

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 out of the fight: see "The fallen" below.
• 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, 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, or an ally revives them (below).
• The DM can click any pip to set a tally by hand.

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

The fallen

A combatant is out of the fight when it is:

• a monster or NPC at 0 HP (one with hit points to track), or
• a dead character. Dying and stable characters are not: they stay in view.

What that does:

• Players no longer see it. Its card is gone from their screen, along with any target mark on it; the server does not send it to them at all.
• The DM's screen leaves it out as well, until the DM ticks Show dead above the list (the box shows how many there are, and only appears when there are any). Ticked, they are listed in a group of their own at the bottom, "Out of the fight, hidden from players", each with a "Hidden from players" badge, and everything on the card still works. The tick is not remembered: it is off again when the page is reopened.
• It has no turn. Next Turn, Next Round and Begin Battle pass over it.
• It stays in the encounter: nothing is removed, and gold is still split with a dead character.

It is worked out from hit points each time, not stored, so it undoes itself: heal a monster or NPC above 0, or revive a character, and they are back on everyone's screen and back in the turn order.

Reviving a dead character. Players see dead characters by name only, in a ☠ Fallen box above the list. There are two ways back:

• The DM ticks Show dead and clicks Revive at 1 HP on the dead character's card (or does it on the sheet), at any time.
• An ally tries it: in a battle in progress, the player whose character is on turn gets a Try revive button beside each name in the Fallen box, if that character is capable. Capable means on their feet (above 0 HP) and knowing a spell that is ticked Revives in the campaign's spell list (SPELLS.md), at a level they can cast. The library's Revivify (level 3) and Raise Dead (level 5) are ticked already.

Either way the character comes back at 1 HP with the death saves cleared. The app does not use up the spell, check how long ago they died, or end the reviver's turn.

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.
• Anyone out of the fight (section 6, "The fallen") is passed over.
• The list follows the turn. While a battle is in progress, whoever is on turn is at the top of "Initiative order" with those still to act this round beneath them. Each combatant whose turn has passed moves down to a Next Round section at the bottom, still in initiative order. When the round rolls over everyone is back in "Initiative order". Everyone sees the same arrangement. Before the battle begins, and once it is complete, it is one plain list.

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 player cannot mark someone who is out of the fight, and is not shown a mark the DM leaves on one.
• The combatant on turn cannot be marked: nobody targets themselves, and their card has no Target button until the turn passes. To heal or hurt them on their own turn, use the buttons on their card.
• A target's card is outlined in red for everyone and reads "Targeted by ".
• 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 (none, if nothing is 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 higher for each target beyond the first, by the campaign's area attack AC penalty. The DM sets it in the campaign settings, from 0 (no penalty) to 10; it starts at 2, which gives:

  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.

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
Coins or cash	An amount, and which: gold, silver, copper or cash ($)
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 (coins and cash only)	Shared evenly between the characters in the encounter. Any remainder goes one each, highest initiative first: 101 gold between two is 51 and 50.

• Coins or cash are added to the character's balance with a money-log entry reading "Reward: ".
• 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. Trade

In an NPC quest the party can change money and buy things. Both take someone to deal with and the time to do it, so:

• Trading is open only in an NPC quest that is in progress. Before "Begin Quest" and after "Complete Quest" everything on offer is still shown, but the buttons are off.
• There is no trading in a battle. Switching a quest to a battle hides the Trade card and the server refuses any trade; switching back brings it back.
• An NPC trades only while they are in the scene and not at 0 HP.
• The character trading has to be in the encounter and alive.

The "Trade" card sits beside the scene, above Rewards. It appears for players when there is something to trade, and always for the DM in a quest.

Part of the card	What it does
Who is trading	Picks the character. A player chooses among their own characters in the scene; the DM among all of them. Their purse is shown beside it
💱 A money changer	One row per NPC in the scene who has an exchange rate. Type an amount, choose "gold into cash" or "cash into gold", and the button shows what comes back
🛒 " sells"	Everything that NPC has for sale: what it is, its level and dice, the price, and how many are left. "Buy" buys one
🛒 "For sale here"	Things sold by the scene itself rather than by anyone in it
Set up (DM only)	Puts weapons and items from the campaign pools up for sale at this encounter, and edits their price and stock

• Changing money uses the NPC's own rate, the same both ways, and only gold and cash: no silver, no copper, no change. The amount handed over has to be a whole multiple of that side of the rate. The full rules and examples are in NPCS.md, section 5.
• Buying pays the price from the character's purse (coins make change; a cash price takes cash only), adds the weapon or item to what the character holds at the level it is sold at, and uses up stock. A character below that level holds it but cannot use it yet.
• Every trade is written to the character's money log.
• An NPC's rate and wares are set on the campaign page, under "Trade" on the NPC's row, and follow the NPC into every quest they are in. An encounter's own wares are set here, in the DM's part of the card, and exist only in this encounter: a market stall, a vending machine, a chest with a price tag.
• Removing an NPC from the scene takes their rate and wares out of it. Deleting the encounter deletes its own wares; what was bought stays bought.

11. What each side sees

	DM	Players
Scene description	Yes	Yes
DM notes	Yes	Never
Characters	Full card	Full card
A character's inventory, spells and purse	Yes, for everyone	Their own characters only
Monsters	Full stat block	Name, HP, conditions
NPCs	Everything	Name, role, attitude, description, HP bar
Monsters and NPCs at 0 HP	With "Show dead" ticked, marked hidden	Nothing
Dead characters	Full card with "Show dead" ticked, marked hidden	The name only, in the Fallen box
Rewards	All	Only awarded ones
Exchange rates and things for sale	Yes	Yes, for NPCs they can see and for the scene itself
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.

12. 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	Yes	No
Revive a dead character outright	Yes	No
Try to revive a dead character	Yes, for the character on turn	On their own character's turn, if it has a reviving spell
Advance turns and rounds	Yes	No
Add, remove or award rewards	Yes	No
Set exchange rates, and put things up for sale	Yes	No
Change money or buy, in a quest in progress	Yes, for any character in it	For their own character in it

People outside the campaign cannot open its encounters.

13. What is not modelled

• Rolling initiative, attacks, damage or saves (use the dice roller, bottom left of every page, or in the bottom bar on a phone)
• Applying an attack's damage automatically
• Death saves for monsters and NPCs, and prompting for a save on a dying character's turn
• A roll, a spell slot or a time limit for reviving the dead
• Conditions with durations or mechanical effects
• Maps, positions, distances and areas of effect
• Experience points and encounter difficulty
• Spells as rewards, and spells for sale
• Selling to an NPC, haggling, and buying more than one of a thing in a single step
• Renaming an encounter from the screen
• A log of what happened during the encounter