Magic Items

Magic Items can be defined in any spell file, but they can also be defined in general.yml. This lets you use the same item in multiple places throughout the plugin's configuration without having to define the full Cast Item format every time.

Spigot's ItemStack Serialization Format

If you want to use Spigot's ItemStack serialization then the specification can be found here. You can also generate magic items as ItemStack objects from hand held items using the Item Serialize Spell.

The configuration will go like this:

magic-items:
    <internal name>:
        type: "external::spigot"
        data:
            # This is where the options go.

Otherwise, if you want to define general magic items the options for it can be found here and the configuration would look like this instead:

magic-items:
    <internal name>:
        # This is where the options go.

You can give yourself magic items using the /ms magicitem command.

Formatting

Certain options support formatting codes, using the format &<formatting code>. The formatting codes can be found here. Hex color codes are also supported, by substituting #RRGGBB for <formatting code>. Examples: &c, &#66ff00.

When options specify a format, arguments indicated with angle brackets (<>) are required. Optional arguments are indicated with square brackets ([]); when specifying an optional argument, all arguments prior to it must be specified.

General Configuration Options

Option	Description	Variable Type	Default
type	Material name, as listed here. As mentioned above, type can also be the string "external::spigot" to serialise the item from an ItemStack YAML object defined in data. This option is required either way.	String	-
name	The display name for the item. Supports color codes. You can't parse variables using the %var parameters on the item directly, but if this item is an item option on a Menu Spell, they will be parsed.	String	-
amount	The amount of the item.	Integer	1
lore	A list of strings representing the item's lore. Its capabilities are the same as above.	List	-
enchants	A list of strings representing enchantments. Format: <enchantment name> <level>.	List	-
custom-model-data	The item's custom model data.	Integer	0
hide-tooltip	Defines whether all of the item's flags should be hidden.	Boolean	false
fake-glint	Applies a fake enchantment glint to the item if it has no enchantments.	Boolean	false
repair-cost	The item's repair cost.	Integer	0
unbreakable	Whether the item is unbreakable.	Boolean	false
attributes	A list of strings representing attributes. Format: <attribute name> <value> [operation] [slot]. Attributes are as listed here. Operations are as listed here, and are by default add_number. Slots are as listed here, and by default applies the attribute modifier to all slot types. Setting the UUID of the attribute modifier is not currently supported, but can be done using Spigot's ItemStack serialization format.	List	-
ignored-attributes	As defined here. Can also be defined when using Spigot's ItemStack serialization format.	List	-
blacklisted-attributes	As defined here. Can also be defined when using Spigot's ItemStack serialization format.	List	-

Ignored Attributes

Magic items can sometimes be used as item filters, such as in modifiers conditions and passive triggers. Options that have been explicitly defined (and in the case of lists, not empty) are used when comparing an item matches a magic item. If the item has an attribute that differs from what is defined in an option, the item does not match the magic item. Options listed in ignored-attributes are ignored in this comparison. For example:

broken-sword:
    type: "stone_sword"
    durability: 20

Would match any stone sword with 20 durability damage, ignoring any other attribute. However,

broken-sword:
    type: "stone_sword"
    durability: 20
    ignored-attributes:
        - DURABILITY

Would match any stone sword, regardless of durability damage.

Blacklisted Attributes

Similar to ignored-attributes, except that any option defined in blacklisted-attributes is not allowed to exist on an item when it is compared to a magic item. For example:

redstone-cost:
    type: "redstone"

Would match any redstone item, regardless of name, lore or enchantments. However,

redstone-cost:
    type: "redstone"
    blacklisted-attributes:
        - name
        - lore
        - enchants

Would only match redstone items that do not have a custom name, lore or enchantments.

Specific Configuration Options

Items with Durability

Option	Description	Variable Type	Default
durability	The item's durability damage; items with full durability have a damage of 0.	Integer	0

magic-items:
    dull-blade:
        type: "stone_sword"
        name: "&8Dull Blade"
        durability: 20

Potions

Option	Description	Variable Type	Default
potion-effects	A string list of status effects from. Format: <potion effect type> (level) [duration] [ambient]. Duration is in ticks (600 by default). A list of potion effect types can be found here.	List	-
potion-color	Color (hex code) of the potion.	String	-
potion-data	Base potion data of the potion. Format: <potion type> [extended/upgraded]. A list of potion types can be found here.	String	-

