Enchant books

An enchant book is how players put an enchant on their gear: drag the book onto a held or worn item to apply it. There is one book likeness for every enchant — a specific book (from a command, a mystery book, a drop, or combining) is minted from this single template with the enchant, level, and success chance filled in.

The book template — items/enchant-book.yml

type: enchant-book
material: ENCHANTED_BOOK
# Bold, tier-coloured "<Name> <Level>". (Colour first, then &l, so the bold actually sticks.)
name: "{TIER_COLOR}&l{ENCHANT} {LEVEL}"
lore:
  - "&a{SUCCESS}% Success Rate"
  - "&c{FAILURE}% Failure Rate"
  - ""
  - "{TIER_COLOR}{DESCRIPTION}"
  - ""
  - "&7{KINDS} Enchantment"
  - "&7Drag n' Drop on an item to apply."
# The success/failure rate lives in the main lore above, so success-lore is empty by default. Lines here
# are appended only to a book minted with an explicit success chance (the unopened/randomized book).
success-lore: []
# When a sub-100% book FAILS its apply roll, destroy the gear — unless a White Scroll guards it.
destroy-on-fail: true

Placeholders, filled in when a concrete book is minted — usable in both name and lore:

Token	Renders
{ENCHANT}	the enchant's display name
{LEVEL}	the granted level (Roman or Arabic per lore.roman in config.yml)
{TIER_COLOR}	the enchant's rarity-tier colour code, from tiers.yml
{SUCCESS}	the apply success chance (a guaranteed book shows 100)
{FAILURE}	100 - {SUCCESS}
{KINDS}	the applies-to kinds, grammatically joined (e.g. Sword & Axe)
{DESCRIPTION}	the enchant's description, word-wrapped to lore.item-wrap — one lore line per wrapped line

:::warning destroy-on-fail A book below 100% success can fail its apply roll. When it does, destroy-on-fail: true shatters the gear — unless a White Scroll is guarding it. Books that always succeed (e.g. /se book) never fail, so this only bites the random mystery/rolled books. Set it false to make a failed apply harmless (the White Scroll then has nothing to do). :::

The unopened (mystery) book — items/unopened-book.yml

A tier-scoped mystery book. Right-click it to reveal a concrete enchant book of a random enchant from its tier, at a random level and a random success chance:

type: unopened-book
material: BOOK
name: "&b{TIER} Mystery Book"
lore:
  - "&7Right-click to reveal a random"
  - "&7{TIER} enchant book."
min-success: 25                # the revealed book's success rolls uniformly in [min, max]
max-success: 100

The mystery book's own name/lore take three tokens, substituted at mint:

Token	Renders
{TIER}	the raw tier key, lowercase (e.g. legendary)
{TIER_NAME}	the tier key with its first letter capitalized (e.g. Legendary)
{TIER_COLOR}	the tier's colour code from tiers.yml (e.g. &6)

The revealed book carries the rolled enchant/level/percent, which name it in the reveal message (lang.yml) rather than here.

The global success ceiling

books.max-success in config.yml (default 100) is the maximum success rate a book may reach through randomness or economy items — the unopened book's roll, a Randomizer Scroll reroll, the Black Scroll's conversion roll, and Success Dust (a dust that would push a book past the ceiling snaps to it). It does not touch admin mints — a guaranteed /se book or an explicit /se give book <player> <enchant> <level> <success> overrides it.

Minting & giving

/se book <enchant> [level]                # mint a guaranteed (100%) book to yourself
/se give book <player> <enchant> [level] [success]
/se give book <player> random <tier>      # a concrete random book from that tier
/se unopened <tier>                       # mint a tier mystery book to yourself
/se give unopened <player> <tier>

The self-mint takes no success argument — it always mints a guaranteed book. Only the give form accepts an explicit success percent.

:::tip Combine, dust, and reroll A book's success chance can be raised with Success Dust and rerolled with a Randomizer Scroll. Two books fuse into one of the next level at the Alchemist bench when they are the same enchant, at the same level, and that level is below the enchant's max — slots don't gate the combine. The upgrade inherits the better of the two inputs' success, clamped to books.max-success. :::