Spell Effects Reference

Complete reference for all available spell effects in the OpenRoads spell system.

📚 Table of Contents

1. Effect Overview

2. Damage Effects

3. Healing Effects

4. Teleportation Effects

5. Summoning Effects

6. Stat Modification Effects

7. Custom Effects

8. Multiple Effects

9. Effect Combinations

10. Advanced Examples

🎯 Effect Overview

Effects define what your spell actually does when cast. Every spell must have at least one effect, but you can combine multiple effects for complex spells.

Basic Structure

effects:
  - type: "effect_type"
    # Effect-specific properties

Available Effect Types

• "damage" - Deal damage to targets

• "heal" - Restore health

• "teleport" - Move players to different locations

• "summon_creature" - Summon creatures

• "stat_mod" - Modify player statistics

• "custom" - Custom effects (advanced)

⚔️ Damage Effects

Deal damage to enemy targets.

Basic Damage

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

Properties

Property	Type	Required	Description
damage_min	number	✅	Minimum damage dealt
damage_max	number	✅	Maximum damage dealt
damage_type	string	⚠️	Damage type for flavor (fire, ice, lightning, etc.)

Damage Types

Common damage types (for flavor and future resistance systems):

• "fire" - Fire damage

• "ice" - Ice/cold damage

• "lightning" - Electrical damage

• "earth" - Earth/stone damage

• "magic" - Pure magical damage

• "dark" - Dark/shadow damage

• "light" - Light/holy damage

• "poison" - Poison damage

• "physical" - Physical damage

Examples

Basic Fire Spell:

effects:
  - type: "damage"
    damage_min: 15
    damage_max: 25
    damage_type: "fire"

High-Level Lightning Spell:

effects:
  - type: "damage"
    damage_min: 50
    damage_max: 80
    damage_type: "lightning"

Variable Damage Spell:

effects:
  - type: "damage"
    damage_min: 10
    damage_max: 100  # High variance for unpredictable damage
    damage_type: "chaos"

💚 Healing Effects

Restore health to the caster or other targets.

Basic Healing

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

Properties

Property	Type	Required	Description
heal_min	number	✅	Minimum health restored
heal_max	number	✅	Maximum health restored

Examples

Basic Heal Spell:

effects:
  - type: "heal"
    heal_min: 20
    heal_max: 30

Powerful Healing Spell:

effects:
  - type: "heal"
    heal_min: 80
    heal_max: 120

Consistent Healing:

effects:
  - type: "heal"
    heal_min: 50
    heal_max: 50  # Always heals exactly 50

🌀 Teleportation Effects

Move players to different locations.

Basic Teleportation

effects:
  - type: "teleport"
    teleport:
      # Choose one of the following modes

Teleport Modes

Element Room Teleport

Teleports to the player's elemental room:

effects:
  - type: "teleport"
    teleport:
      element_room: true

Specific Room Teleport

Teleports to a specific room (usually from spell arguments):

effects:
  - type: "teleport"
    teleport:
      target_room: ""  # Room ID from spell arguments

Random Room Teleport

Teleports to a random room within a range:

effects:
  - type: "teleport"
    teleport:
      random_room: true
      room_range: [1, 100]  # Random room between 1 and 100

Properties

Property	Type	Required	Description
element_room	boolean	⚠️	Teleport to player's element room
target_room	string	⚠️	Specific room ID (usually from args)
random_room	boolean	⚠️	Random teleportation
room_range	array	⚠️	[min, max] room range for random teleport

Examples

Recall Spell:

effects:
  - type: "teleport"
    teleport:
      element_room: true

Teleport Spell:

effects:
  - type: "teleport"
    teleport:
      target_room: ""  # Uses room from spell arguments

Random Teleport:

effects:
  - type: "teleport"
    teleport:
      random_room: true
      room_range: [1, 50]

👹 Summoning Effects

Summon creatures to assist the player.

Basic Summoning

effects:
  - type: "summon_creature"
    creature: "wolf"            # Creature name to summon
    duration: -1                # Duration in seconds (-1 = permanent)
    max_instances: 1            # Maximum active summons

Properties

Property	Type	Required	Description
creature	string	✅	Name of creature to summon
duration	number	⚠️	Duration in seconds (-1 for permanent)
max_instances	number	⚠️	Maximum active instances

Examples

Wolf Companion:

effects:
  - type: "summon_creature"
    creature: "wolf"
    duration: -1        # Permanent until killed
    max_instances: 1    # Only one wolf at a time

Temporary Elemental:

effects:
  - type: "summon_creature"
    creature: "fire elemental"
    duration: 300       # 5 minutes
    max_instances: 1

Multiple Minions:

effects:
  - type: "summon_creature"
    creature: "skeleton"
    duration: 600       # 10 minutes
    max_instances: 3    # Up to 3 skeletons

📊 Stat Modification Effects

Temporarily or permanently modify player statistics.

Basic Stat Modification

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 (optional)

