# Guild TOML Reference

Each file in `world/guilds/` defines one guild. The filename (without `.toml`) becomes the guild ID with prefix `guild:` (e.g. `warriors_guild.toml` → `guild:warriors_guild`).

## Top-level fields

Put these **before** any `[section]` headers so they are not parsed as part of a table.

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | — | Display name of the guild. |
| `description` | string | Yes | — | Short description. |
| `max_level` | integer | No | `50` | Maximum guild level. |
| `resource` | string | No | `"mana"` | Primary resource: `"mana"` or `"endurance"`. |
| `base_mana` | integer | No | `0` | Mana granted when joining (and per new member level if used). |
| `base_endurance` | integer | No | `0` | Endurance granted when joining. |
| `spells` | array of strings | No | `[]` | Spell IDs (e.g. `"spell:power_strike"`) this guild grants. Order can matter for display. |
| `min_player_level` | integer | No | `0` | Minimum character level required to join. |
| `race_restricted` | array of strings | No | `[]` | Race IDs (e.g. `"race:dragon"`) that cannot join this guild. |

## `[growth]` — Per guild-level gains

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `hp_per_level` | integer | No | `0` | HP per guild level. |
| `mana_per_level` | integer | No | `0` | Mana per guild level. |
| `endurance_per_level` | integer | No | `0` | Endurance per guild level. |
| `attack_per_level` | integer | No | `0` | Attack per guild level. |
| `defense_per_level` | integer | No | `0` | Defense per guild level. |

## Important: TOML layout

Top-level keys such as `spells`, `min_player_level`, and `race_restricted` must appear **before** the `[growth]` section. Otherwise they are parsed as part of `[growth]` and ignored.

## Example

```toml
name = "Warriors Guild"
description = "Masters of martial combat."
max_level = 50
resource = "endurance"
base_mana = 0
base_endurance = 50
spells = ["spell:power_strike", "spell:battle_cry", "spell:shield_wall", "spell:whirlwind"]
min_player_level = 0
race_restricted = []

[growth]
hp_per_level = 8
mana_per_level = 0
endurance_per_level = 5
attack_per_level = 2
defense_per_level = 1
```

## Spell IDs

Spell IDs are the spell’s file stem with prefix `spell:` (e.g. `world/spells/power_strike.toml` → `spell:power_strike`). Spells are defined in `world/spells/*.toml`; see `world/spells/SPELLS.md`.