mudserver/world/spells/SPELLS.md

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):

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:

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:

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:

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