# NPCs

How non-player characters work in this app: what the DM records about them,
how they are brought into a scene, 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. [What players see](#5-what-players-see)
6. [NPC or monster?](#6-npc-or-monster)
7. [Permissions](#7-permissions)
8. [What is not modelled](#8-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.

## 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 5 |
| Attack bonus | Optional | DM only |
| Damage | Optional dice, e.g. `1d6` | DM only |

A new NPC is Neutral unless you choose otherwise.

## 3. Managing NPCs

The NPC list is the "NPCs" card on the campaign page (DM only).

- **Adding:** "+ Add NPC" opens a form with every field above. Only the name
  is required.
- **Changing:** there is no edit form. To change an NPC, remove it and add it
  again (the API accepts changes, but no screen offers them).
- **Removing:** the ✕ button, 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. 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 |

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.

## 6. 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 |

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

## 7. 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 |

## 8. What is not modelled

- Ability scores, saves, skills and spells for NPCs
- NPC inventory, gold and shops
- 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