Available Stats

Stat	Description
str	Strength
dex	Dexterity
int	Intelligence
ego	Ego
spd	Speed
hp	Maximum Hit Points
sp	Maximum Spell Points

Properties

Property	Type	Required	Description
stat_mod	object	✅	Map of stat changes
duration	number	⚠️	Duration in seconds (omit for permanent)

Examples

Strength Buff:

effects:
  - type: "stat_mod"
    stat_mod:
      str: 10
    duration: 600  # 10 minutes

Balanced Enhancement:

effects:
  - type: "stat_mod"
    stat_mod:
      str: 3
      dex: 3
      int: 3
    duration: 300  # 5 minutes

Permanent Stat Gain:

effects:
  - type: "stat_mod"
    stat_mod:
      int: 1  # Permanent intelligence increase
    # No duration = permanent

🔧 Custom Effects

For advanced spell behaviors that can't be achieved with standard effects.

Basic Custom Effect

effects:
  - type: "custom"
    custom:
      effect_name: "special_behavior"
      parameter1: "value1"
      parameter2: 42

Properties

Property	Type	Required	Description
custom	object	✅	Custom parameters for the effect

Note: Custom effects require implementation in the Go code. They're primarily used for unique spell behaviors that can't be achieved with standard effects.

🔗 Multiple Effects

Spells can have multiple effects that all trigger when the spell is cast.

Multiple Effect Example

effects:
  - type: "damage"
    damage_min: 30
    damage_max: 45
    damage_type: "fire"
  - type: "heal"
    heal_min: 10
    heal_max: 15
  - type: "stat_mod"
    stat_mod:
      str: 2
    duration: 60

This spell would:

1. Deal 30-45 fire damage to the target

2. Heal the caster for 10-15 HP

3. Increase the caster's strength by 2 for 1 minute

🎯 Effect Combinations

Vampiric Spell (Damage + Heal)

name: "Vampiric Drain"
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 25
    damage_max: 40
    damage_type: "dark"
  - type: "heal"
    heal_min: 15
    heal_max: 25

Berserker Spell (Damage + Stat Mod)

name: "Berserker Rage"
target_type: "self"
effects:
  - type: "stat_mod"
    stat_mod:
      str: 10
      dex: 5
      hp: -20  # Trade health for power
    duration: 120

Escape Spell (Damage + Teleport)

name: "Explosive Escape"
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 15
    damage_max: 25
    damage_type: "fire"
  - type: "teleport"
    teleport:
      element_room: true

Summoner's Blessing (Summon + Stat Mod)

name: "Call of the Wild"
target_type: "room"
effects:
  - type: "summon_creature"
    creature: "wolf"
    max_instances: 2
  - type: "stat_mod"
    stat_mod:
      dex: 5
      spd: 3
    duration: 300

🚀 Advanced Examples

Progressive Damage Spell

name: "Escalating Fireball"
description: "Damage increases with caster's spell level"
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 10  # Base damage
    damage_max: 20  # Will be modified by spell level in code
    damage_type: "fire"

Conditional Healing Spell

name: "Emergency Heal"
description: "Heals more when health is lower"
target_type: "self"
effects:
  - type: "heal"
    heal_min: 20
    heal_max: 80  # Actual amount determined by current health

Area Effect Simulation

name: "Chain Lightning"
description: "Hits multiple enemies in room"
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 25
    damage_max: 40
    damage_type: "lightning"
  # Additional logic in custom handler for multiple targets

Transformation Spell

name: "Dragon Form"
description: "Temporarily transforms the caster"
target_type: "self"
effects:
  - type: "stat_mod"
    stat_mod:
      str: 20
      hp: 100
      sp: -50  # Trade SP for physical power
    duration: 180

📋 Best Practices

Effect Design

• Start Simple: Begin with single effects, add complexity gradually

• Balance Power: More powerful effects should cost more SP or have longer cooldowns

• Consider Combinations: Think about how effects work together

• Test Thoroughly: Verify all effects work as intended

Performance

• Limit Multiple Effects: Too many effects can impact performance

• Reasonable Durations: Very long stat modifications can accumulate

• Instance Limits: Always set max_instances for summoning spells

Game Balance

• Damage Scaling: Higher level spells should have proportionally higher costs

• Healing Limits: Prevent healing from trivializing combat

• Stat Modifications: Temporary buffs should be meaningful but not overpowered

• Teleportation: Consider escape potential and balance accordingly

🎓 Conclusion

The spell effects system provides powerful building blocks for creating diverse and interesting spells. By combining different effect types, you can create unique magical experiences that enhance gameplay.

Next Steps

1. YAML Spell Tutorial - Learn to implement these effects

2. JSON Spell Guide - Advanced custom effects

3. Custom Spells Directory - See practical examples

4. Experiment - Try combining effects in creative ways!

Remember: The best spells are balanced, fun to use, and add meaningful choices to gameplay. Happy spell crafting! ✨