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

Contents

1. The basics
2. What an NPC holds
3. Managing NPCs
4. NPCs in encounters
5. Trade: changing money and selling
6. What players see
7. NPC or monster?
8. Permissions
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, 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, 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, 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