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 & 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.

Mini Spell Files:

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.).

Default Options:

Warning

The "Defaults" file is available since 4.0 Beta 13.

Inside the defaults.yml file you can override the hardcoded spell default option values. The spell should be defined as a configuration section, the spell class is the section key. The spell class is the Java class' fully qualified class name - if the class is from MS, then com.nisivin.spells may be omitted. Example:

".instant.LeapSpell":
    rotation: 0
    upward-velocity: 15
    forward-velocity: 40
    client-only: false
    cancel-damage: true
    add-velocity-instead: false
    power-affects-velocity: true

General Spell Options:

Since 4.0 Beta 13 some of these options support dynamic values through numeric or string expressions.

Table of contents:

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

---

Common Options:

Option	Description	Type	Default	Supports expressions
spell-class	Aside from these general options every class has its options - you can find them along with their class name in the Spell List. The spell class is the Java class' fully qualified class name - if the class is from MS, then com.nisivin.spells may be omitted.	String		false
name	String that gets displayed as a 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 sub-spell, 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		false
helper-spell	This option is documented here.	Boolean	false	false
always-granted	If enabled, all players will be taught this spell. For more about permissions check this page of our wiki.	Boolean	false	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	Spell name	false
incantations	A list of strings that would cast the spell when sent in chat by a player.	String List		false
description	A string that would be sent to chat when using the Help spell.	String		false
broadcast-range	Distance that spells 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	true
effects	Configuration section for Spell Effects.	Config section		false
cost	A string list of reagents required for the spell to be cast.	String List		false
str-cost	String that gets displayed under Cost on the Help spell.	Rich Text		true
str-missing-reagents	String sent to the caster if the caster does not have the reagents required for the spell to cast successfully.	Rich Text	Defined in general.yml	true
cooldown	Defines in seconds and it is applied post cast. You can even apply a random cooldown from a range using the format: min-max (e.g. 0-5). 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 /ms resetcd.	Float	0	false
server-cooldown	Same as above but the cooldown is applied to everyone on the cast. Doesn't support ranged cooldown.	Float	0	false
shared-cooldowns	Applies a cooldown for each entry in the list. Entries are formatted as <spell name> <cooldown>.	String List		false
str-on-cooldown	Additional placeholders: - %s: Spell's name. - %c: Spell's rounded cooldown.	Rich Text	Defined in general.yml	true
modifiers	View further documentation on this page.	String List		false
target-modifiers	Conditions for the target to consider for the target handler. View further documentation on this page.	String List		false
str-modifier-failed	String sent to the caster when but a modifier that was specified failed.	Rich Text		true
location-modifiers	Conditions for the target location to consider for the target handler. View further documentation on this page.	String List		false
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		false
variable-mods-casted	Variables are modified only if the spell is cast successfully. Learn how to modify variables here.	String List		false
variable-mods-target	Can be used in targeted spells to change variable values of targets. Learn how to modify variables here.	String List		false
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		false

Back To Top

---

Less-Common Options:

Option	Description	Type	Default	Supports expressions
debug	Enables spell-specific debug mode.	Boolean	false	false
aliases	A list of strings that can act as internal spell names. They cannot be used when specifying the spell as a sub-spell.	String List		false
experience	Amount of experience given to the caster upon successful cast.	Integer	0	true
ignore-global-cooldown	Ignores the cooldown set on server-cooldown.	Boolean	false	false
charges	Defines how many times this spell can be cast before the cooldown is applied.	Integer	0	false
recharge-sound	Plays the sound by defined on charges decrement at a constant volume and pitch value of 1.	String		false
prerequisites	A list of spells that the caster is required to already know to learn this spell.	String List		false
replaces	Define a list of spells that this spell would replace upon when it gets learned by the caster.	String List		false
precludes	A list of spells the player can no longer learn if they know this spell.	String List		false
restrict-to-worlds	List of worlds this spell would be restricted to. It would not be castable in any other world.	String List		false
sound-on-cooldown	Plays the sound by defining if the spell is currently on cooldown, at a constant volume and pitch value of 1.	String	Defined in general.yml	false
sound-missing-reagents	Plays the sound by defining if the caster is missing the reagents required, at a constant volume and pitch value of 1.	String	Defined in general.yml	false

Back To Top

---

Targeting Options:

