mudserver/world/races/RACES.md

Race TOML Reference

Each file in world/races/ defines one race. The filename (without .toml) becomes the race ID with prefix race: (e.g. human.toml → race:human).

Top-level fields

Field	Type	Required	Default	Description
name	string	Yes	—	Display name of the race.
description	string	Yes	—	Short description shown in chargen and elsewhere.
metarace	string	No	—	Category (e.g. "animal", "draconic"). Used for flavour and filtering; NPCs without a fixed race are chosen from races that are not hidden (metarace does not exclude them from random NPC pool).
hidden	boolean	No	false	If true, the race does not appear in character creation. Use for NPC-only races (e.g. Beast).
default_class	string	No	—	Class ID (e.g. "class:peasant") used as the default class for NPCs of this race when the NPC has no fixed class. Omit for “random compatible class” (e.g. Dragon).

[stats] — Stat modifiers

All values are integers applied as modifiers (e.g. +1, -2). Defaults are 0 if omitted.

Field	Description
strength	STR modifier.
dexterity	DEX modifier.
constitution	CON modifier.
intelligence	INT modifier.
wisdom	WIS modifier.
perception	PER modifier.
charisma	CHA modifier.

[body]

Field	Type	Required	Default	Description
size	string	No	"medium"	One of: "tiny", "small", "medium", "large", "huge". Flavour and potential future rules.
weight	integer	No	0	Weight in arbitrary units.
slots	array of strings	No	humanoid default	Equipment slot names this race can use. If empty, default humanoid slots are used: head, neck, torso, legs, feet, main_hand, off_hand, finger, finger.

[natural] — Natural armor and attacks

Field	Type	Required	Default	Description
armor	integer	No	0	Natural armor bonus added to defense.

[natural.attacks.<name>]

Each key under natural.attacks defines one natural attack (e.g. bite, claw, fire_breath).

Field	Type	Required	Default	Description
damage	integer	No	0	Base damage.
type	string	No	"physical"	Damage type (e.g. "physical", "fire", "magical").
cooldown_ticks	integer	No	—	If set, minimum ticks between uses of this attack.

[resistances]

Map of damage type → multiplier (float).

• 0.0 = immune
• 1.0 = normal
• 1.5 = vulnerable (e.g. 50% more damage)
• < 1.0 = resistant (e.g. 0.5 = half damage)

Example: fire = 0.0, cold = 1.5, physical = 0.7

traits and disadvantages

Top-level arrays of strings (free-form). Shown in chargen and used for flavour.

• traits — e.g. ["darkvision", "lucky"]
• disadvantages — e.g. ["light_sensitivity"]

[regen] — Regeneration multipliers

Multipliers applied to passive HP/mana/endurance regen. Float; default 1.0.

Field	Description
hp	HP regen multiplier.
mana	Mana regen multiplier.
endurance	Endurance regen multiplier.

[guild_compatibility]

Used when picking a random class for NPCs (and potentially future guild rules). Guild IDs in each list are string identifiers (e.g. "guild:warriors_guild").

Field	Description
good	Guilds this race is well suited to.
average	Guilds with no special modifier.
poor	Guilds this race is poorly suited to.
restricted	Guilds this race cannot join.

All default to empty arrays.

[misc]

Field	Type	Required	Default	Description
lifespan	integer	No	—	Flavour lifespan.
diet	string	No	—	Flavour diet (e.g. "omnivore", "carnivore").
xp_rate	float	No	1.0	Multiplier for XP gain (e.g. 0.7 = slower leveling).
natural_terrain	array of strings	No	[]	Flavour terrain list.
vision	array of strings	No	[]	Vision types (e.g. ["normal", "darkvision", "infravision"]).

Minimal example

name = "Human"
description = "Versatile and adaptable."
default_class = "class:peasant"

[stats]
charisma = 1

Full example (excerpt)

See dragon.toml for a race using body slots, natural attacks, resistances, regen, and guild compatibility.