# NPC TOML Reference

Each file in a region’s `npcs/` folder (e.g. `world/town/npcs/`) defines one NPC template. The NPC ID is `"<region>:<filename_stem>"` (e.g. `barkeep.toml` in region `town` → `town:barkeep`). Race and class are resolved at **spawn time** (and again on respawn if not fixed); omit them for random selection.

## Top-level fields

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | — | Display name. |
| `description` | string | Yes | — | Shown when the player looks at or examines the NPC. |
| `room` | string | Yes | — | Full room ID where the NPC appears (e.g. `"town:tavern"`). |
| `base_attitude` | string | No | `"neutral"` | One of: `friendly`, `neutral`, `wary`, `aggressive`, `hostile`. Hostile NPCs auto-engage players in the room. |
| `faction` | string | No | — | Optional faction ID for attitude grouping. |
| `race` | string | No | — | Race ID (e.g. `"race:beast"`, `"race:human"`). If omitted, a random non-hidden race is chosen at each spawn/respawn. |
| `class` | string | No | — | Class ID (e.g. `"class:peasant"`, `"class:rogue"`). If omitted, the race’s `default_class` is used, or a random compatible non-hidden class. |
| `respawn_secs` | integer | No | — | If set, the NPC respawns this many seconds after death. Race/class are re-rolled on respawn unless fixed above. |
| `dialogue` | table | No | — | See below. |
| `combat` | table | No | — | If set, the NPC can be attacked and has combat stats. If omitted, the NPC has default combat stats when attacked. |

## `[dialogue]`

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `greeting` | string | No | — | Line shown when a player uses `talk` on this NPC (only if attitude allows talking). |

## `[combat]`

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `max_hp` | integer | Yes | — | Maximum HP. |
| `attack` | integer | Yes | — | Attack value. |
| `defense` | integer | Yes | — | Defense value. |
| `xp_reward` | integer | No | `0` | XP awarded when the NPC is killed. |

## Examples

**Fixed race/class (e.g. animal):**

```toml
name = "Giant Rat"
description = "A mangy rat the size of a small dog."
room = "town:cellar"
base_attitude = "hostile"
race = "race:beast"
class = "class:creature"
respawn_secs = 60

[combat]
max_hp = 25
attack = 6
defense = 2
xp_reward = 15
```

**Random race, fixed class (e.g. barkeep):**

```toml
name = "Grizzled Barkeep"
description = "A weathered man with thick forearms."
room = "town:tavern"
base_attitude = "friendly"

[dialogue]
greeting = "Welcome to The Rusty Tankard."
```

(No `race` or `class` → random race each spawn, default class from race, e.g. Peasant for humanoids.)

**Fixed class, random race:**

```toml
name = "Shadowy Thief"
description = "A cloaked figure lurking in the darkness."
room = "town:dark_alley"
base_attitude = "aggressive"
faction = "underworld"
class = "class:rogue"
respawn_secs = 90

[combat]
max_hp = 45
attack = 12
defense = 6
xp_reward = 35
```

## Display

`look <npc>` and `examine <npc>` show the NPC’s **resolved** race and class (from the current spawn instance).