OpenRoads Spell System

The OpenRoads spell system is a comprehensive, flexible magic system that allows content creators to design spells using YAML and JSON configuration files without writing Go code. The system supports everything from simple damage spells to complex multi-effect magical abilities.

🚀 Quick Navigation

• New to spells? Start with the Spell Creation Quick Start

• Want to learn YAML? Follow the YAML Spell Tutorial

• Need hardcoded spells? Check the JSON Spell Guide

• Looking for examples? Browse the Custom Spells Directory

• Need reference docs? See Spell Effects Reference and Configuration Reference

🎯 System Overview

The OpenRoads spell system is built around three core principles:

1. Accessibility - Content creators can add spells without programming knowledge

2. Flexibility - Support for simple and complex spell behaviors

3. Performance - Efficient loading and execution of spells

🏗️ Architecture Components

• 📁 Custom Spell Files (spells/custom/*.yaml) - Individual spell files (recommended approach)

• 📄 YAML Configuration (world/spells.yaml) - Legacy bulk spell definitions

• ⚙️ JSON Configuration (world/spells.json) - Hardcoded spells and overrides

• ⚡ Effect System - Modular spell effects (damage, heal, summon, teleport, stat modification)

• ⏱️ Cooldown System - Per-player, per-spell cooldown tracking

• 🕐 Cast Time System - Spells with casting delays and interruption support

• ✅ Validation System - Element, level, resource, and target requirements

• 💬 Message System - Customizable feedback for all spell interactions

• 🚫 Restriction System - Combat, location, and instance limitations

File Structure

Custom Spell Files (spells/custom/*.yaml) - Recommended

Each spell in its own file:

# spells/custom/fireball.yaml
name: "Fireball"
description: "Hurls a ball of fire at target enemy"
element_required: "fire"      # Optional: fire, water, air, earth
min_spell_level: 10
min_phys_level: 0
sp_cost: 15
cast_time: 0                  # Seconds (0 = instant)
cooldown: 3                   # Seconds
target_type: "enemy"          # self, enemy, player, room, none
required_items: []            # List of required items
effects:
  - type: "damage"
    damage_min: 20
    damage_max: 35
    damage_type: "fire"
messages:
  success: "Your fireball engulfs %s in flames!"
  failure_element: "Only fire mages can cast fireball."
restrictions:
  combat_only: false
  non_combat_only: false

Legacy YAML Spells (world/spells.yaml)

Bulk spell definitions (still supported):

spells:
  spell_name:
    name: "Display Name"
    # ... same properties as above

JSON Spells (world/spells.json)

{
  "spells": {
    "spell_name": {
      "name": "Display Name",
      "custom_handler": "function_name"
    }
  }
}

File Loading Order

The spell system loads files in this order:

1. Main YAML file (world/spells.yaml) - Legacy bulk definitions

2. Custom YAML files (spells/custom/*.yaml) - Individual spell files (loaded alphabetically)

3. JSON files (world/spells.json) - Hardcoded spells and overrides

Later files can override earlier ones if they use the same spell name.

Creating Custom Spells

Recommended Approach: Individual Files

1. Create a new .yaml file in spells/custom/

2. Use a descriptive filename: meteor.yaml, heal.yaml, etc.

3. Define your spell using the single-spell format

4. Test in-game with the spells command

Example: Creating a New Spell

Create spells/custom/frost_bolt.yaml:

name: "Frost Bolt"
description: "Launches a bolt of freezing energy"
element_required: "water"
min_spell_level: 15
sp_cost: 20
cooldown: 4
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 30
    damage_max: 45
    damage_type: "ice"
messages:
  success: "Your frost bolt freezes %s solid!"
  failure_element: "Only water mages can cast frost bolt."

Benefits of Individual Files

• Easy Management: Each spell is self-contained

• Version Control: Better Git diffs and merge conflict resolution

• Collaboration: Multiple people can work on different spells

• Organization: Easy to find and edit specific spells

• Hot Reloading: Easier to reload individual spells (future feature)

Spell Properties

Basic Properties

• name: Display name of the spell

• description: Detailed description

• element_required: Required element (fire, water, air, earth, or empty for any)

• min_spell_level: Minimum spell level required

• min_phys_level: Minimum physical level required

• sp_cost: Spell point cost

• cast_time: Casting time in seconds (0 for instant)

• cooldown: Cooldown time in seconds

• target_type: Type of target required

Target Types

• self: Targets the caster

• enemy: Requires an enemy target

• player: Requires a player target

• room: Requires a room ID

• none: No target required

Required Items

List of item names that must be in the caster's inventory:

required_items: ["teleport scroll", "mana crystal"]

Effect Types

Damage Effects

effects:
  - type: "damage"
    damage_min: 20
    damage_max: 35
    damage_type: "fire"  # fire, ice, lightning, earth, etc.

Healing Effects

effects:
  - type: "heal"
    heal_min: 15
    heal_max: 25

Summoning Effects

effects:
  - type: "summon_creature"
    creature: "wolf"
    duration: -1          # -1 for permanent
    max_instances: 1

Teleportation Effects

effects:
  - type: "teleport"
    teleport:
      element_room: true  # Teleport to element room
      target_room: "123"  # Specific room
      random_room: true   # Random room in range
      room_range: [1, 100]

Stat Modification Effects

effects:
  - type: "stat_mod"
    stat_mod:
      str: 5              # Increase strength by 5
      dex: -2             # Decrease dexterity by 2
    duration: 300         # Duration in seconds

Messages

Standard Messages

• success: Successful cast message

• miss: Failed effect message

• failure_element: Wrong element message

• failure_level: Insufficient level message

• failure_sp: Insufficient spell points message

• failure_items: Missing required items message

• failure_cooldown: Spell on cooldown message

• failure_target: Invalid/missing target message

Cast Time Messages

• cast_start: Message when casting begins

• cast_complete: Message when casting completes

• cast_interrupt: Message when casting is interrupted

Broadcast Messages

• broadcast_effect: Message sent to other players in room

Message Formatting

Messages support %s placeholders for targets and %d for numbers:

success: "Your fireball engulfs %s in flames!"
failure_level: "You need spell level %d or higher. (Current: %d)"

Restrictions

Combat Restrictions

restrictions:
  combat_only: true      # Can only cast during combat
  non_combat_only: true  # Cannot cast during combat

Instance Restrictions

restrictions:
  max_instances: 1       # Maximum active instances of this spell

Location Restrictions

restrictions:
  required_rooms: ["1", "2", "3"]    # Can only cast in these rooms
  forbidden_rooms: ["10", "11"]      # Cannot cast in these rooms

Hardcoded Spells

For complex spells that require custom logic, use the JSON format with a custom_handler:

{
  "spells": {
    "servant": {
      "name": "Aerial Servant",
      "custom_handler": "cast_servant"
    }
  }
}

The handler function must be implemented in spell_engine.go in the handleCustomSpell function.

Commands

Player Commands

• cast - Show available spells

• cast <spell> - Cast a spell (if no target required)

• cast <spell> <target> - Cast a spell with target

• spells - Show detailed spell information

Admin Commands

Debug spells are available in spells.json for testing:

• debug_heal - Full heal

• debug_damage <enemy> - High damage

• debug_teleport <room> - Instant teleport

• debug_summon <room> - Summon debug creature

Examples

Simple Damage Spell

fireball:
  name: "Fireball"
  description: "Hurls a ball of fire at target enemy"
  element_required: "fire"
  min_spell_level: 10
  sp_cost: 15
  cooldown: 3
  target_type: "enemy"
  effects:
    - type: "damage"
      damage_min: 20
      damage_max: 35
      damage_type: "fire"
  messages:
    success: "Your fireball engulfs %s in flames!"
    failure_element: "Only fire mages can cast fireball."

Healing Spell with Cast Time

heal:
  name: "Heal"
  description: "Restores health to the caster"
  min_spell_level: 5
  sp_cost: 10
  cast_time: 2
  cooldown: 5
  target_type: "self"
  effects:
    - type: "heal"
      heal_min: 15
      heal_max: 25
  messages:
    cast_start: "You begin channeling healing energy..."
    success: "You feel your wounds close!"
  restrictions:
    non_combat_only: true

Teleport Spell with Requirements

teleport:
  name: "Teleport"
  description: "Teleports to a specified room"
  min_spell_level: 20
  sp_cost: 35
  cast_time: 3
  cooldown: 60
  target_type: "room"
  required_items: ["teleport scroll"]
  effects:
    - type: "teleport"
  messages:
    success: "You teleport to room %s!"
    failure_items: "You need %s to cast this spell."
  restrictions:
    non_combat_only: true

🔄 Hot Reloading

Spells can be reloaded without restarting the server by calling ReloadSpells() from the admin interface or by restarting the spell loading process. This feature is planned for future implementation.

🔗 System Integration

The spell system seamlessly integrates with all major game systems:

Core Game Systems

• 👤 Player System: Level and element validation, stat modifications

• 🎒 Inventory System: Required item checking and consumption

• ⚔️ Combat System: Damage dealing, healing effects, combat state tracking

• 🌍 World System: Room targeting, teleportation, location restrictions

• 👹 Enemy System: Enemy targeting, health management, summoning

Advanced Integrations

• 🏃 Routine Engine: Background spell processing, cooldown management

• 💾 Save System: Persistent spell cooldowns and effects

• 📊 Statistics: Spell usage tracking and analytics

• 🔐 Permission System: Admin spell access control

• 📝 Logging System: Comprehensive spell event logging

📚 Complete Documentation Suite

🎯 Getting Started

• Spell Creation Quick Start - Create your first spell in 5 minutes

• YAML Spell Tutorial - Comprehensive YAML spell creation guide

• Custom Spells Directory - Examples and file management

📖 Reference Documentation

• Spell Effects Reference - Complete effects documentation

• Spell Configuration Reference - All properties and options

• JSON Spell Guide - Advanced hardcoded spells

🎮 Content Creation

• Spell Design Guidelines - Best practices for spell design

• Spell Balance Guide - Balancing spells for gameplay

• Spell Testing Guide - Testing procedures and tips

🎉 Success Stories

The spell system has successfully enabled:

• 19+ Spells: Currently loaded and functional

• 8 Custom Files: Individual YAML spell files

• Multiple Effect Types: Damage, healing, teleportation, summoning, stat modification

• Zero Downtime: Hot-reloadable spell definitions

• Easy Maintenance: Non-programmers can create and modify spells