magic-items:
    healing-potion:
        type: "splash_potion"
        name: "&#66ff00Healing Potion"
        potion-color: "66ff00"
        potion-effects:
            - "regeneration 1 100 false"
            - "instant_health 1 0"

Suspicious Stew

Option	Description	Variable Type	Default
potion-effects	Potion effects of the stew. Format: <potion effect> [duration]. Duration is in ticks (600 by default). A list of effects can be found here.	List	-

magic-items:
    healing-stew:
        type: "suspicious_stew"
        name: "&aHealing Stew"
        potion-effects:
            - "regeneration 100"

Firework Stars

Option	Description	Variable Type	Default
firework-type	Type of the firework, as defined here.	String	-
trail	Should the firework have a trail?	Boolean	false
flicker	Should the firework flicker?	Boolean	false
colors	Colors (hex codes) of the firework, separated by a comma.	String	-
fade-colors	Fade colors (hex codes) of the firework, separated by a comma.	String	-

magic-items:
    sun-firework-star:
        type: "firework_star"
        name: "&eSun Firework Star"
        trail: true
        flicker: false
        colors: "FFE484, FFCC33, FC9601"
        fade-colors: "B72C3C, D14009"

Fireworks

Option	Description	Variable Type	Default
firework-effects	Firework effects of the rocket. Format: <type> <trail> <flicker> <colors> [fade-colors].	List	-
power	Power of the firework rocket (0 - 128).	Integer	0

magic-items:
    sun-firework:
        type: "firework_rocket"
        name: "&rFirework - &ESun"
        power: 2
        firework-effects:
            - "ball_large true false FFE484,FFCC33,FC9601 B72C3C,D14009"
            - "ball false false B72C3C,D14009"

Leather Armor

Option	Description	Variable Type	Default
color	Color (hex code) of the leather armor.	String	-

magic-items:
    bloodied-vest:
        type: "leather_chestplate"
        name: "&#8A0303Bloodied Vest"
        color: "8A0303"

Skulls

Option	Description	Variable Type	Default
skull-owner	The name of the skull's owner. Must be defined if uuid is not defined for texture to apply.	String	-
uuid	The UUID of the skull owner. Must be defined if skull-owner is not defined for texture to apply.	String	-
texture	The skull's texture.	String	-
signature	The signature for the skull's texture.	String	-

magic-items:
    jeb-head:
        type: "player_head"
        skull-owner: "jeb_"
        uuid: "853c80ef-3c37-49fd-aa49-938b674adae6"
        texture: "ewogICJ0aW1lc3RhbXAiIDogMTYxMzkzOTQ5NTg2NCwKICAicHJvZmlsZUlkIiA6ICI4NTNjODBlZjNjMzc0OWZkYWE0OTkzOGI2NzRhZGFlNiIsCiAgInByb2ZpbGVOYW1lIiA6ICJqZWJfIiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzdmZDliYTQyYTdjODFlZWVhMjJmMTUyNDI3MWFlODVhOGUwNDVjZTBhZjVhNmFlMTZjNjQwNmFlOTE3ZTY4YjUiCiAgICB9LAogICAgIkNBUEUiIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzU3ODZmZTk5YmUzNzdkZmI2ODU4ODU5ZjkyNmM0ZGJjOTk1NzUxZTkxY2VlMzczNDY4YzVmYmY0ODY1ZTcxNTEiCiAgICB9CiAgfQp9"
        signature: "XWHSTMXVrh2GWxJx8PX0kedO4t7SS6zpg7aTcslbo4WzKXufuE8DiO61sQm0LbQhMmrP9Zw9jCbkKtYtsruddC+jc5FYbHbpU9+dXLSJ2rWfAHRDbcw6IfrjyAEYPB3IyhoCPGaOitQrGoWIINvdYiipXbPOA3KuOBYdvsLSu30QTtVdujQ/RMCXrA6SIk1YeoVhsztjbWNnzevTe/C2WTSyVFYHNm618HudZbNM2qbDLwOMu0Ddzla+pf9roT3V0jZstStldIptZMOooIUmr57MfIZ6MQ8/76ZSBeaM/KDZu4w3VmyN18sTY+jDWzVm7onw+O3H3FRmJe0oWAofqoA3CoYH52YrkYSsCRo4CDojcX8SXv9DzsudAPnSL3gZ69LKP8VCqRY75TroclFMmptseS57yV9aJCAlFsccstveilefpCSUrVUoM8g/gzhuZwrQCBsVKlzVEQAcwvagxckHj2VqFHBrLoKrJDlG1ZFfHw9qMYvRkEnpHjlvV/CaVchWTeJ4MLt7xuGQM4CbldQELwl6ApwvWNvKLn3uPMJmyrAci3bZHIao9txXbRyn5M2EYMw1ftjDhAqrY982LkDK1WBcFgzTvzhlvBiLHbwLAjGUmdpBYKHfj2c4YPRz8wpnlvhwup81nDta90Lk+a6M1wXpj/V14FxNdWmypww="

