Skip to content

Special Items

neoramm edited this page Nov 5, 2026 · 1 revision

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

Getting special items

/metaenchants giveitem <players> <id> [amount] [value]

<id> 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, the Enchanter, the give-item action of triggers, other plugins that use the Trigger Engine) can give them with this id:

external-item: "metaenchants:item/white-scroll"

With a value at the end: metaenchants:item/magic-dust/25.

How items.yml looks

enabled: true

display:
  protected: "<white><bold>PROTECTED"
  holy: "<gold><bold>HOLY"
  slots: "<aqua>+%amount% enchantment slot(s)"

items:
  white-scroll:
    kind: white-scroll
    consume: true
    item:
      material: MAP
      name: "<white>White Scroll"
      lore:
        - "<gray>Keeps an item from breaking"
        - "<gray>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 How souls are earned; see 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. 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

  white-scroll:
    kind: white-scroll
    consume: true
    applies-to: [any]
    item:
      material: MAP
      name: "<white>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

  holy-white-scroll:
    kind: holy-scroll
    consume: true
    item:
      material: PAPER
      name: "<gold>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 do the same through an enchantment.

Black scroll

  black-scroll:
    kind: black-scroll
    success: 60-100
    destroy: 0
    item:
      material: INK_SAC
      name: "<dark_gray>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

  transmog-scroll:
    kind: transmog
    format: " <light_purple>[<aqua>%count%</aqua>]"

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

  randomizer:
    kind: randomizer
    rarities: []

Used on a book, it rolls its success and destroy rates again, with the ranges of that enchantment's book. 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

  magic-dust:
    kind: magic-dust
    value: 1-10
    rarities: []
    lower-destroy: false
    item:
      material: SUGAR
      name: "<aqua>Magic Dust <gray>(+%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.

Orbs: extra enchantment slots

  slot-increaser:
    kind: slot-increaser
    value: 1
    max: 3
    success: 100
    applies-to: [any]

When there is a maximum of 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

  stattrak:
    kind: tracker
    stat: player-kills
    applies-to: ["#minecraft:swords", "#minecraft:axes"]

The item starts counting. See Souls and Trackers.

Boxes

  secret-dust:
    kind: box
    rewards:
      - give: "metaenchants:item/magic-dust"
        weight: 3
      - give: "metaenchants:item/mystery-dust"
        weight: 1
    item:
      material: FIREWORK_STAR
      name: "<aqua>Secret Dust"

  rare-book:
    kind: box
    rewards:
      - "metaenchants:random-book/rare"
    item:
      material: BOOK
      name: "<aqua>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/<id>, metaenchants:random-book/<rarity>, metaenchants:book/<enchantment>/<level>, metaenchants:set/<set>/<piece>, 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

  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 <red> or <gradient:red:gold>.
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. %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.

Clone this wiki locally