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 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	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 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)	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.
• 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 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.

• 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: 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.

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
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
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
• Renaming an encounter from the screen
• A log of what happened during the encounter