Add TOML reference docs for all world data types
- 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
This commit is contained in:
AI Agent
117
world/races/RACES.md
Normal file
117
world/races/RACES.md
Normal file
@@ -0,0 +1,117 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user