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

📝 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

Check server logs for YAML parsing errors
Verify file is in spells/custom/ directory
Ensure file has .yaml or .yml extension
Validate YAML syntax online

Spell Not Working

Check all required properties are present
Verify target_type matches how you're casting
Check element and level requirements
Ensure effect types are spelled correctly

Performance Issues

Avoid very short cooldowns on powerful spells
Limit max_instances for summoning spells
Use reasonable cast times for balance

🎓 Graduation

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

Spell Effects Reference - Complete effect documentation
JSON Spell Guide - Learn about hardcoded spells
Custom Spells Directory - See more examples
Experiment - Try creating your own unique spells!

Happy spell crafting! ✨

PreviousSpell System Troubleshooting

Last updated 6 months ago

Was this helpful?