Spell Configuration - TheComputerGeek2/MagicSpells GitHub Wiki

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.nisovin.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:

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 cast item cooldown set by global-cooldown in general.yml. 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

Note

Anyone can edit the wiki so if you feel like you need to edit or add something, or if you find some mistakes, please do help us out. We would appreciate it! ❤️

⚠️ **GitHub.com Fallback** ⚠️