Skip to content
neoramm edited this page Nov 5, 2026 · 1 revision

Enchanted Books

An enchanted book carries an enchantment until a player puts it on an item. With MetaEnchants you choose, for each enchantment:

  • what the book looks like: a normal enchanted book, or any other item (a scroll, a gem, an item from ItemsAdder...);
  • whether books stack in the inventory;
  • how likely the book is to work, and to break the item when it fails.

Whatever it looks like, the book always works as an enchanted book: it goes in the anvil, it can be dragged onto items, and the game treats it like any other book.

Three places, one result

Book settings can be written in three places. Each one only needs the options it changes; the rest comes from the place before it:

  1. books in config.yml: for every book.
  2. book inside a rarity, in rarities.yml: for the books of the enchantments of that rarity.
  3. book inside an enchantment file: for the books of that enchantment.

The enchantment wins over the rarity, and the rarity wins over config.yml.

books:
  stackable: false
  max-stack: 64
  success: 100
  destroy: 0
Option What it does Default
item The item the book looks like. See below. A normal enchanted book.
stackable true lets books of the same enchantment and level stack. false
max-stack How many stack in one slot, from 1 to 99. Only with stackable: true. 64
success Chance from 0 to 100 that the book works. 100
destroy Chance from 0 to 100 that the item breaks when the book fails. 0

Changes reload with /metaenchants reload. Books that already exist keep the look they were made with.

What the book looks like

item uses the same format as items everywhere else (menus, give-item...): see Items. Its material decides the look, not what the item is:

book:
  item:
    material: ECHO_SHARD
    name: "<gold>Soulbound Scroll"
    lore:
      - "<gray>Drop it on an item in your"
      - "<gray>inventory to bind it to your soul."

This book looks like an echo shard, with that name and lore, but it is still an enchanted book with Soulbound inside.

In the name and lore you can use:

Value What it is
{enchant} The name of the enchantment.
{level} The level of the book.
{enchant.max_level}, {enchant.rarity} Its maximum level and rarity id.
{player} The player who gets the book, when there is one.

Other useful options of item:

  • custom-model-data or item-model for a texture from your resource pack.
  • external-item: itemsadder:myitems:scroll (or nexo:, craftengine:) to look like an item of another plugin. See Items from other plugins.
  • glint: false to remove the enchanted shine.
  • rarity: EPIC to color the name like vanilla rare items.

Keep material: ENCHANTED_BOOK to change only the name, lore or rarity of a normal book:

book:
  item:
    material: ENCHANTED_BOOK
    rarity: EPIC

Stacking books

Vanilla enchanted books never stack: each one takes a whole slot. With stackable: true, books of the same enchantment and level stack up to max-stack:

book:
  stackable: true
  max-stack: 16

Two books only stack when they are exactly the same. Books with different rates (for example, one with 80% and one with 95%) do not stack. If you want stackable books with rates, give them one fixed value, like success: 90, instead of a range.

When a player drags a stack of books onto an item, only one book is used.

Success and destroy rates

Rates add risk to applying books. They are off until you turn them on in config.yml:

apply:
  rates: true

From then on, every book MetaEnchants creates gets two numbers written on it:

  • Success: the chance that dragging the book onto an item works.
  • Destroy: if the book fails, the chance that the item breaks too.

A failed book is always used up. Example with success: 70 and destroy: 20:

What happens Chance
The enchantment is applied. 70%
The book fails and is lost; the item is fine. 24% (80% of the 30%)
The book fails and the item breaks. 6% (20% of the 30%)

Write a range to give each book a random value:

book:
  success: 60-100
  destroy: 0-25

Each book gets its own value when it is created, and players see it in the tooltip.

Rates only matter when dragging books onto items. The anvil ignores them. Books taken from the menu by administrators always have 100% success and 0% destroy.

Players can change the odds with special items: magic dust raises the success rate of a book, a randomization scroll rolls both numbers again, and a white scroll saves an item from breaking once. The Alchemist can also join two books into a better one.

Which books get these settings

Where the book comes from Look and stacking Rates
/metaenchants give and randombook Yes Rolled
The menus (with metaenchants.menu.take) Yes 100% / 0%
Triggers and menus with external-item: metaenchants:... Yes Rolled
The enchanting table, villagers, chests and fishing Yes, when the book has one MetaEnchants enchantment Rolled
/enchant, /give and other plugins No, they are normal books None (they always work)

Random books

/metaenchants randombook <players> [rarity] gives each player a book of a random MetaEnchants enchantment, at a random level. More common enchantments (bigger weight) come up more often.

/metaenchants randombook Steve
/metaenchants randombook @a legendary

Books as items in triggers and menus

Anywhere an item can be written, external-item can create MetaEnchants books:

Id Gives
metaenchants:book/<enchantment> A book of that enchantment at level 1.
metaenchants:book/<enchantment>/<level> A book at that level.
metaenchants:random-book A book of a random enchantment and level.
metaenchants:random-book/<rarity> A random book of that rarity.

A MetaJobs reward that gives a random epic book:

do:
  - give-item:
      item:
        material: ENCHANTED_BOOK
        external-item: metaenchants:random-book/epic

A crate or menu icon that gives Vampirism III:

item:
  material: ENCHANTED_BOOK
  external-item: metaenchants:book/vampirism/3

material is what is given if the id is wrong (for example, an enchantment that no longer exists), as with every external item. These books get the look, stacking and rates of their enchantment.

In short

  • books (config.yml), book (rarity) and book (enchantment) build each book, the most specific winning.
  • item changes the look; the book still works as an enchanted book.
  • stackable and max-stack let books stack.
  • success and destroy add risk, with apply.rates: true.
  • randombook and metaenchants:random-book/... give random books.

Clone this wiki locally