Spell Configuration

The section covers all base (general) spell options. For individual spell options visit the Spell List. Links to specific spell types:

• Instant spell
• Targeted spell
• Buff spell

Configuration files:

You can configure spells in spell configuration files. A spell file is any file in the MagicSpells plugin folder which has a name that starts with spell and ends with .yml (A YAML file, like spells-regular.yml). You can also put spell files in any folder in the MagicSpells folder which has a name that starts with spells (e.g. spellsFireMagic). Subfolders aren't supported.

You can also make something called "mini spell config", but it's highly restrictive. With this method, mini configs are loaded from any file in spellconfig and any folder within it. Mini config files are files where you can only store one spell per file. The file name dictates the spell name, but they have to end with .yml. Inside the mini config file, the spell configuration is not under a "spell name" configuration section, but top-level. Only spell configuration is loaded (no variable declaration, etc.).

General Spell Options:

Table of contents:

• Common Options
• Less-Common Options
• Targeting Options
• Cast Item Options
• Cast Time Options
• Message Options

---

Common Options:

Option	Description	Variable Type	Default Value
name	String that gets displayed as spell name when scrolling through a spell list. We call it the external spell name because when listing a spell with this option as a subspell, you wouldn't use this name, but the internal spell name. It supports color codes, but when trying to cast the spell using the cast command, you have to specify the spell in quotations, without color codes.	String	null
helper-spell	This option is documented here.	Boolean	false
always-granted	If enabled, all players will be taught this spell. For more about permissions check this page of our wiki.	Boolean	false
permission-name	It defaults to the internal spell name, but it can be changed to any string. Multiple spells can have the same permission-name. For more about permissions visit this page.	String	Internal spell name
incantations	A list of strings that would cast the spell when sent in chat by a player.	String list	null
incantations-regex	A list of regex patterns that would cast the spell when sent in chat by a player.	String list	null
description	A string that would be sent to chat when using the Help spell.	String	null
broadcast-range	Distance that spell messages are broadcast from the casting player to other players nearby. This option overwrites the default range specified in your general.yml file.	Integer	Defined in general.yml
effects	Configuration section for Spell Effects.	Map
cost	A string list of reagents required for the spell to be cast.	String List	null
cooldown	Defines in seconds and it is applied post cast. It can be modified using the cooldown modifier action and the Modify Cooldown spell. general.yml includes an option that defines whether the cooldown is reset on plugin reload. It can also be reset using the command /c resetcd	Float	0
server-cooldown	Same as above but the cooldown is applied to everyone on cast.	Float	0
shared-cooldowns	Applies cooldown to the spell and to all spells defined in this spell list.	String List	null
modifiers	View further documentation on this page.	String List	null
target-modifiers	Conditions for the target to consider for the target handler. View further documentation on this page.	String List	null
location-modifiers	Conditions for the target location to consider for the target handler. View further documentation on this page.	String List	null
variable-mods-cast	Variables are modified for the caster whether the spell failed to cast or not. Learn how to modify variables here.	String List	null
variable-mods-casted	Variables are modified only if the spell is casted successfully. Learn how to modify variables here.	String List	null
variable-mods-target	Can be used in targeted spells to change variable values of targets. Learn how to modify variables here.	String List	null
tags	This is a list of strings which some spells support to refer to a group of spells that are tagged with a specific tag. This is most commonly used in a Spell Filter which some spells like the Silence spell or No Magic Zones use. All spells have two predefined tags - in this example, we'll use .instant.BeamSpell: spell-class:com.nisovin.magicspells.spells.instant.BeamSpell, spell-package:com.nisovin.magicspells.spells(extra).	String List	null

Back To Top

---

Less-Common Options:

Option	Description	Variable Type	Default Value
debug	Enables spell-specific debug mode.	Boolean	false
aliases	A list of strings that can act as internal spell names. They cannot be used when specifying the spell as a subspell.	String List	null
experience	Amount of experience given to the caster upon successful cast.	Integer	0
spell-power-affects-range	Defines if the range is affected by Spell Power.	Boolean	false
ignore-global-cooldown	Ignores the cooldown set on server-cooldown.	Boolean	false
charges	(charges - 1) is the amount of times that this spell can still be cast when it is already on cooldown.	Integer	0
recharge-sound	Plays the sound by defined on charges decrement at a constant volume and pitch value of 1. This config does nothing in the dvz branch, since charges no longer decrement one at a time.	String	null
prerequisites	A list of spells that the caster is required to already know in order to learn this spell.	String List	null
replaces	Define a list of spells that this spell would replace upon when it gets learned by the caster.	String List	null
precludes	A list of spells the player can no longer learn if they know this spell.	String List	null
restrict-to-worlds	List of worlds this spell would be restricted to. It would not be castable in any other world.	String List	null
sound-on-cooldown	Plays the sound by defined if the spell is currently on cooldown, at a constant volume and pitch value of 1.	String	Defined in general.yml
sound-missing-reagents	Plays the sound by defined if the caster is missing the reagents required, at a constant volume and pitch value of 1.	String	Defined in general.yml
bypass-dippgen	Makes it so that the events that are called by this spell will be allowed by the DippGen permissions, even when the caster does not have the proper permissions.	Boolean	false

