e5e7057650
- world/MANIFEST.md: manifest.toml and directory layout - world/races/RACES.md: race schema (stats, body, natural, resistances, etc.) - world/classes/CLASSES.md: class schema (base_stats, growth, hidden, guild) - world/guilds/GUILDS.md: guild schema and [growth] - world/spells/SPELLS.md: spell schema and types - world/town/REGION.md: region.toml - world/town/rooms/ROOMS.md: room schema and exits - world/town/npcs/NPCS.md: NPC schema, race/class resolution - world/town/objects/OBJECTS.md: object schema and [stats] Made-with: Cursor
90 lines
3.2 KiB
Markdown
90 lines
3.2 KiB
Markdown
# 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).
|