# Special Items Special items are scrolls, dusts, orbs, boxes and tags that change other items. Players use them like books: they pick one up in their inventory and click it on the item they want to change. Boxes and rename tags are used with a right click instead. They are all configured in `plugins/MetaEnchants/items.yml`. Changes apply with `/metaenchants reload`. | Item | Kind | What it does | |---|---|---| | White Scroll | `white-scroll` | The next book that fails on the item does not break it. | | Holy White Scroll | `holy-scroll` | The player keeps the item when they die. | | Black Scroll | `black-scroll` | Takes a random enchantment off the item and gives it back as a book. | | Transmog Scroll | `transmog` | Adds the number of enchantments to the item name, like `Sword [5]`. | | Randomization Scroll | `randomizer` | Rolls the success and destroy rates of a book again. | | Magic Dust | `magic-dust` | Raises the success rate of a book. | | Orb | `slot-increaser` | The item can have one more enchantment than the limit. | | StatTrak, MobTrak, BlockTrak, FishTrak | `tracker` | The item starts counting kills, broken blocks or caught fish. | | Soul Tracker and Soul Gem | `tracker`, `soul-gem` | Souls; see [Souls and Trackers](Souls-And-Trackers). | | Secret Dust, book boxes | `box` | Opens into a random reward. | | Mystery Dust | `plain` | Does nothing by itself; something to give or trade. | | Item Name Tag | `rename-tag` | Renames the held item from the chat. | The success and destroy rates of books only matter when `apply.rates` is `true` in `config.yml`. See [Success and destroy rates](Books#success-and-destroy-rates). ## Getting special items ``` /metaenchants giveitem [amount] [value] ``` `` is the name of the item in `items.yml`, like `white-scroll`. `value` sets the value of dusts, orbs and soul gems instead of a random one: `/metaenchants giveitem Steve magic-dust 1 25` gives a dust of +25%. Anywhere that accepts an item (menus, [kits](Kits), the [Enchanter](Enchanter-Tinkerer-Alchemist#the-enchanter), the `give-item` action of triggers, other plugins that use the Trigger Engine) can give them with this id: ```yaml external-item: "metaenchants:item/white-scroll" ``` With a value at the end: `metaenchants:item/magic-dust/25`. ## How `items.yml` looks ```yaml enabled: true display: protected: "PROTECTED" holy: "HOLY" slots: "+%amount% enchantment slot(s)" items: white-scroll: kind: white-scroll consume: true item: material: MAP name: "White Scroll" lore: - "Keeps an item from breaking" - "when a book fails on it." ``` | Setting | Meaning | |---|---| | `enabled` | `false` turns off every special item: they stop working and their lines disappear from tooltips. The items stay in the inventories of players and work again when you turn them back on. | | `display` | Lines added at the end of the tooltip of items that carry a mark. `%amount%` is the number of extra slots. Delete a line to hide it. Trackers have their own lines; see [Souls and Trackers](Souls-And-Trackers). | | `souls` | How souls are earned; see [Souls and Trackers](Souls-And-Trackers). | | `items` | The special items. The name of each one (`white-scroll`) is its id: lowercase letters, numbers, `-` and `_`. | Like enchantment tooltips, the `display` lines only change what players see; nothing is written on the item. ### Options of every special item | Option | Meaning | |---|---| | `kind` | What it does: one of the kinds in the table above. `plain` by default. | | `item` | What it looks like. Same format as any item; see [Items](../Items). It must be there. | | `applies-to` | The items it can be used on: ids like `minecraft:bow`, tags like `#minecraft:swords`, or `any`. Without it, any item that does not stack or has durability. Used by white scrolls, holy scrolls, orbs and trackers. | In the `name` and `lore` of the item, `%value%` is replaced by the value of that item (the bonus of a dust, the souls of a gem...). Special items cannot be used on other special items, and players in creative mode cannot use them from the creative inventory. ## White scroll ```yaml white-scroll: kind: white-scroll consume: true applies-to: [any] item: material: MAP name: "White Scroll" ``` The item gets the **PROTECTED** line. The next time a book fails on it and would break it, the item is saved instead. With `consume: true` the protection is used up at that moment; with `false` it stays forever. ## Holy white scroll ```yaml holy-white-scroll: kind: holy-scroll consume: true item: material: PAPER name: "Holy White Scroll" ``` The item gets the **HOLY** line. When the player dies, the item stays with them instead of dropping. With `consume: true` this happens once; with `false`, every time. Enchantments with [`soulbound`](Creating-An-Enchantment#soulbound) do the same through an enchantment. ## Black scroll ```yaml black-scroll: kind: black-scroll success: 60-100 destroy: 0 item: material: INK_SAC name: "Black Scroll" ``` Takes one random enchantment of this plugin off the item and gives it to the player as a book of the same level. Enchantments with `removable: false` are never taken. `success` and `destroy` are the rates of that book: a number from 0 to 100 or a range like `60-100`. ## Transmog scroll ```yaml transmog-scroll: kind: transmog format: " [%count%]" ``` Adds `format` to the end of the item name, with `%count%` as the number of enchantments. Using it again updates the number instead of adding a second one. ## Randomization scroll ```yaml randomizer: kind: randomizer rarities: [] ``` Used on a book, it rolls its success and destroy rates again, with the ranges of that enchantment's [book](Books). `rarities` limits it to books of some rarities, like `[rare, epic]`; empty means any. It only works on one book at a time, not on a stack. ## Magic dust ```yaml magic-dust: kind: magic-dust value: 1-10 rarities: [] lower-destroy: false item: material: SUGAR name: "Magic Dust (+%value%%)" ``` Used on a book, it adds its value to the success rate, up to 100%. `value` is the bonus: a number, or a range like `1-10` so each dust gets a random value when it is created. With `lower-destroy: true` it also lowers the destroy rate by the same amount. `rarities` works like in the randomizer. Two dusts of the same kind can be joined by the [Alchemist](Enchanter-Tinkerer-Alchemist#the-alchemist). ## Orbs: extra enchantment slots ```yaml slot-increaser: kind: slot-increaser value: 1 max: 3 success: 100 applies-to: [any] ``` When there is a [maximum of enchantments per item](Applying-Enchantments#maximum-enchantments-per-item), each orb lets the item have `value` more. `max` is the most extra slots one item can get (0 = no limit). `success` is the chance that it works; when it fails, the orb is used up anyway. Orbs do nothing when there is no maximum. ## Trackers ```yaml stattrak: kind: tracker stat: player-kills applies-to: ["#minecraft:swords", "#minecraft:axes"] ``` The item starts counting. See [Souls and Trackers](Souls-And-Trackers). ## Boxes ```yaml secret-dust: kind: box rewards: - give: "metaenchants:item/magic-dust" weight: 3 - give: "metaenchants:item/mystery-dust" weight: 1 item: material: FIREWORK_STAR name: "Secret Dust" rare-book: kind: box rewards: - "metaenchants:random-book/rare" item: material: BOOK name: "Rare Enchantment Book" ``` The player holds the box and right-clicks: one box is used and one reward is given. Each reward has: | Option | Meaning | |---|---| | `give` | What to give: `metaenchants:item/`, `metaenchants:random-book/`, `metaenchants:book//`, `metaenchants:set//`, a material like `DIAMOND`, or an item of another plugin like `oraxen:ruby`. | | `weight` | How likely it is compared with the others. With weights 3 and 1, the first comes out three times out of four. 1 by default. | | `amount` | How many. 1 by default. | A reward can also be just the text of `give`, like in `rare-book`. ## Rename tag ```yaml rename-tag: kind: rename-tag colors: true blacklist: ["admin", "owner"] ``` How players use it: 1. Right-click with the tag in the hand. The plugin asks for a name in the chat. 2. Take the item to rename in the main hand (the tag must still be somewhere in the inventory). 3. Type the name in the chat within 30 seconds. The item gets that name and one tag is used. Typing `cancel` stops it. | Option | Meaning | |---|---| | `colors` | Let players use colors and styles like `` or ``. | | `blacklist` | Names that contain any of these words (or patterns) are refused. Upper and lower case do not matter. | Names can be up to 48 letters long, colors not counted. ## Messages These are in the [language file](Menu-And-Messages#languages). `%name%` is the special item and `%item%` the item it was used on. | Message | When | |---|---| | `item-applied` | A special item worked. | | `item-not-here` | It cannot be used on that item. | | `item-already` | The item already has that mark, or the book is already at 100%. | | `item-stacked` | A randomizer or dust was used on a stack of books. | | `item-rerolled` | A randomizer gave new rates: `%value%` success, `%amount%` destroy. | | `item-dust` | A dust raised a book to `%value%` success. | | `item-limit` | The item has the most extra slots it can get. | | `item-failed` | An orb failed. | | `item-black-empty` | A black scroll found nothing to take. | | `item-black-done` | A black scroll took `%name%` off `%item%`. | | `item-box` | A box gave `%name%`. | | `item-holy` | A holy scroll kept `%item%` on death. | | `item-protected` | A white scroll saved `%item%`. | | `rename-ask`, `rename-cancel`, `rename-blocked`, `rename-done` | The steps of the rename tag. `%name%` in `rename-done` is the new name. | | `unknown-item` | `giveitem` with an id that does not exist. |