Skip to content

Creating An Enchantment

neoramm edited this page Nov 5, 2026 · 1 revision

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.

All the options

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.

name

The name that appears on the item, in the menu and in messages. It is shown in the color of its rarity.

name: "Lifesteal"

description

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.

rarity

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: epic

max-level

The 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: 3

Operators can go above it. See Levels Above the Maximum.

weight

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.

anvil-cost

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.

min-cost and max-cost

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.

supported-items

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.

primary-items

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"]

slots

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.

incompatible

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"]

obtain

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: false

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

treasure

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.

curse

true marks it as a curse, like Curse of Vanishing. Curses are not removed by the grindstone.

stack

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.

activation

Which item counts when the enchantment's trigger runs:

  • equipment (default): the plugin looks at what the player holds and wears in the slots.
  • 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-item

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

display-item

The material that represents the enchantment in the menu. By default it is an enchanted book that shows the maximum level.

display-item: MACE

placeholders

Values 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}

triggers

What the enchantment does. This is the most important part and it has its own page: Triggers for Enchantments.

type

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: special

requires and replaces

requires 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]

See Applying Enchantments.

drag-and-drop and price

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: true

See Dragging a book onto an item.

removable

false means the grindstone cannot remove it. Without it, the type decides. See The grindstone.

disabled-worlds

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.

soulbound

The item stays with the player when they die, instead of dropping:

soulbound: true

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

minimum-table-level

The enchanting table only gives it when the player pays at least this many levels. See Minimum table level.

book

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-100

Everything is explained in Enchanted Books.

applies-to

The text that books show in "Applies to". Without it, it is made from supported-items.

applies-to: "Swords and axes"

Clone this wiki locally