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. What each side sees
11. Permissions
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; every member can open them.
• 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	Typed in per combatant	Not shown
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 deleted or renamed from the screen.

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)	Yes
NPC	The campaign's NPC list (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.
• At 0 HP a combatant is marked Down and dimmed. It keeps its place in the order; nothing is removed automatically.
• A character's temporary HP is shown beside its HP but is not used up automatically.

7. Initiative, turns and rounds

Battles only.

• The DM types each combatant's initiative when adding them, and can change it on the card. The app does not roll it. The list is ordered highest first; ties keep the order they were added in.
• 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.

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: ".
• 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
Open an encounter	Yes	Yes
Change mode, status, scene or DM notes	Yes	No
Add or remove anyone	Yes	No
Change HP, initiative or conditions	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 and stabilising
• Conditions with durations or mechanical effects
• Maps, positions, distances and areas of effect
• Experience points and encounter difficulty
• Spells as rewards
• Deleting or renaming an encounter from the screen
• A log of what happened during the encounter