Written Books

Option	Description	Variable Type	Default
title	Book title.	String	-
author	Book author.	String	-
pages	A list of strings representing the pages of the book. Line breaks can be represented with \n. Supports multi-line strings, a built in feature of YAML, as mentioned here).	List	-

magic-items:
    rule-book:
        type: "written_book"
        title: "&4Rule Book"
        author: "&cAdmin"
        pages:
          - "Read the rules, they are important."
          - "This is page two. It has more rules on it."
          - |
            This is page three.
            It has multiple lines.

            Here's another line.

Banners

Option	Description	Variable Type	Default
patterns	A list of strings representing banner patterns. Format: <banner pattern> <dye color>. Click here for valid banner patterns, and here for valid dye colors. Shorthand banner pattern identifiers are also supported, as listed here, under the section "Code".	List	-

magic-items:
    pillager-banner:
        type: "white_banner"
        patterns:
            - "rhombus_middle cyan"
            - "stripe_bottom light_gray"
            - "stripe_center gray"
            - "stripe_middle black"
            - "half_horizontal light_gray"
            - "circle_middle light_gray"
            - "border black"
    pillager-banner-short:
        type: "white_banner"
        patterns:
            - "mr cyan"
            - "bs light_gray"
            - "cs gray"
            - "ms black"
            - "hh light_gray"
            - "mc light_gray"
            - "bo black"

Uses

In most cases where magic items can be specified, usage of the inline Cast Item format is also supported. Some major uses of magic items are shown below.

Reagent Costs

magic-items:
    mana-crystal:
        type: "redstone"
        name: "&bMana Crystal"
        lore:
            - "&7Required when casting magic."

heal:
    spell-class: ".targeted.PotionEffectSpell"
    name: "Heal"
    target-self: true
    strength: 1
    duration: 1
    type: "instant_health"
    cost:
        - "mana-crystal 1"

Modifiers

Certain modifiers conditions take magic items as arguments.

magic-items:
    essense-stick:
        type: "stick"
        name: "&aEssense Stick"

lift:
    spell-class: ".targeted.PotionEffectSpell"
    name: "Lift"
    modifiers:
        - "holdingprecise essense-stick required"
    target-self: true
    duration: 200
    strength: 1
    type: "jump_boost"

Passive Triggers

Certain passive triggers take magic items as arguments.

magic-items:
    heavy-sword:
        type: "wooden_sword"
        name: "&#99876b&lHeavy &#99876bSword"

heavy_damage:
    spell-class: ".PassiveSpell"
    triggers:
        - givedamage heavy-sword
    spells:
        - heavy_pain(mode=full)

heavy_pain:
    spell-class: ".targeted.PainSpell"
    damage: 10
    str-cast-target: "&cYou've been heavily damaged!"

Cast Items

magic-items:
    booster-wand:
        type: "stick"
        name: "&eBooster &6Wand"
        lore:
            - "&7Grants the user the ability to boost."

boost:
    spell-class: ".targeted.PotionEffectSpell"
    name: "Boost"
    cast-item: "booster-wand"
    target-self: true
    duration: 200
    strength: 1
    type: "speed"

magic-items:
    magic-wand:
        type: "stick"
        name: "&cMagical &6Wand"
        lore:
          - "&7Right click to cast magic."

regen_magic:
    spell-class: ".targeted.PotionEffectSpell"
    right-click-cast-item: "magic-wand"
    target-self: true
    duration: 200
    strength: 1
    type: "regeneration"