Back To Top

---

Targeting Options:

Option	Description	Variable Type	Default Value
min-range	Minimal range required for the targeting handler defined in block distance.	Integer	0
range	Same as above but it defines the maximal range.	Integer	20
obey-los	Defines whether the target handler should obey caster's line of sight.	Boolean	true
can-target	Overrides target-players and target-non-players. Follows valid target list format.	String List or String	null
target-players	Overriden by can-target. Defines if the target handler should target players.	Boolean	true
target-non-players	Overriden by can-target. Same as above for entities that aren't players.	Boolean	true
beneficial	Defines if this spell is beneficial to the scoreboard team the caster is in. If this is true, then the caster won't be able to target team members.	Boolean	false
target-damage-cause	Damage type string for fake damage cause that wouldn't actually be applied to the target. This option and the one below only exists to create a fake damage event for compatibility for other plugins.	String	null
target-damage-amount	The amount of fake damage to apply. See option above for more info.	Integer	0

Back To Top

---

Cast Item Options:

Option	Description	Variable Type	Default Value
cast-item	Item Type that would make the spell cast whenever it is left-clicked. This option accepts one item or multiple of them separated by commas. Learn more about cast items here.	String	null
cast-items	Same as above, but each Item Type is defined as an element of the string list.	String List	null
right-click-cast-item	Item Type that would make the spell cast whenever it is right-clicked. This option accepts one item or multiple of them separated by commas.	String	null
right-click-cast-items	Same as above, but each Item Type is defined as an element of the string list.	String List	null
consume-cast-item	Item Type that would make the spell cast whenever it is consumed. This option accepts one Item Type or multiple of them separated by commas. Examples of these items are potions, food, etc.	String	null
consume-cast-items	Same as above, but defined as a list of strings.	String List	null
cast-with-left-click	Defines whether the spell is castable on left click with the cast item thereof or on the bound item.	Boolean	Defined in general.yml
cast-with-right-click	Defines whether the spell is castable on right-click with the cast item thereof.	Boolean	Defined in general.yml
dance-cast-sequence	Series of characters that represent actions for the dance casting sequence. This isn't documented entirely because the feature is broken and unmaintained.	String	null
require-cast-item-on-command	When true the player must be holding the cast item even when casting with the /cast command.	Boolean	false
bindable	Defines whether this spell can be bound on an item. There is a difference between cast item methods and items spells have been bound on.	Boolean	true
bindable-items	A list of items this spell can be bound to using the Bind Spell. Leaving this option undefined makes the spell bindable to all types of items.	String List	null
spell-icon	An item that represents this spell for the Spell Icon feature. Format: `item:data\	name`.	String

Back To Top

---

Cast Time Options:

Option	Description	Variable Type	Default Value
cast-time	Warm-up time defined in server ticks before the spell casts successfully. Effect position that can be used at the start of warm-up time is startcast. Leave at 0 for an instant cast.	Integer	0
interrupt-on-move	If cast-time is defined above 0, this interrupts the cast-time for the spell when the player moves. The spell then fails to cast.	Boolean	true
interrupt-on-teleport	Same as above, but this listens for any kind of teleport event to cancel the warm-up.	Boolean	true
interrupt-on-damage	Same as above, but this listens for when the caster receives damage to cancel the warm-up.	Boolean	false
interrupt-on-cast	Same as above, but this listens for whenever a spell is casted to cancel warm-up.	Boolean	false
spell-on-interrupt	Spell to cast if cast-time fails for the above mentioned reasons.	String	null

Back To Top

---

Message Options:

These messages can use of the MiniMessage format.

Option	Description	Default Value
str-cost	String that gets displayed under Cost on the Help spell.	String
str-cast-self	String sent to the caster on the successful cast.	String
str-cast-others	String sent to the other players nearby. The range is defined by the broadcast-range option which, if not defined, will assume the value specified in general.yml instead.	null
str-on-cooldown	String sent to the caster if the spell is currently on cooldown.	String
str-missing-reagents	String sent to the caster if the caster does not have the reagents required for the spell to cast successfully.	Defined in general.yml
str-cant-cast	String sent to the caster if the spell cannot be casted (e.g. if no target is found, etc.)	Defined in general.yml
str-cant-bind	String sent to the caster if the spell is not bindable (e.g. if bindable is defined as false)	null
str-wrong-world	String sent to the caster if the world the caster is in is not defined in restrict-to-worlds.	Defined in general.yml
str-wrong-cast-item	String sent to the caster if require-cast-item-on-command is set to true and they are not holding the cast item.	Value of str-cant-cast
str-cast-start	String sent to the caster on the successful cast.	null
str-interrupted	String sent to the caster if cast-time has been interrupted.	null
str-modifier-failed	String sent to the caster when but a modifier that was specified failed.	null
str-on-teach	When a spell with this option set is taught with a TeachSpell, The str-on-teach is sent instead of the TeachSpell's str-cast-target.	null

Back To Top