# 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](Applying-Enchantments#dragging-a-book-onto-an-item), 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`. ```yaml books: stackable: false max-stack: 64 success: 100 destroy: 0 ``` | Option | What it does | Default | |---|---|---| | `item` | The item the book looks like. See [below](#what-the-book-looks-like). | 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](../Items). Its `material` decides the **look**, not what the item is: ```yaml book: item: material: ECHO_SHARD name: "Soulbound Scroll" lore: - "Drop it on an item in your" - "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](../Items#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: ```yaml 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`: ```yaml book: stackable: true max-stack: 16 ``` Two books only stack when they are exactly the same. Books with different [rates](#success-and-destroy-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`: ```yaml 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: ```yaml book: success: 60-100 destroy: 0-25 ``` Each book gets its own value when it is created, and players see it in the [tooltip](Tooltips#enchanted-books). Rates only matter when [dragging books onto items](Applying-Enchantments#dragging-a-book-onto-an-item). 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](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](Enchanter-Tinkerer-Alchemist#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 [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/` | A book of that enchantment at level 1. | | `metaenchants:book//` | A book at that level. | | `metaenchants:random-book` | A book of a random enchantment and level. | | `metaenchants:random-book/` | A random book of that rarity. | A MetaJobs reward that gives a random epic book: ```yaml do: - give-item: item: material: ENCHANTED_BOOK external-item: metaenchants:random-book/epic ``` A crate or menu icon that gives *Vampirism III*: ```yaml 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](../Items#items-from-other-plugins). 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.