# 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

```toml
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.