Repository navigation
Creating An Enchantment
An enchantment is one file in the enchants folder, such as enchants/lifesteal.yml. The name of the file (without .yml) is the id. For lifesteal.yml, the full id is metaenchants:lifesteal.
Here is a complete enchantment:
name: "Lifesteal"
description:
- "<gray>Heal a little with every hit."
rarity: epic
max-level: 3
supported-items: ["#minecraft:swords", "#minecraft:axes"]
slots: [mainhand]
incompatible: ["minecraft:sharpness"]
triggers:
drain:
on: attack
do:
- heal:
amount: "min({damage} * 0.05 * {level}, 3)"
entity: "{player}"Only supported-items is truly required, but you will want most of the rest. Let's go through every option.
| Option | What it is | Default | Needs |
|---|---|---|---|
name |
The name players see. | The id with a capital letter. | Restart |
description |
Lines shown in the tooltip and the menu, optionally per level. | None. | Reload |
rarity |
The rarity (color and defaults). | The first one in rarities.yml. |
Restart |
max-level |
The highest normal level. | 1 |
Restart |
weight |
How common it is. | From the rarity. | Restart |
anvil-cost |
How costly it is at the anvil. | From the rarity. | Restart |
min-cost and max-cost |
Levels at the enchanting table. | From the rarity. | Restart |
supported-items |
Items that accept it. Required. | Restart | |
primary-items |
Items that get it from the table. | Same as supported-items. |
Restart |
slots |
Where it must be worn or held to work. | [mainhand] |
Restart |
incompatible |
Enchantments it cannot share an item with. | None. | Restart |
obtain |
Where it can be found naturally, and how often. | From the rarity. | Restart (chances: reload) |
treasure |
Treasure enchantments never appear in the table. | From the rarity. | Restart |
curse |
Marks it as a curse. | false |
Restart |
stack |
What happens with several items. | highest |
Restart |
activation |
Which item counts. | equipment |
Reload |
type |
Its type, for limits per item and the grindstone. | The first type. | Reload |
requires |
Enchantments the item must already have. | None. | Reload |
replaces |
Enchantments it removes when applied. | None. | Reload |
drag-and-drop |
Whether its books can be dragged onto items. | true |
Reload |
price |
What dragging its books costs. | Free. | Reload |
removable |
Whether the grindstone can remove it. | From the type. | Reload |
disabled-worlds |
Worlds where it does nothing. | None. | Reload |
soulbound |
Keeps the item when the player dies. | Off. | Reload |
minimum-table-level |
Lowest level cost at the enchanting table. | From the rarity. | Reload |
book |
How its books look, stack and how likely they work. | From the rarity and config.yml. |
Reload |
applies-to |
The "Applies to" text on its books. | Made from supported-items. |
Reload |
display-item |
The icon in the menu. | An enchanted book. | Reload |
placeholders |
Your own values, remembered for each enchanted item. | None. | Reload |
triggers |
What the enchantment does. | None. | Reload |
Mistakes in these options are reported in the console with the file, the line and a suggestion, and the file is skipped until you fix it. See Fixing Problems.
The name that appears on the item, in the menu and in messages. It is shown in the color of its rarity.
name: "Lifesteal"One line or a list of lines, shown under the enchantment in the item tooltip, in the menu and in /metaenchants info. Colors work: see Text and Colors.
description:
- "<gray>Heal a little with every hit."
- "<gray>Works better at higher levels."To change the text with the level, write the level where each text starts:
description:
1:
- "<gray>Heal a little with every hit."
4:
- "<gray>Heal a lot with every hit."%level% inside a description is replaced by the level. See Tooltips.
The id of one of your rarities. It decides the color of the name and gives default values for weight, anvil-cost, costs and where it can be obtained.
rarity: epicThe highest level the game will normally give. It is used by the enchanting table, villagers, loot and the /enchant command. Whole number from 1 to 255.
max-level: 3Operators can go above it. See Levels Above the Maximum.
How common the enchantment is compared to others that fit the same item, from 1 to 1024. A bigger weight means it shows up more often. If you don't set it, it comes from the rarity. See Where Enchantments Appear.
How expensive it is to combine at the anvil. Bigger means more expensive. Whole number from 0 to 255. If you don't set it, it comes from the rarity.
These decide at which enchanting-table power the enchantment can be offered at each level. Each has a base and a per-level number:
min-cost: { base: 10, per-level: 8 }
max-cost: { base: 40, per-level: 8 }If you don't write them, they come from the rarity. They are explained in Where Enchantments Appear.
The items that can carry this enchantment. It is a list of item names and tags. This is the only required option.
supported-items: ["#minecraft:swords", "minecraft:mace"]See Items, Slots and Incompatibilities for the list of useful tags.
Items that can get the enchantment from the enchanting table. If you leave it out, it is the same as supported-items. Use it when you want an enchantment that fits more items (through anvils and commands) than the table offers it for.
primary-items: ["minecraft:diamond_sword"]Where the item must be for the enchantment to work: in a hand, or worn on a body part. A list.
slots: [mainhand]
slots: [feet]
slots: [mainhand, offhand]
slots: [armor]See Items, Slots and Incompatibilities for all the values.
Enchantments that cannot be on the same item as this one. It works in both directions: it is enough that one of the two lists the other.
incompatible: ["minecraft:sharpness", "vampirism", "#minecraft:exclusive_set/damage"]Where the enchantment can be found without commands. Turn each place on or off:
obtain:
enchanting-table: true
villagers: true
loot: true
fishing: true
mob-equipment: false
traded-equipment: falsePlaces you don't mention keep the value they have in the rarity. Every place accepts true, false or a chance, like villagers: 30%. fishing separates fishing from chest loot; if neither the rarity nor the enchantment writes it, it follows the final loot value. See Where Enchantments Appear.
true makes it a treasure enchantment, like Mending: it never appears in the enchanting table and it costs double in villager trades. Defaults to what the rarity says.
true marks it as a curse, like Curse of Vanishing. Curses are not removed by the grindstone.
What happens when the same enchantment is on several items the player wears or holds:
-
highest(default): the highest level counts. -
sum: the levels add up.
Example: a player wears boots with level 2 and a chestplate with level 3 of an enchantment that works in [armor]. With highest the level is 3. With sum it is 5.
Which item counts when the enchantment's trigger runs:
-
equipment(default): the plugin looks at what the player holds and wears in theslots. -
event-item: if the event brings an item (like the tool that is wearing down, or the item being consumed), only that item counts. Use it for enchantments that react to one specific item.
activation: event-itemFor example, a curse that makes tools wear out faster uses event-item, because the trigger must look at the tool that is actually losing durability.
The material that represents the enchantment in the menu. By default it is an enchanted book that shows the maximum level.
display-item: MACEValues you create, like how many hits a sword has landed. Every enchantment on every item has its own values: two swords with the same enchantment count separately, and a newly made enchantment starts fresh. Triggers change them with placeholder-add and placeholder-set. See File Placeholders.
placeholders:
kills: 0
bonus: "min({kills} * 0.01, 1)"
triggers:
hunt:
on: kill
do:
- placeholder-add: {name: kills, value: 1}What the enchantment does. This is the most important part and it has its own page: Triggers for Enchantments.
The id of one of your types, from types.yml. Types limit how many enchantments of the same kind an item can have, decide whether the grindstone can remove them, and can make the enchanting table give lower levels.
type: specialrequires lists enchantments the item must already have, with the lowest level they need. replaces lists enchantments that are removed when this one is applied, for upgrades.
requires:
vampirism: 2
replaces: [swiftness]Players can apply books by clicking them on an item in their inventory. drag-and-drop: false turns that off for this enchantment. price makes it cost money, experience levels or items:
price:
levels: 3
per-level: trueSee Dragging a book onto an item.
false means the grindstone cannot remove it. Without it, the type decides. See The grindstone.
Worlds where the enchantment does nothing: its triggers do not run there.
disabled-worlds: [world_nether, minigames]disabled-worlds in config.yml does the same for every enchantment. Names must be written exactly like the folder of the world.
The item stays with the player when they die, instead of dropping:
soulbound: trueOr with more control:
soulbound:
chance: 100
cost: level| Option | What it does | Default |
|---|---|---|
chance |
Chance from 0 to 100 that the item is kept. | 100 |
cost |
What it costs each time it saves the item: none (nothing), level (the enchantment loses one level) or all (the enchantment is removed). |
none |
It works on any item in the inventory, worn or not. When the world has keepInventory, or the player has a keep-inventory effect, nothing is spent. An enchantment can be soulbound and also have triggers.
The enchanting table only gives it when the player pays at least this many levels. See Minimum table level.
How the books of this enchantment look (any item, like a scroll), whether they stack, and their success and destroy rates:
book:
item:
material: PAPER
name: "<gold>{enchant} Scroll {level}"
stackable: true
max-stack: 16
success: 60-100Everything is explained in Enchanted Books.
The text that books show in "Applies to". Without it, it is made from supported-items.
applies-to: "Swords and axes"