# 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: ```yaml name: "Lifesteal" description: - "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`](#name) | The name players see. | The id with a capital letter. | Restart | | [`description`](#description) | Lines shown in the tooltip and the menu, optionally per level. | None. | Reload | | [`rarity`](#rarity) | The rarity (color and defaults). | The first one in `rarities.yml`. | Restart | | [`max-level`](#max-level) | The highest normal level. | `1` | Restart | | [`weight`](#weight) | How common it is. | From the rarity. | Restart | | [`anvil-cost`](#anvil-cost) | How costly it is at the anvil. | From the rarity. | Restart | | [`min-cost` and `max-cost`](#min-cost-and-max-cost) | Levels at the enchanting table. | From the rarity. | Restart | | [`supported-items`](#supported-items) | Items that accept it. **Required.** | | Restart | | [`primary-items`](#primary-items) | Items that get it from the table. | Same as `supported-items`. | Restart | | [`slots`](#slots) | Where it must be worn or held to work. | `[mainhand]` | Restart | | [`incompatible`](#incompatible) | Enchantments it cannot share an item with. | None. | Restart | | [`obtain`](#obtain) | Where it can be found naturally, and how often. | From the rarity. | Restart (chances: reload) | | [`treasure`](#treasure) | Treasure enchantments never appear in the table. | From the rarity. | Restart | | [`curse`](#curse) | Marks it as a curse. | `false` | Restart | | [`stack`](#stack) | What happens with several items. | `highest` | Restart | | [`activation`](#activation) | Which item counts. | `equipment` | Reload | | [`type`](#type) | Its type, for limits per item and the grindstone. | The first type. | Reload | | [`requires`](#requires-and-replaces) | Enchantments the item must already have. | None. | Reload | | [`replaces`](#requires-and-replaces) | Enchantments it removes when applied. | None. | Reload | | [`drag-and-drop`](#drag-and-drop-and-price) | Whether its books can be dragged onto items. | `true` | Reload | | [`price`](#drag-and-drop-and-price) | What dragging its books costs. | Free. | Reload | | [`removable`](#removable) | Whether the grindstone can remove it. | From the type. | Reload | | [`disabled-worlds`](#disabled-worlds) | Worlds where it does nothing. | None. | Reload | | [`soulbound`](#soulbound) | Keeps the item when the player dies. | Off. | Reload | | [`minimum-table-level`](#minimum-table-level) | Lowest level cost at the enchanting table. | From the rarity. | Reload | | [`book`](#book) | How its books look, stack and how likely they work. | From the rarity and `config.yml`. | Reload | | [`applies-to`](#applies-to) | The "Applies to" text on its books. | Made from `supported-items`. | Reload | | [`display-item`](#display-item) | The icon in the menu. | An enchanted book. | Reload | | [`placeholders`](#placeholders) | Your own values, remembered for each enchanted item. | None. | Reload | | [`triggers`](#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](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](Rarities). ```yaml name: "Lifesteal" ``` ## `description` One line or a list of lines, shown under the enchantment in the item [tooltip](Tooltips), in the menu and in `/metaenchants info`. Colors work: see [Text and Colors](../Text-And-Colors). ```yaml description: - "Heal a little with every hit." - "Works better at higher levels." ``` To change the text with the level, write the level where each text starts: ```yaml description: 1: - "Heal a little with every hit." 4: - "Heal a lot with every hit." ``` `%level%` inside a description is replaced by the level. See [Tooltips](Tooltips#descriptions). ## `rarity` The id of one of your [rarities](Rarities). It decides the color of the name and gives default values for `weight`, `anvil-cost`, costs and where it can be obtained. ```yaml 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. ```yaml max-level: 3 ``` Operators can go above it. See [Levels Above the Maximum](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](Where-Enchantments-Appear#weight). ## `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: ```yaml 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](Where-Enchantments-Appear#min-cost-and-max-cost). ## `supported-items` The items that can carry this enchantment. It is a list of **item names** and **tags**. This is the only required option. ```yaml supported-items: ["#minecraft:swords", "minecraft:mace"] ``` See [Items, Slots and Incompatibilities](Items-Slots-And-Incompatibilities#supported-items) 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. ```yaml 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. ```yaml slots: [mainhand] slots: [feet] slots: [mainhand, offhand] slots: [armor] ``` See [Items, Slots and Incompatibilities](Items-Slots-And-Incompatibilities#slots) 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. ```yaml incompatible: ["minecraft:sharpness", "vampirism", "#minecraft:exclusive_set/damage"] ``` ## `obtain` Where the enchantment can be found without commands. Turn each place on or off: ```yaml 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](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. ```yaml 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. ```yaml 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](../File-Placeholders). ```yaml 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](Triggers-For-Enchantments). ## `type` The id of one of your [types](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. ```yaml 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. ```yaml requires: vampirism: 2 replaces: [swiftness] ``` See [Applying Enchantments](Applying-Enchantments#requires-enchantments-that-must-be-there-first). ## `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: ```yaml price: levels: 3 per-level: true ``` See [Dragging a book onto an item](Applying-Enchantments#dragging-a-book-onto-an-item). ## `removable` `false` means the grindstone cannot remove it. Without it, the [type](Types) decides. See [The grindstone](Applying-Enchantments#the-grindstone). ## `disabled-worlds` Worlds where the enchantment does nothing: its triggers do not run there. ```yaml 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: ```yaml soulbound: true ``` Or with more control: ```yaml 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](Where-Enchantments-Appear#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: ```yaml book: item: material: PAPER name: "{enchant} Scroll {level}" stackable: true max-stack: 16 success: 60-100 ``` Everything is explained in [Enchanted Books](Books). ## `applies-to` The text that books show in "Applies to". Without it, it is made from `supported-items`. ```yaml applies-to: "Swords and axes" ```