the-sunken-reach/docs/NPCS.md

# NPCs

How non-player characters work in this app: what the DM records about them,
how they are brought into a scene, what they sell and the rate they change
money at, and what players can and cannot see.

This describes the code as it stands. Related: [ENCOUNTERS.md](ENCOUNTERS.md),
[MONSTERS.md](MONSTERS.md).

## Contents

1. [The basics](#1-the-basics)
2. [What an NPC holds](#2-what-an-npc-holds)
3. [Managing NPCs](#3-managing-npcs)
4. [NPCs in encounters](#4-npcs-in-encounters)
5. [Trade: changing money and selling](#5-trade-changing-money-and-selling)
6. [What players see](#6-what-players-see)
7. [NPC or monster?](#7-npc-or-monster)
8. [Permissions](#8-permissions)
9. [What is not modelled](#9-what-is-not-modelled)

---

## 1. The basics

- An NPC is a person the DM plays: an innkeeper, a quest-giver, a rival, a
  villain.
- Every campaign has its own **NPC list**. Only the DM can see or change it.
- An NPC does nothing by sitting in the list. Players meet one when the DM
  **adds it to an encounter**.
- NPCs are mainly for talking to. Combat stats are optional.
- An NPC can also **trade**: change gold and cash at a rate of their own, and
  sell weapons and items (section 5).

## 2. What an NPC holds

| Field | What it is | Who sees it |
|---|---|---|
| Name | Up to 80 characters | Everyone, once in an encounter |
| Role | A few words: "Innkeeper", "Captain of the Watch" | Everyone |
| Attitude | Friendly, Neutral or Hostile toward the party | Everyone |
| Description | What the party can see and knows | Everyone |
| DM notes | Secrets, motives, what they are hiding | **DM only** |
| AC | Optional | DM only |
| HP | Optional. Without it the NPC has no health bar | See section 6 |
| Attack bonus | Optional | DM only |
| Damage | Optional dice, e.g. `1d6` | DM only |
| Exchange rate | Optional: so much gold for so much cash (section 5) | Everyone, in an encounter |
| Wares | Optional: weapons and items for sale, each with a price (section 5) | Everyone, in an encounter |

A new NPC is Neutral unless you choose otherwise.

**Found at.** An NPC can be given one of the campaign's locations as the place
they are usually found, on their pop-out. In a **free-roam** encounter that
includes that place, the NPC appears on its card, and a character who goes
there can buy from them and change money with them
([ENCOUNTERS.md](ENCOUNTERS.md), section 2, "Free roam"). It changes nothing in
a quest or a battle, where an NPC takes part because the DM added them.

## 3. Managing NPCs

The NPC list is the "NPCs" part of the campaign page (DM only). Each NPC is a
short row: name, role, the start of their description, and badges for their
attitude, a 💱 with their exchange rate and a 🛒 with how many things they
have for sale. The list has a search box and shows ten to a page.

- **The pop-out:** clicking a row opens the NPC's pop-out, with everything
  above: description, DM notes, combat stats, and their trade.
- **Adding:** "+ Add NPC" opens a pop-out with every field above except the
  exchange rate and wares. Only the name is required. Once added, the NPC's
  own pop-out opens, to set their trade; "+ Add another NPC" at its top goes
  straight back to an empty form.
- **Trade:** the exchange rate and the wares are set in the NPC's pop-out,
  under "Changes money" and "For sale" (section 5).
- **Changing:** there is no edit form for the other fields. To change them,
  remove the NPC and add it again (the API accepts changes, but no screen
  offers them). Removing an NPC removes their wares too.
- **Removing:** "Remove from campaign" at the foot of the pop-out, after a
  confirmation. This also **removes the NPC from every encounter** it was in.

## 4. NPCs in encounters

On an encounter page, the DM chooses "NPC" in the "Add to the scene" panel
and picks one. Each NPC can be in an encounter once.

- In an **NPC quest** encounter, NPCs are listed first under "People you
  meet", ahead of the party and any creatures.
- In a **battle**, an NPC takes its place in the initiative order like anyone
  else, using the initiative the DM types in.
- An NPC with HP gets a health bar, and the DM can damage and heal it. This
  HP belongs to the encounter: the same NPC starts at full HP in the next one.
- An NPC with no HP has no health bar and cannot be marked Down.
- Conditions (Prone, Charmed…) can be put on an NPC like any combatant.

An NPC's card shows its attitude as a coloured badge, its role under its
name, and its description in full. The DM's card also shows AC, attack,
damage and the DM notes.

## 5. Trade: changing money and selling

Only the DM sets trade up. Players see it and use it on the encounter page,
in the "Trade" card. The rules for when trading is open are in
[ENCOUNTERS.md](ENCOUNTERS.md), section 10: in short, in an **NPC quest that
is in progress**, never in a battle, and only with an NPC who is in the scene
and not at 0 HP.

### Changing money

An NPC with an **exchange rate** changes gold into cash ($) and cash into
gold. The rate is two whole numbers, "this much gold = this much cash", and
each NPC has their own, so one money changer can be a better deal than
another.

| Rate | Hand over | Get |
|---|---|---|
| 1 gold = $5 | 3 gold | $15 |
| 1 gold = $5 | $20 | 4 gold |
| 2 gold = $15 | 6 gold | $45 |
| 2 gold = $15 | $30 | 4 gold |

- The same rate is used both ways.
- **Only gold and cash.** Silver and copper are not taken, a gold coin is not
  broken to make up an amount, and no change is given.
- What is handed over has to be a whole multiple of that side of the rate: at
  2 gold = $15, gold goes in twos and cash in fifteens.
- Both sides go on the character's money log, naming the NPC: "Changed with
  Vex for $45" and "Changed with Vex from 6 gold".
- An NPC never runs out of gold or cash to change.
- To set a rate, type both numbers under "Changes money" in the NPC's pop-out
  and press "Save rate".
  "Stop changing money" clears it. An NPC with no rate does not change money.

### Selling

An NPC's **wares** are weapons and items from the campaign's own pools, each
put up for sale with:

| Field | What it is |
|---|---|
| What | One weapon or item from the pool |
| Level | The gear level it is handed over at, not below its starting level |
| Price | For one, in gold, silver, copper or cash |
| Stock | How many can be bought. Empty means no limit |

- Wares belong to the NPC, not to an encounter: they are on offer in every
  quest that NPC is in.
- Buying pays the price from the character's purse, adds the weapon or item
  to what they hold (stacking with any they already have) and lowers the
  stock. A price in coins is paid with change, exactly like any other spend;
  a price in cash takes cash only.
- At 0 stock a ware shows as sold out and cannot be bought. It stays listed
  until the DM removes it.
- The ✕ beside a ware stops it being sold. Things already bought stay bought.
- "Edit" beside a ware changes its price, the coin (or cash) the price is in,
  and its stock: restock a sold-out ware, or clear the stock for no limit.
  What is sold, its level and who sells it cannot be changed; remove the ware
  and put it up again for that.
- Removing a weapon or item from the campaign pool removes it from sale
  everywhere.

A stall or a machine with nobody behind it can sell things too: those wares
belong to an encounter rather than an NPC, and are set up on the encounter
page. See [ENCOUNTERS.md](ENCOUNTERS.md), section 10.

## 6. What players see

Players only ever see an NPC through an encounter it is in:

| Players see | Players never see |
|---|---|
| Name, role, attitude, description | DM notes |
| Health bar and conditions, if the NPC has HP | AC, attack bonus, damage |
| The exchange rate, and everything the NPC has for sale with its price and stock | The NPC list, and wares of NPCs who are not in the scene |

This is enforced by the server, not just hidden on screen: the hidden fields
are never sent to a player's browser.

Changing an NPC's attitude changes what players see straight away, so
flipping a "Friendly" NPC to "Hostile" is itself a reveal.

## 7. NPC or monster?

| | NPC | Monster |
|---|---|---|
| Meant for | People with names and motives | Things to fight |
| Has a description players can read | Yes | No |
| Has an attitude | Yes | No |
| Has DM-only notes | Yes | Yes |
| Combat stats | Optional, basic | Full stat block |
| Can be in an encounter more than once | No | Yes (a pack of goblins) |
| Built-in library | No | Yes |
| Can change money and sell things | Yes | No |

A named villain the party will both talk to and fight works well as an NPC
with HP, AC, attack and damage filled in.

## 8. Permissions

| Action | DM | Players |
|---|---|---|
| See the NPC list | Yes | No |
| Add or remove NPCs | Yes | No |
| Add an NPC to an encounter | Yes | No |
| Change an NPC's HP or conditions in an encounter | Yes | No |
| See an NPC in an encounter | Everything | Name, role, attitude, description, health bar, exchange rate, wares |
| Set an NPC's exchange rate | Yes | No |
| Put things up for sale, or take them down | Yes | No |
| Change money with an NPC, or buy from one | Yes, for any character in the scene | For their own character in the scene |

## 9. What is not modelled

- Ability scores, saves, skills and spells for NPCs
- An NPC's own purse: they never run short of gold or cash
- Selling things to an NPC, haggling, and different rates for buying and
  selling cash
- Changing silver or copper for cash
- Where an NPC is (they are not tied to locations)
- Relationships, reputation and attitude toward individual characters
- A record of which NPCs the party has met, outside of encounters
- Portraits