Spell System Troubleshooting

Common issues and solutions for the OpenRoads spell system.

🚨 Quick Fixes

Spell Not Loading

1. Check file location: Must be in spells/custom/ directory

2. Verify file extension: Use .yaml or .yml

3. Validate YAML syntax: Use online YAML validator

4. Check server logs: Look for parsing errors

5. Restart server: Sometimes needed after file changes

Spell Won't Cast

1. Check requirements: Level, element, SP, items

2. Verify target: Correct target type and valid target

3. Check cooldown: Wait for cooldown to expire

4. Check restrictions: Combat/location limitations

5. Check spelling: Spell name must match exactly

Effects Not Working

1. Verify effect syntax: Check effect type spelling

2. Check target validity: Enemy must exist, room must be valid

3. Review effect properties: Ensure all required fields present

4. Check logs: Look for effect execution errors

5. Test with simple effects: Start with basic damage/heal

📁 File and Loading Issues

Spell File Not Found

Symptoms:

• Spell doesn't appear in spell list

• No loading messages in server logs

• spells command doesn't show your spell

Solutions:

# Check file location
ls spells/custom/your_spell.yaml

# Verify directory exists
mkdir -p spells/custom

# Check file permissions
chmod 644 spells/custom/your_spell.yaml

YAML Syntax Errors

Common Syntax Issues:

Missing Quotes:

# Wrong:
name: Magic Missile

# Right:
name: "Magic Missile"

Incorrect Indentation:

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

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

Invalid List Format:

# Wrong:
required_items: "item1", "item2"

# Right:
required_items:
  - "item1"
  - "item2"

Mixed Tabs and Spaces:

# Use only spaces, never tabs
effects:
  - type: "damage"    # 2 spaces
    damage_min: 20    # 4 spaces

Validation Errors

Missing Required Properties:

# Error: Missing required properties
name: "Test Spell"
# Missing: description, sp_cost, target_type, effects

# Fixed:
name: "Test Spell"
description: "A test spell"
sp_cost: 10
target_type: "self"
effects:
  - type: "heal"
    heal_min: 5
    heal_max: 10

Invalid Property Values:

# Error: Invalid target_type
target_type: "invalid"

# Fixed:
target_type: "enemy"  # Must be: self, enemy, player, room, none

⚔️ Casting and Effect Issues

Spell Requirements Not Met

Element Requirement:

Error: "Only fire mages can cast this spell."
Solution: 
- Check player element matches spell requirement
- Use empty string "" for no element requirement

Level Requirement:

Error: "You need spell level 15 or higher. (Current: 10)"
Solution:
- Level up character or reduce min_spell_level
- Check both spell_level and phys_level requirements

Insufficient Spell Points:

Error: "Not enough spell points. (Need: 25, Have: 15)"
Solution:
- Rest to restore SP or reduce sp_cost
- Check SP cost is reasonable for spell power

Missing Required Items:

Error: "You need teleport scroll to cast this spell."
Solution:
- Add required items to inventory
- Check item names match exactly (case-sensitive)
- Verify items aren't consumed by other spells

Target Issues

Invalid Enemy Target:

Error: "That enemy is not here."
Solutions:
- Check enemy name spelling
- Verify enemy exists in current room
- Use partial names (e.g., "orc" for "orc warrior")

Invalid Room Target:

Error: "That room does not exist."
Solutions:
- Check room ID is valid number
- Verify room exists in world data
- Use string format for room IDs in YAML

Wrong Target Type:

Error: "You must specify a target enemy."
Solutions:
- Check target_type matches usage
- Provide target when required
- Use correct command format

Effect Problems

Damage Not Applied:

# Check effect syntax
effects:
  - type: "damage"
    damage_min: 20      # Required
    damage_max: 35      # Required
    damage_type: "fire" # Optional but recommended

Healing Not Working:

# Verify healing effect
effects:
  - type: "heal"
    heal_min: 15        # Required
    heal_max: 25        # Required

Teleportation Failing:

# Check teleport configuration
effects:
  - type: "teleport"
    teleport:
      element_room: true  # OR target_room, OR random_room

Summoning Issues:

# Verify summoning setup
effects:
  - type: "summon_creature"
    creature: "wolf"     # Must match enemy definition
    max_instances: 1     # Prevent spam

🔧 Configuration Issues

Cooldown Problems

Cooldown Not Working:

# Ensure cooldown is properly set
cooldown: 10  # Seconds, not minutes

