mudserver/world/town/npcs/NPCS.md

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):

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):

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:

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