# Spell TOML Reference

Each file in `world/spells/` defines one spell or skill. The filename (without `.toml`) becomes the spell ID with prefix `spell:` (e.g. `magic_missile.toml` → `spell:magic_missile`). Spells are referenced from guilds in `world/guilds/*.toml`.

## Top-level fields

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | — | Display name. |
| `description` | string | Yes | — | Short description shown in `spells` and `guild info`. |
| `spell_type` | string | No | `"offensive"` | One of: `"offensive"`, `"heal"`, `"utility"`. Affects when and how the spell can be used (e.g. heal/utility out of combat; offensive usually in combat). |
| `damage` | integer | No | `0` | Base damage for offensive spells. |
| `heal` | integer | No | `0` | HP restored for heal spells. |
| `damage_type` | string | No | `"magical"` | Damage type (e.g. `"physical"`, `"fire"`, `"magical"`, `"holy"`, `"poison"`). |
| `cost_mana` | integer | No | `0` | Mana cost to cast. |
| `cost_endurance` | integer | No | `0` | Endurance cost to cast. |
| `cooldown_ticks` | integer | No | `0` | Ticks before the spell can be used again. |
| `casting_ticks` | integer | No | `0` | Ticks before the spell resolves (future use; currently casting is one tick). |
| `min_guild_level` | integer | No | `0` | Minimum guild level required to know/use this spell. |
| `effect` | string | No | — | Status effect kind applied (e.g. `"poison"`, `"regen"`, `"defense_up"`). |
| `effect_duration` | integer | No | `0` | Duration of the effect in ticks. |
| `effect_magnitude` | integer | No | `0` | Magnitude (e.g. damage per tick for poison, heal per tick for regen). |

## Spell types

- **offensive** — Deals damage to current combat target. Requires combat; blocked out of combat.
- **heal** — Restores HP. Can be used in or out of combat; out of combat resolves immediately.
- **utility** — Buffs, cleanses, etc. Can apply status effects; out of combat resolves immediately.

## Examples

**Offensive (mana):**

```toml
name = "Magic Missile"
description = "Hurl bolts of pure arcane energy."
spell_type = "offensive"
damage = 15
damage_type = "magical"
cost_mana = 10
cooldown_ticks = 1
min_guild_level = 1
```

**Heal:**

```toml
name = "Heal"
description = "Channel divine energy to mend wounds."
spell_type = "heal"
heal = 25
cost_mana = 15
cooldown_ticks = 2
min_guild_level = 1
```

**Utility with effect:**

```toml
name = "Battle Cry"
description = "A thunderous war shout that steels your resolve."
spell_type = "utility"
cost_endurance = 10
cooldown_ticks = 10
min_guild_level = 3
effect = "regen"
effect_duration = 5
effect_magnitude = 4
```

**Offensive with DoT:**

```toml
name = "Poison Blade"
description = "Coat your weapon with virulent toxin."
spell_type = "offensive"
damage = 8
damage_type = "poison"
cost_endurance = 10
cooldown_ticks = 6
min_guild_level = 3
effect = "poison"
effect_duration = 4
effect_magnitude = 3
```