Spell Creation Quick Start Guide

Get started creating your first spell in OpenRoads in just 5 minutes!

🚀 Quick Start

Step 1: Create Your Spell File

Create a new file in the spells/custom/ directory:

# Example: Create a simple damage spell
touch spells/custom/magic_missile.yaml

Step 2: Define Your Spell

Add this basic spell definition:

name: "Magic Missile"
description: "Launches a magical projectile at target enemy"
element_required: ""
min_spell_level: 5
sp_cost: 8
cooldown: 2
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 12
    damage_max: 18
    damage_type: "magic"
messages:
  success: "Your magic missile strikes %s!"
  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 enemy."

Step 3: Test Your Spell

1. Start the OpenRoads server

2. Connect to the game

3. Use spells command to see your new spell

4. Cast it with: cast magic_missile <enemy_name>

🎯 Common Spell Types

Damage Spell

name: "Fireball"
description: "Hurls a ball of fire"
element_required: "fire"
min_spell_level: 10
sp_cost: 15
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 20
    damage_max: 35
    damage_type: "fire"

Healing Spell

name: "Heal"
description: "Restores health"
min_spell_level: 5
sp_cost: 10
cast_time: 2
target_type: "self"
effects:
  - type: "heal"
    heal_min: 15
    heal_max: 25
restrictions:
  non_combat_only: true

Teleport Spell

name: "Recall"
description: "Return to your element room"
min_spell_level: 3
sp_cost: 20
cast_time: 5
target_type: "self"
effects:
  - type: "teleport"
    teleport:
      element_room: true
restrictions:
  non_combat_only: true

Summoning Spell

name: "Summon Wolf"
description: "Summons a wolf companion"
element_required: "earth"
min_spell_level: 18
sp_cost: 30
cast_time: 4
target_type: "room"
effects:
  - type: "summon_creature"
    creature: "wolf"
    max_instances: 1

📋 Essential Properties

Required Properties

• name: Display name

• description: What the spell does

• sp_cost: Spell point cost

• target_type: Who/what the spell targets

• effects: What the spell does

Common Optional Properties

• element_required: Element restriction

• min_spell_level: Level requirement

• cast_time: Casting delay in seconds

• cooldown: Cooldown in seconds

• required_items: Items needed to cast

• messages: Custom messages

• restrictions: When/where it can be cast

🎮 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

⚡ Effect Types

• "damage" - Deal damage to target

• "heal" - Restore health

• "teleport" - Move player to location

• "summon_creature" - Summon a creature

• "stat_mod" - Modify player stats

💬 Message Placeholders

Use these in your messages:

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

• %d - Numbers (levels, spell points)

Example:

messages:
  success: "Your %s spell hits %s for %d damage!"
  failure_level: "Need level %d (you're %d)"

🔧 Testing Tips

1. Start Simple: Begin with basic damage or heal spells

2. Test Thoroughly: Try different character levels and elements

3. Check Balance: Make sure damage/cost ratios are fair

4. Use Examples: Look at existing spells in spells/custom/

5. Read Errors: The server logs will show YAML parsing errors

📚 Next Steps

Once you've created your first spell:

1. Read the YAML Spell Tutorial for detailed explanations

2. Check the Spell Effects Reference for all available effects

3. Review Custom Spells Directory for more examples

4. Study existing spells in the spells/custom/ directory

🚨 Common Mistakes

• Missing quotes: Always quote string values

• Wrong indentation: YAML is sensitive to spaces

• Invalid target_type: Must be one of the valid types

• Missing required fields: name, sp_cost, target_type, effects are required

• Typos in effect types: Check spelling of "damage", "heal", etc.

🎉 Congratulations!

You've created your first spell! The spell system is very flexible - you can create simple spells like the examples above, or complex multi-effect spells with cast times, cooldowns, and restrictions.

Happy spell crafting! ✨