YAML Spell Tutorial

This comprehensive tutorial will teach you everything you need to know about creating spells using YAML files in OpenRoads.

📚 Table of Contents

1. YAML Basics

2. Spell File Structure

3. Required Properties

4. Optional Properties

5. Effect System

6. Message System

7. Restrictions

8. Advanced Examples

9. Best Practices

10. Troubleshooting

📝 YAML Basics

YAML (YAML Ain't Markup Language) is a human-readable data format. Here are the key rules:

Indentation

• Use spaces, not tabs

• Consistent indentation (usually 2 spaces)

• Child elements are indented more than parents

parent:
  child: value
  another_child:
    grandchild: value

Data Types

string: "Text in quotes"
number: 42
boolean: true
list:
  - item1
  - item2
  - item3
object:
  key: value
  another_key: "another value"

Quotes

• Always quote strings that might be confused for other types

• Quote strings with special characters

• Numbers and booleans don't need quotes

🏗️ Spell File Structure

Each spell file should contain a single spell definition:

name: "Spell Name"
description: "What the spell does"
element_required: "fire"
min_spell_level: 10
min_phys_level: 0
sp_cost: 15
cast_time: 0
cooldown: 3
target_type: "enemy"
required_items: []
effects:
  - type: "damage"
    damage_min: 20
    damage_max: 35
    damage_type: "fire"
messages:
  success: "Your spell succeeds!"
  failure_element: "Only fire mages can cast this."
restrictions:
  combat_only: false
  non_combat_only: false

✅ Required Properties

Every spell must have these properties:

name (string)

The display name of the spell.

name: "Fireball"

description (string)

A brief description of what the spell does.

description: "Hurls a ball of fire at target enemy"

sp_cost (number)

How many spell points the spell costs to cast.

sp_cost: 15

target_type (string)

What the spell targets. Must be one of:

• "self" - Targets the caster

• "enemy" - Requires an enemy target

• "player" - Requires a player target

• "room" - Requires a room ID

• "none" - No target required

target_type: "enemy"

effects (list)

What the spell actually does. Must contain at least one effect.

effects:
  - type: "damage"
    damage_min: 20
    damage_max: 35
    damage_type: "fire"

🔧 Optional Properties

Element and Level Requirements

element_required: "fire"        # "fire", "water", "air", "earth", or ""
min_spell_level: 10            # Minimum spell level (default: 0)
min_phys_level: 5              # Minimum physical level (default: 0)

Timing

cast_time: 3                   # Casting time in seconds (default: 0)
cooldown: 10                   # Cooldown in seconds (default: 0)

Requirements

required_items:                # Items needed in inventory
  - "teleport scroll"
  - "mana crystal"

⚡ Effect System

Effects define what your spell actually does. You can have multiple effects in one spell.

Damage Effects

effects:
  - type: "damage"
    damage_min: 20              # Minimum damage
    damage_max: 35              # Maximum damage
    damage_type: "fire"         # Damage type (for flavor)

Healing Effects

effects:
  - type: "heal"
    heal_min: 15                # Minimum healing
    heal_max: 25                # Maximum healing

Teleportation Effects

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

Summoning Effects

effects:
  - type: "summon_creature"
    creature: "wolf"            # Creature to summon
    duration: -1                # -1 for permanent
    max_instances: 1            # Max active summons

Stat Modification Effects

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

💬 Message System

Customize messages for different situations:

Basic Messages

messages:
  success: "Your spell succeeds!"
  miss: "Your spell fails!"
  failure_element: "Only fire mages can cast this."
  failure_level: "You need spell level %d or higher. (Current: %d)"
  failure_sp: "Not enough spell points. (Need: %d, Have: %d)"
  failure_target: "You must specify a target."
  failure_items: "You need %s to cast this spell."
  failure_cooldown: "This spell is still on cooldown."

Cast Time Messages

messages:
  cast_start: "You begin casting..."
  cast_complete: "Your spell is complete!"
  cast_interrupt: "Your casting was interrupted!"

Broadcast Messages

messages:
  broadcast_effect: "%s casts a powerful spell!"

Message Placeholders

• %s - String values (target names, item names)

• %d - Numeric values (levels, spell points, damage)

Example:

success: "Your %s spell hits %s for %d damage!"

🚫 Restrictions

Control when and where spells can be cast:

Combat Restrictions

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

Instance Limits

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

Location Restrictions

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

🎯 Advanced Examples

Multi-Effect Spell

name: "Vampiric Strike"
description: "Damages enemy and heals caster"
element_required: ""
min_spell_level: 15
sp_cost: 25
cooldown: 8
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 30
    damage_max: 45
    damage_type: "dark"
  - type: "heal"
    heal_min: 10
    heal_max: 15
messages:
  success: "You drain life from %s, healing yourself!"
  failure_level: "You need spell level %d or higher. (Current: %d)"

Complex Teleport Spell

name: "Dimensional Door"
description: "Teleports to any room with a long cast time"
element_required: ""
min_spell_level: 25
sp_cost: 50
cast_time: 8
cooldown: 300
target_type: "room"
required_items:
  - "dimensional key"
effects:
  - type: "teleport"
    teleport:
      target_room: ""
messages:
  success: "You step through the dimensional door to room %s!"
  failure_items: "You need %s to open a dimensional door."
  cast_start: "You begin tearing a hole in reality..."
  cast_complete: "A shimmering portal opens before you!"
  cast_interrupt: "The dimensional fabric snaps back into place!"
restrictions:
  non_combat_only: true

Summoning with Restrictions

name: "Summon Fire Elemental"
description: "Summons a powerful fire elemental"
element_required: "fire"
min_spell_level: 30
sp_cost: 75
cast_time: 10
cooldown: 600
target_type: "room"
required_items:
  - "elemental essence"
  - "summoning circle"
effects:
  - type: "summon_creature"
    creature: "fire elemental"
    duration: 1800
    max_instances: 1
messages:
  success: "A fire elemental materializes in room %s!"
  failure_element: "Only fire mages can summon fire elementals."
  cast_start: "You begin the complex summoning ritual..."
  cast_complete: "Flames swirl as your elemental takes form!"
restrictions:
  non_combat_only: true
  max_instances: 1
  forbidden_rooms:
    - "6"  # Water room

📋 Best Practices

File Organization

• Use descriptive filenames: fireball.yaml, greater_heal.yaml

• One spell per file

• Group related spells with prefixes: fire_bolt.yaml, fire_wall.yaml

Spell Design

• Start with simple effects and add complexity gradually

• Balance SP cost with power level

• Consider cast time vs. power (more powerful = longer cast time)

• Use appropriate cooldowns to prevent spam

YAML Style

• Use consistent indentation (2 spaces recommended)

• Quote all string values

• Use descriptive comments when needed

• Keep lines under 80 characters when possible

Testing

• Test with different character levels

• Test with different elements

• Test edge cases (no SP, wrong element, etc.)

• Verify all messages display correctly

🐛 Troubleshooting

Common YAML Errors

Indentation Error:

# Wrong:
effects:
- type: "damage"  # Not indented enough

# Right:
effects:
  - type: "damage"  # Properly indented

Missing Quotes:

# Wrong:
name: Magic Missile  # Might be parsed incorrectly

# Right:
name: "Magic Missile"  # Always quote strings

Invalid List Syntax:

# Wrong:
required_items: "teleport scroll", "mana crystal"

# Right:
required_items:
  - "teleport scroll"
  - "mana crystal"

Spell Not Loading

1. Check server logs for YAML parsing errors

2. Verify file is in spells/custom/ directory

3. Ensure file has .yaml or .yml extension

4. Validate YAML syntax online

Spell Not Working

1. Check all required properties are present

2. Verify target_type matches how you're casting

3. Check element and level requirements

4. Ensure effect types are spelled correctly

Performance Issues

1. Avoid very short cooldowns on powerful spells

2. Limit max_instances for summoning spells

3. Use reasonable cast times for balance

🎓 Graduation

Congratulations! You now know how to create YAML spells in OpenRoads. Here's what to explore next:

1. Spell Effects Reference - Complete effect documentation

2. JSON Spell Guide - Learn about hardcoded spells

3. Custom Spells Directory - See more examples

4. Experiment - Try creating your own unique spells!

Happy spell crafting! ✨