Spell Configuration Reference

Complete reference for all spell configuration properties in OpenRoads.

📚 Table of Contents

1. Configuration Overview

2. Required Properties

3. Optional Properties

4. Messages Configuration

5. Restrictions Configuration

6. Property Validation

7. Default Values

8. Examples by Category

🎯 Configuration Overview

Every spell is defined by a set of properties that control its behavior, requirements, and effects. This reference covers all available properties and their usage.

Basic Structure

name: "Spell Name"                    # Required
description: "What the spell does"    # Required
element_required: "fire"              # Optional
min_spell_level: 10                   # Optional
min_phys_level: 0                     # Optional
sp_cost: 15                           # Required
cast_time: 0                          # Optional
cooldown: 3                           # Optional
target_type: "enemy"                  # Required
required_items: []                    # Optional
effects: []                           # Required
messages: {}                          # Optional
restrictions: {}                      # Optional
custom_handler: ""                    # Optional (JSON only)

✅ Required Properties

These properties must be present in every spell definition.

name (string)

The display name of the spell as shown to players.

name: "Fireball"

Rules:

• Must be a non-empty string

• Should be descriptive and unique

• Used in spell lists and messages

• Can contain spaces and special characters

description (string)

A brief description of what the spell does.

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

Rules:

• Must be a non-empty string

• Should clearly explain the spell's purpose

• Shown in spell information displays

• Keep under 100 characters for readability

sp_cost (number)

The spell point cost to cast the spell.

sp_cost: 15

Rules:

• Must be a positive integer

• Should scale with spell power

• Consider player SP pools when setting

• Minimum value: 1

target_type (string)

Defines what the spell targets.

target_type: "enemy"

Valid Values:

• "self" - Targets the caster only

• "enemy" - Requires an enemy target

• "player" - Requires a player target

• "room" - Requires a room ID

• "none" - No target required

effects (array)

List of effects the spell produces when cast.

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

Rules:

• Must contain at least one effect

• Each effect must have a valid type

• See Spell Effects Reference for details

🔧 Optional Properties

These properties have default values and can be omitted.

element_required (string)

Restricts the spell to specific elemental mages.

element_required: "fire"

Valid Values:

• "fire" - Fire mages only

• "water" - Water mages only

• "air" - Air mages only

• "earth" - Earth mages only

• "" or omitted - Any element can cast

min_spell_level (number)

Minimum spell level required to cast.

min_spell_level: 10

Rules:

• Default: 0 (no requirement)

• Must be non-negative integer

• Should scale with spell power

• Consider progression balance

min_phys_level (number)

Minimum physical level required to cast.

min_phys_level: 5

Rules:

• Default: 0 (no requirement)

• Must be non-negative integer

• Rarely used (most spells use spell level)

• Useful for hybrid combat/magic spells

cast_time (number)

Casting time in seconds before the spell takes effect.

cast_time: 3

Rules:

• Default: 0 (instant cast)

• Must be non-negative integer

• Longer cast times should mean more powerful spells

• Can be interrupted by damage or movement

cooldown (number)

Cooldown time in seconds before the spell can be cast again.

cooldown: 10

Rules:

• Default: 0 (no cooldown)

• Must be non-negative integer

• Should scale with spell power

• Prevents spell spam

required_items (array)

List of items that must be in the caster's inventory.

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

Rules:

• Default: [] (no items required)

• Items are consumed on successful cast

• Item names must match exactly

• Case-sensitive matching

custom_handler (string, JSON only)

Name of the Go function to handle custom spell logic.

"custom_handler": "cast_servant"

Rules:

• Only available in JSON spell definitions

• Must match a function in the Go code

• Used for complex spells that can't use standard effects

• See JSON Spell Guide for details

💬 Messages Configuration

Customize messages for different spell casting 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_cast: "%s begins casting a spell!"
  broadcast_effect: "%s casts a powerful spell!"

Message Properties

Property	Description	Placeholders
success	Successful spell cast	%s (target), %d (numbers)
miss	Spell effect failed	%s (target)
failure_element	Wrong element	None
failure_level	Insufficient level	%d (required), %d (current)
failure_sp	Insufficient SP	%d (needed), %d (have)
failure_target	Invalid/missing target	None
failure_items	Missing required items	%s (item name)
failure_cooldown	Spell on cooldown	None
cast_start	Cast time begins	None
cast_complete	Cast time finishes	None
cast_interrupt	Cast interrupted	None
broadcast_cast	Others see casting start	%s (caster name)
broadcast_effect	Others see spell effect	%s (caster name)

