the-sunken-reach/docs/MONSTERS.md

# Monsters

How monsters work in this app: the campaign's monster list, the built-in
bestiary, and how monsters behave in an encounter.

This describes the code as it stands. The built-in list is
`backend/src/game/data/monstersLibrary.js`. Related:
[ENCOUNTERS.md](ENCOUNTERS.md), [NPCS.md](NPCS.md).

## Contents

1. [The basics](#1-the-basics)
2. [What a monster holds](#2-what-a-monster-holds)
3. [Managing monsters](#3-managing-monsters)
4. [The built-in bestiary](#4-the-built-in-bestiary)
5. [Monsters in encounters](#5-monsters-in-encounters)
6. [What players see](#6-what-players-see)
7. [Permissions](#7-permissions)
8. [What is not modelled](#8-what-is-not-modelled)

---

## 1. The basics

- Every campaign has its own **monster list**. Only the DM can see or change
  it.
- A monster in the list is a **template**. Each time it is added to an
  encounter it becomes a separate combatant with its own hit points.
- Stat blocks are the DM's. Players see a monster only as a name and a health
  bar in an encounter.

## 2. What a monster holds

| Field | What it is |
|---|---|
| Name | Up to 80 characters |
| AC | Armor Class |
| Max HP | Hit points each copy starts an encounter with |
| Speed | Walking speed in feet. 30 unless set otherwise. Other speeds (fly, swim, climb) go in Notes |
| Ability scores | STR, DEX, CON, INT, WIS, CHA. 10 unless set otherwise |
| Attack bonus | Added to the monster's attack roll |
| Damage | Dice for its main attack, e.g. `1d6+2`, with the damage type if you like: `1d6+2 necrotic` |
| Named attacks | Optional, up to 8: each a name, an attack bonus, damage dice, a damage type and **how many times it is made each turn** (a multiattack: "Claw ×2, Bite ×1"). With any listed, these are what the monster attacks with in an encounter, in place of the single attack above |
| Challenge rating | A rough danger rating, e.g. `1/4`, `2`. It sets what the monster is worth in XP and how hard an encounter is ([ENCOUNTERS.md](ENCOUNTERS.md), section 9); a monster with none, or with text that is not a rating, is left out of both |
| Special trait | A short note such as "Pack Tactics" |
| Notes | Anything else: what it attacks with, how it behaves |

The challenge rating feeds the XP and difficulty sums. The AC, the attack
bonus and damage (or the named attacks) and the ability scores are used when
an attack or a spell is resolved in an encounter: an attack roll is judged
against the AC, a saving throw adds the ability's modifier, and with
auto-roll on the monster's attacks are aimed and rolled for the DM
([ENCOUNTERS.md](ENCOUNTERS.md), "Attacks and spells"). A monster's ability
modifiers are worked out from its scores for display, for its initiative
bonus (Dexterity) and for the rolls a click makes (section 5).

## 3. Managing monsters

The list is the "Monsters" part of the campaign page (DM only). Each monster
is a short row: its name, challenge rating, AC, HP and attack. The list has a
search box, shows ten to a page, and clicking a row opens the monster's
**pop-out** with its whole stat block.

- **Adding by hand:** "+ Add Monster" opens a pop-out with the whole stat
  block: name,
  challenge rating, AC, HP, speed, attack bonus, damage, the six ability
  scores, special trait and notes. Only name, AC and HP must be typed; speed
  starts at 30, attack bonus at 0 and each ability score at 10.
- Once added by hand, the monster's own pop-out opens. "+ Add another
  monster" at its top goes straight back to an empty form.
- **Adding from the bestiary:** "📚 From Library" opens the bestiary in a
  pop-out, and "+ Add" copies a complete stat block.
  Each monster can be added once: one the campaign already has by that name is
  left out of the list, and comes back if the campaign's monster is renamed or
  deleted.
- **Changing:** "Edit stat block" in a monster's pop-out opens the same form
  filled in.
  Saving changes the template, and copies already in encounters show the new
  stat block straight away; their current HP is left alone.
- The pop-out shows the full stat block: the numbers, the six ability scores,
  the trait and the notes.
- **Removing:** "Remove from campaign" at the foot of the pop-out, after a
  confirmation. Copies
  already in encounters stay there with their name and HP, but lose their
  stat block.

## 4. The built-in bestiary

38 monsters, from harmless to dangerous, every one with a complete stat
block. Each library row shows challenge rating, AC, HP, speed, attack, damage
and the six ability scores, plus its trait and notes, before you add it. Adding copies the monster into your campaign; the copy is yours, and later
changes to the library do not affect it.

The full bestiary, weakest first. "Attack" is the bonus added to the
monster's attack roll.

This list is written from the app's own data by `npm run docs:lists` (in `/backend`). Re-run it after changing the data; do not edit the list by hand.

<!-- BEGIN GENERATED: monster-library -->
| Monster | CR | AC | HP | Speed | Attack | Damage | STR / DEX / CON / INT / WIS / CHA | Trait | Notes |
|---|---|---|---|---|---|---|---|---|---|
| Commoner | 0 | 10 | 4 | 30 | +2 | 1d4 | 10 / 10 / 10 / 10 / 10 / 10 | — | An ordinary villager, armed with a club. |
| Giant Rat | 1/8 | 12 | 7 | 30 | +4 | 1d4+2 | 7 / 15 / 11 / 2 / 10 / 4 | Pack Tactics | Bite, piercing damage. |
| Kobold | 1/8 | 12 | 5 | 30 | +4 | 1d4+2 | 7 / 15 / 9 / 8 / 7 / 8 | Pack Tactics, Sunlight Sensitivity | Dagger, piercing damage. |
| Bandit | 1/8 | 12 | 11 | 30 | +3 | 1d6+1 | 11 / 12 / 12 / 10 / 10 / 10 | — | Scimitar, slashing damage. |
| Cultist | 1/8 | 12 | 9 | 30 | +3 | 1d6+1 | 11 / 12 / 10 / 10 / 11 / 10 | Dark Devotion | Scimitar, slashing damage. |
| Stirge | 1/8 | 12 | 2 | 10 | +5 | 1d4 | 4 / 16 / 11 / 2 / 8 / 6 | Blood Drain | Proboscis; attaches and drains hp on a hit. |
| Goblin | 1/4 | 15 | 7 | 30 | +4 | 1d6+2 | 8 / 14 / 10 / 10 / 8 / 8 | Nimble Escape | Scimitar, slashing damage. |
| Skeleton | 1/4 | 13 | 13 | 30 | +4 | 1d6+2 | 10 / 14 / 15 / 6 / 8 / 5 | Undead — vulnerable to bludgeoning | Shortsword, piercing damage. |
| Zombie | 1/4 | 8 | 22 | 20 | +3 | 1d6+1 | 13 / 6 / 16 / 3 / 6 / 5 | Undead Fortitude | Slam, bludgeoning damage. |
| Wolf | 1/4 | 13 | 11 | 40 | +4 | 2d4+2 | 12 / 15 / 12 / 3 / 12 / 6 | Pack Tactics | Bite; can knock prone on a hit. |
| Giant Wolf Spider | 1/4 | 13 | 11 | 40 | +3 | 1d6+1 | 12 / 16 / 13 / 3 / 12 / 4 | Poison bite | Spider climb; bite deals poison damage. |
| Scout | 1/2 | 13 | 16 | 30 | +4 | 1d6+2 | 11 / 14 / 12 / 11 / 13 / 11 | Keen Hearing and Sight | Shortsword or longbow. |
| Orc | 1/2 | 13 | 15 | 30 | +5 | 1d12+3 | 16 / 12 / 16 / 7 / 11 / 10 | Aggressive | Greataxe, slashing damage. |
| Hobgoblin | 1/2 | 18 | 11 | 30 | +3 | 1d8+1 | 13 / 12 / 12 / 10 / 10 / 9 | Martial Advantage | Longsword, slashing damage. |
| Thug | 1/2 | 11 | 32 | 30 | +4 | 1d6+2 | 15 / 11 / 14 / 10 / 10 / 11 | Pack Tactics | Mace, bludgeoning damage. |
| Gnoll | 1/2 | 15 | 22 | 30 | +3 | 1d8+1 | 14 / 12 / 11 / 6 / 10 / 7 | Rampage | Spear, piercing damage. |
| Lizardfolk | 1/2 | 15 | 22 | 30 | +3 | 1d6+1 | 15 / 10 / 13 / 7 / 12 / 7 | Hold Breath | Club or spear, piercing damage. |
| Black Bear | 1/2 | 11 | 19 | 40 | +3 | 1d6+2 | 15 / 10 / 14 / 2 / 12 / 7 | Keen Smell | Bite and claw attacks. |
| Giant Spider | 1 | 14 | 26 | 30 | +5 | 1d8+3 | 14 / 16 / 12 / 2 / 11 / 4 | Web, poison bite | Bite deals piercing plus poison damage. |
| Ghoul | 1 | 12 | 22 | 30 | +2 | 2d6+2 | 13 / 15 / 10 / 7 / 10 / 6 | Claws paralyze on a hit | Undead. |
| Dire Wolf | 1 | 14 | 37 | 50 | +5 | 2d6+3 | 17 / 15 / 15 / 3 / 12 / 7 | Pack Tactics | Bite; can knock prone on a hit. |
| Brown Bear | 1 | 11 | 34 | 40 | +5 | 1d8+5 | 19 / 10 / 16 / 2 / 13 / 7 | Keen Smell | Multiattack: bite and claws. |
| Harpy | 1 | 11 | 38 | 20 | +4 | 2d4+2 | 12 / 13 / 12 / 7 / 10 / 13 | Luring Song | Flying speed 40 ft; claws deal slashing damage. |
| Ochre Jelly | 2 | 8 | 45 | 10 | +5 | 2d6+3 | 15 / 6 / 14 / 2 / 6 / 1 | Amorphous, splits when damaged by slashing | Pseudopod, bludgeoning plus acid damage. |
| Ogre | 2 | 11 | 59 | 40 | +6 | 2d8+4 | 19 / 8 / 16 / 5 / 7 / 7 | — | Greatclub, bludgeoning damage. |
| Griffon | 2 | 12 | 59 | 30 | +6 | 2d6+4 | 18 / 15 / 16 / 2 / 13 / 8 | Keen Sight | Flying speed 80 ft; multiattack beak and claws. |
| Ankheg | 2 | 14 | 39 | 30 | +6 | 2d6+4 | 17 / 11 / 13 / 1 / 13 / 6 | Burrow speed 10 ft; can spit acid | Bite, piercing plus acid damage. |
| Manticore | 3 | 14 | 68 | 30 | +5 | 1d8+3 | 17 / 16 / 17 / 7 / 12 / 8 | Tail spikes (ranged) | Flying speed 50 ft; multiattack claws or tail spikes. |
| Basilisk | 3 | 15 | 52 | 20 | +5 | 2d6+3 | 16 / 8 / 15 / 2 / 8 / 7 | Petrifying Gaze | Bite, piercing damage. |
| Owlbear | 3 | 13 | 59 | 40 | +7 | 1d10+5 | 20 / 12 / 17 / 3 / 12 / 7 | Keen Sight and Smell | Multiattack: beak and claws. |
| Wight | 3 | 14 | 45 | 30 | +4 | 1d8+2 | 15 / 14 / 16 / 10 / 13 / 15 | Life Drain, Sunlight Sensitivity | Longsword or life-draining touch. |
| Werewolf | 3 | 12 | 58 | 30 | +4 | 1d8+2 | 15 / 13 / 14 / 10 / 11 / 10 | Shapechanger, regeneration | Bite (hybrid/wolf form) or multiattack claws + bite. |
| Doppelganger | 3 | 14 | 52 | 30 | +4 | 2d4+2 | 11 / 18 / 14 / 11 / 12 / 14 | Shapechanger, Ambusher | Multiattack slam. |
| Displacer Beast | 3 | 13 | 85 | 40 | +7 | 2d6+4 | 18 / 15 / 16 / 6 / 12 / 8 | Displacement (attacks vs. it have disadvantage) | Multiattack: two tentacles. |
| Ettin | 4 | 12 | 85 | 40 | +7 | 2d8+4 | 21 / 8 / 17 / 6 / 10 / 8 | Two heads — advantage on Perception, can’t be surprised easily | Multiattack: battleaxe and morningstar. |
| Hill Giant | 5 | 13 | 105 | 40 | +8 | 3d8+5 | 21 / 8 / 19 / 5 / 9 / 6 | — | Greatclub, bludgeoning damage. |
| Troll | 5 | 15 | 84 | 30 | +7 | 2d6+4 | 18 / 13 / 20 / 7 / 9 / 7 | Regeneration (vulnerable to fire/acid) | Multiattack: bite and two claws. |
| Wraith | 5 | 13 | 67 | 0 | +6 | 4d8+4 | 6 / 16 / 16 / 12 / 14 / 15 | Incorporeal, life drain, flying 60 ft | Undead; life drain touch attack. |
<!-- END GENERATED: monster-library -->

## 5. Monsters in encounters

On an encounter page, the DM chooses "Monster" in the "Add to the scene"
panel, picks one, says how many, and types its initiative or leaves it to be
rolled ("🎲 Roll initiative for N monsters and NPCs" rolls a d20 plus the
Dexterity modifier for each that has no roll).

- The same monster can be added **any number of times**, up to 20 in one go.
  Each copy has its own HP and conditions. Copies added together are numbered
  ("Goblin 1" to "Goblin 4"); one added on its own has the monster's name. The
  screen has no way to rename one (the API allows it).
- A copy starts at the monster's max HP. Its HP stays between 0 and its max.
- At 0 HP a copy is marked **Down** and dimmed, but keeps its place in the
  initiative order until the DM removes it.
- HP belongs to the encounter: a monster starts fresh in the next one.

The DM's card for a monster shows AC, speed, attack bonus and damage at a
glance, and under "details" its six ability scores with modifiers, its trait
and its notes. **Attack, Damage and each ability score roll when clicked**: a
d20 plus the attack bonus, the damage dice, or a d20 plus the ability's
modifier. Of damage written with more after the dice ("2d8+3 fire") the dice
are rolled; damage that does not start with dice is shown but does not roll.

## 6. What players see

| Players see | Players never see |
|---|---|
| The monster's name | AC, speed, attack bonus, damage |
| Its health bar and current/max HP | Ability scores, challenge rating |
| Its conditions | Trait and notes |
| Its place in the initiative order | The campaign's monster list |

This is enforced by the server: stat blocks are never sent to a player's
browser.

Players see a monster's exact HP numbers unless the campaign setting "Players
see the exact hit points of monsters and NPCs in encounters" is unticked.
Then they get the health bar only.

## 7. Permissions

| Action | DM | Players |
|---|---|---|
| See the monster list and stat blocks | Yes | No |
| Browse the built-in bestiary | Yes | Yes (it is standard reference material) |
| Add or remove monsters | Yes | No |
| Add a monster to an encounter | Yes | No |
| Change a monster's HP, initiative or conditions | Yes | No |
| See a monster in an encounter | Everything | Name, HP, conditions |

## 8. What is not modelled

- Spells, legendary actions and resistances (use Notes; in an encounter the
  DM can spell out any attack or save on the spot)
- Trade: monsters do not sell things or change money (NPCs do)
- Saving throw proficiencies and skills (on an encounter card a click on an
  ability score rolls a d20 with its modifier, for a check or a save)
- XP typed in for a monster: it always comes from the challenge rating
- Monster hit dice, and rolling HP rather than using the fixed value