Cooldown Too Long/Short:

# Balance cooldown with power
low_power_spell:
  cooldown: 2

high_power_spell:
  cooldown: 60

Cast Time Issues

Cast Time Not Triggering:

# Verify cast time syntax
cast_time: 5  # Seconds

Casting Interrupted:

• Don't move during cast time

• Avoid taking damage

• Check for interruption messages

Restriction Problems

Combat Restrictions:

restrictions:
  combat_only: true      # Can only cast in combat
  non_combat_only: true  # Can only cast outside combat
  # Don't set both to true!

Location Restrictions:

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

📊 Balance and Performance Issues

Spell Too Powerful

Symptoms:

• Trivializes combat

• Makes other spells obsolete

• Breaks game progression

Solutions:

# Increase costs
sp_cost: 50  # Was 15

# Add cooldown
cooldown: 60  # Was 0

# Add restrictions
restrictions:
  non_combat_only: true
  max_instances: 1

# Reduce effects
effects:
  - type: "damage"
    damage_min: 25  # Was 50
    damage_max: 40  # Was 80

Spell Too Weak

Symptoms:

• Never worth using

• Cost too high for benefit

• Other options always better

Solutions:

# Reduce costs
sp_cost: 10  # Was 25

# Reduce cooldown
cooldown: 5  # Was 30

# Increase effects
effects:
  - type: "damage"
    damage_min: 30  # Was 15
    damage_max: 45  # Was 20

Performance Issues

Server Lag:

• Reduce spell complexity

• Add reasonable cooldowns

• Limit max_instances for summoning

• Check for infinite loops in custom handlers

Memory Usage:

• Clean up temporary effects

• Limit persistent summons

• Monitor long-duration stat modifications

🔍 Debugging Techniques

Enable Debug Logging

Check server logs for detailed information:

2025/06/04 23:47:25 SPELL: Loaded custom spell from fireball.yaml: Fireball
2025/06/04 23:47:25 SPELL: Player cast fireball (SP: 35/50)

Test with Simple Spells

Start with minimal spell to isolate issues:

name: "Debug Test"
description: "Simple test spell"
sp_cost: 1
target_type: "self"
effects:
  - type: "heal"
    heal_min: 1
    heal_max: 1

Use Debug Spells

Test with admin debug spells:

cast debug_heal
cast debug_damage orc
cast debug_teleport 5

Check Game State

Verify character state:

status  # Check levels and SP
spells  # See available spells
inventory  # Check required items

📞 Getting Help

Information to Provide

When asking for help, include:

1. Spell file content (YAML)

2. Error messages (exact text)

3. Server logs (relevant portions)

4. Character details (level, element, SP)

5. Steps to reproduce the issue

Common Support Channels

1. Documentation - Check all guides first

2. Examples - Look at working spells in spells/custom/

3. Server logs - Often contain the answer

4. Community - Ask other content creators

Self-Help Checklist

Before asking for help:

• Read relevant documentation

• Check server logs for errors

• Validate YAML syntax

• Test with simple spell first

• Compare with working examples

• Try restarting server

🎯 Prevention Tips

Best Practices

1. Start Simple - Begin with basic spells

2. Test Frequently - Test after each change

3. Use Examples - Copy from working spells

4. Validate Syntax - Check YAML before testing

5. Read Logs - Monitor server output

6. Document Changes - Keep notes on modifications

Common Mistakes to Avoid

• Using tabs instead of spaces

• Forgetting quotes around strings

• Missing required properties

• Invalid property values

• Incorrect file locations

• Overpowered spell effects

🎉 Success Tips

When Everything Works

1. Document what you did right

2. Share successful patterns with others

3. Test thoroughly before considering complete

4. Backup working configurations

5. Iterate to improve balance and fun

Building Expertise

1. Study examples in detail

2. Experiment with different configurations

3. Learn from failures - they teach the most

4. Help others - teaching reinforces learning

5. Stay updated - follow system improvements

🎓 Conclusion

Most spell issues are caused by simple syntax errors or missing requirements. Work through this guide systematically, and you'll resolve most problems quickly.

Quick Reference

• File location: spells/custom/spell_name.yaml

• Required properties: name, description, sp_cost, target_type, effects

• Common errors: YAML syntax, missing quotes, wrong indentation

• Debug tools: Server logs, debug spells, simple test spells

Remember: Every expert was once a beginner who didn't give up! Keep experimenting and learning! ✨