Message Placeholders

• %s - String values (names, items, etc.)

• %d - Numeric values (levels, damage, SP, etc.)

🚫 Restrictions Configuration

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

Rules:

• Cannot have both combat_only and non_combat_only true

• Default: false for both (can cast anytime)

Instance Restrictions

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

Rules:

• Default: 0 (no limit)

• Applies to summoning spells and persistent effects

• Prevents spell stacking abuse

Location Restrictions

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

Rules:

• Default: [] (no restrictions)

• Room IDs must be strings

• required_rooms and forbidden_rooms can both be used

• If required_rooms is set, spell can only be cast in those rooms

Element Restrictions

restrictions:
  required_element: true   # Must match player's element

Rules:

• Default: false

• When true, element_required must be set

• Stricter than just element_required

✅ Property Validation

The spell system validates all properties when loading spells.

Validation Rules

String Properties

• Must not be empty (except element_required)

• Must be valid UTF-8

• Length limits apply to some fields

Numeric Properties

• Must be non-negative integers

• SP cost must be at least 1

• Level requirements cannot exceed reasonable limits

Array Properties

• Can be empty

• String arrays must contain valid strings

• Effect arrays must contain valid effect objects

Enum Properties

• target_type must be one of the valid values

• element_required must be valid element or empty

Validation Errors

Common validation errors and solutions:

Invalid target_type:

# Wrong:
target_type: "invalid"

# Right:
target_type: "enemy"

Negative values:

# Wrong:
sp_cost: -5

# Right:
sp_cost: 5

Empty required fields:

# Wrong:
name: ""

# Right:
name: "Spell Name"

📊 Default Values

Properties that are omitted use these default values:

Property	Default Value	Notes
element_required	""	No element restriction
min_spell_level	0	No level requirement
min_phys_level	0	No physical level requirement
cast_time	0	Instant cast
cooldown	0	No cooldown
required_items	[]	No items required
messages	{}	Default messages used
restrictions	{}	No restrictions

📋 Examples by Category

Beginner Spell

name: "Magic Missile"
description: "Basic magical projectile"
sp_cost: 5
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 8
    damage_max: 12
    damage_type: "magic"

Intermediate Spell

name: "Fireball"
description: "Hurls a ball of fire"
element_required: "fire"
min_spell_level: 10
sp_cost: 15
cooldown: 3
target_type: "enemy"
effects:
  - type: "damage"
    damage_min: 20
    damage_max: 35
    damage_type: "fire"
messages:
  success: "Your fireball engulfs %s in flames!"
  failure_element: "Only fire mages can cast fireball."

Advanced Spell

name: "Meteor"
description: "Calls down a devastating meteor"
element_required: "fire"
min_spell_level: 25
sp_cost: 50
cast_time: 5
cooldown: 120
target_type: "enemy"
required_items:
  - "meteor stone"
effects:
  - type: "damage"
    damage_min: 80
    damage_max: 120
    damage_type: "fire"
messages:
  success: "A massive meteor crashes down upon %s!"
  failure_items: "You need %s to call down a meteor."
  cast_start: "You raise your hands to the sky..."
  cast_complete: "The sky darkens as a meteor streaks down!"
restrictions:
  max_instances: 1

Utility Spell

name: "Recall"
description: "Return to your elemental sanctuary"
min_spell_level: 3
sp_cost: 20
cast_time: 5
cooldown: 30
target_type: "self"
effects:
  - type: "teleport"
    teleport:
      element_room: true
messages:
  cast_start: "You begin the recall incantation..."
  success: "You recall to your elemental sanctuary!"
restrictions:
  non_combat_only: true

Support Spell

name: "Bless"
description: "Enhances the caster's abilities"
min_spell_level: 12
sp_cost: 25
cast_time: 2
cooldown: 300
target_type: "self"
effects:
  - type: "stat_mod"
    stat_mod:
      str: 3
      dex: 3
      int: 3
    duration: 600
messages:
  success: "Divine energy flows through you!"
  cast_start: "You invoke divine blessing..."
restrictions:
  non_combat_only: true
  max_instances: 1

🎓 Conclusion

Understanding spell configuration is essential for creating balanced, functional spells. Use this reference to ensure your spells have all required properties and follow best practices.

Next Steps

1. YAML Spell Tutorial - Learn to create spells

2. Spell Effects Reference - Understand effects

3. Custom Spells Directory - See examples

4. Practice - Create your own spells using this reference!

Remember: Well-configured spells enhance gameplay and provide clear feedback to players. Take time to craft good messages and appropriate restrictions! ✨