Option	Description	Type	Default	Supports expressions
min-range	Minimal range required for the targeting handler defined in block distance.	Integer	0	true
range	Same as above but it defines the maximal range.	Integer	20	true
spell-power-affects-range	Defines if the range is affected by Spell Power.	Boolean	false	true
obey-los	Defines whether the target handler should obey the caster's line of sight.	Boolean	true	false
can-target	Overrides target-players and target-non-players. Follows valid target list format.	String List or String		false
los-transparent-blocks	A list of blocks that count as "transparent" in line-of-sight dependent spells, such as targeted spells. It also determines whether beam and particle projectiles (among others) will go through the blocks listed.	String List	Defined in general.yml.	false
los-ray-size	Since 4.0 Beta 14. Determines the size of the ray used for checking the line of sight to entities when retrieving an entity target.	Double	Defined in general.yml.	true
los-ignore-passable-blocks	Since 4.0 Beta 14. When true, passable blocks (blocks that do not have any colliding parts that stop movement) are ignored for entity/location targeting. For example, air and tall grass are passable.	Boolean	Defined in general.yml.	true
los-fluid-collision-mode	Since 4.0 Beta 14. Determines whether or not fluids are collided with when retrieving entity/location targets.	Fluid Collision Mode	Defined in general.yml.	true
target-self	This isn't checked as consistently, so use can-target: self instead. Forces the targeting handler to target the caster instead.	Boolean	false	true
target-players	Overridden by can-target. Defines if the target handler should target players.	Boolean	true	false
target-non-players	Overridden by can-target. Same as above for entities that aren't players.	Boolean	true	false
beneficial	Defines if this spell is beneficial to the scoreboard team the caster is in. If the caster is targeting an enemy team, the spell will only target them if the spell is not beneficial. If the caster is targeting an allied team, they will only be able to do so if friendly fire is allowed in the team or if the spell is beneficial.	Boolean	false	false
target-damage-cause	Damage type string for fake damage cause that wouldn't be applied to the target. This option and the one below only exist to create a fake damage event for compatibility with other plugins.	String		false
target-damage-amount	The amount of fake damage to apply. See the option above for more info.	Integer	0	false
always-activate	Defines if the spell's reagents will be charged and the cooldown activated even if the spell fails to find a valid target.	Boolean	false	true
play-fizzle-sound	Defines if the spell should play the fire extinguished sound if the spell fails to find a valid target.	Boolean	false	true
spell-on-fail	Sub-spell to cast if the spell fails to cast (e.g. if it fails to find a target).	String		false
str-cast-target	String to send to the target if the target is a player.	Rich Text		true
str-no-target	String to send to the caster if the target handler fails to find a valid target.	Rich Text		true

Back To Top

---

Cast Item Options:

Option	Description	Type	Supports expressions
cast-item	Casts the spell whenever it is left-clicked.	Cast Item	false
cast-items	Same as above.	Cast Item List	false
left-click-cast-item		Cast Item	false
left-click-cast-items		Cast Item List	false
right-click-cast-item		Cast Item	false
right-click-cast-items		Cast Item List	false
consume-cast-item	Casts the spell whenever it is consumed. Examples of these items are potions, food, etc.	Cast Item	false
consume-cast-items	Same as above.	Cast Item List	false
cast-with-left-click	Defines whether the spell is castable on left click with the cast item thereof or on the bound item. Default value is defined in general.yml.	Boolean	false
cast-with-right-click	Defines whether the spell is castable on right-click with the cast item thereof. Default value is defined in general.yml.	Boolean	false
dance-cast-sequence	A series of characters that represent actions for the dance-casting sequence. This isn't documented entirely because the feature is broken and unmaintained.	String	false
require-cast-item-on-command	When true the player must be holding the cast item even when casting with the /cast command.	Boolean (def: false)	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 (def: true)	false
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.	Cast Item List	false
str-cant-bind	String sent to the caster if the spell is not bindable (e.g. if bindable is defined as false)	Rich Text	true
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. Defaults to the value of str-cant-cast.	Rich Text	true
spell-icon	An item that represents this spell for the Spell Icon feature.	Magic Item String	false

Back To Top

---

Cast Time Options:

Option	Description	Type	Default	Supports expressions
cast-time	Warm-up time defined in server ticks before the spell casts successfully. The effect position that can be used at the start of warm-up time is startcast. Leave at 0 for an instant cast.	Integer	0	true
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	true
interrupt-on-teleport	Same as above, but this listens for any kind of teleport event to cancel the warm-up.	Boolean	true	true
interrupt-on-damage	Same as above, but this listens for when the caster receives damage to cancel the warm-up.	Boolean	false	true
interrupt-on-cast	Same as above, but this listens for whenever a spell is cast, that is not a Passive spell, to cancel cast-time.	Boolean	true	true
interrupt-filter	Since 4.0 Beta 14. Spell Filter for interrupt-on-cast. While empty, all spells interrupt cast-time except Passive spells.	Spell Filter Config		false
spell-on-interrupt	Spell to cast if cast-time fails for the above-mentioned reasons.	String		false
str-interrupted	String sent to the caster if cast-time has been interrupted.	Rich Text		true

Back To Top

---

Other Message Options:

All options are of type Rich Text.

Option	Description
str-cast-self	String sent to the caster on the successful cast.
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.
str-cant-cast	String sent to the caster if the spell cannot be cast (e.g. if no target is found, etc.). Default value is defined in general.yml.
str-wrong-world	String sent to the caster if the world the caster is in is not defined in restrict-to-worlds. The default value is defined in general.yml.
str-cast-start	String sent to the caster on the successful cast.
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.
str-cast-cancelled	Sent whenever a spell cast is cancelled, and is mostly helpful for debugging.

Back To Top