Guide

uxmEnchants adds custom enchantments, each written as one file, and weaves them into the enchanting table, villager trades, loot chests, the anvil and books. Rarities decide how they are found, types decide how they are drawn and whether a grindstone takes them off, and targets decide when they fire.

Install

1. Put the jar in plugins/.
2. Start the server once. The plugin writes its files into plugins/uxmEnchants/, including eight example enchantments.
3. Edit or add files under enchantments/, then run /uxmenchants reload.

PlaceholderAPI, an economy and the claim plugins are optional.

When any content file is wrong, the reload is refused as a whole: the console names the file, the key and the line, and the server keeps the content it had.

Files

An enchantment

enchantments/sharpened.conf is commented in full and is the reference for the format. In short:

An effect block names an effect and its arguments, and may carry its own chance, cooldown, delay, conditions and actions. The effects are damage, heal, feed, ignite, potion, launch, pull, extinguish, lightning, explode, vein-miner, tree-feller, smelt-drops, extra-drops, repair-item and give-experience.

Every number is either fixed or a modifier block that scales with the level:

amount { base = 1.0, per-level = 0.5, cap = 4.0, mode = add, curve = linear }

mode is add (base + per-level * growth) or multiply (base * (1 + per-level * growth)). curve is linear (growth level - 1), diminishing (the square root of that) or exponential (2^(level-1) - 1). cap is the value it never goes above. There is no free maths expression.

A condition is a comparison ("%player_level% >= 10"), a balance ("money >= 250") or an item count ("item DIAMOND >= 2"). An action is [message], [actionbar], [title], [sound], [broadcast], [close], [console], [player], [take-money] or [take-item]. A condition on money together with [take-money] makes an enchantment cost money to fire.

What may go on an item

When an enchantment is added by any route, it is refused when:

• the level is above max-level (or overpower-max on an overpowering anvil);
• it conflicts with something on the item, from either side, or shares an exclusive group with it;
• a required enchantment is missing;
• the item is at its limit and this would be a new enchantment (raising a level is always allowed);
• its type is at that type's limit-per-item.

removed enchantments come off first, so an evolution can replace the enchantment it grows from even on a full item.

The limit is limit.base for everyone, raised by a node limit.node-prefix plus a number (uxmenchants.limit.6), never above limit.maximum-from-node. It counts ours only, never vanilla ones. /enchants limit prints the whole calculation for the item in hand.

Getting enchantments

rarities.conf sets, per rarity, minimum-level (the table level it starts at) and the chance out of a hundred on each route: table-chance, villager-chance, loot-chance, and optionally fishing-chance, mob-drop-chance and raid-chance (they default to loot-chance). A chance may be a modifier block. A chance of 0 closes that route for that rarity.

acquisition in config.conf bounds each route: enabled, cap (the most enchantments one roll gives) and reduction, which divides the chance of every grant after the first. fishing, mob-drops and raids ship off.

The anvil applies books at anvil.base-cost levels for the first of ours, multiplied by cost-exponent for each further one, unless vanilla-costs is on. drag-and-drop (off by default) lets a player click a book onto an item for cost levels, times the book's level when per-level is on. grindstone.enabled decides whether ours come off at all; the type decides which.

Types and targets

A type in types.conf has a name, order, a format with <name>, <roman> and <number>, a limit-per-item (-1 for no limit) and grindstone-removable. A curse is a type that a grindstone does not remove.

A target in targets.conf has items and slots (mainhand, offhand, hands, helmet, chestplate, leggings, boots, armor, any). An enchantment fires only while its item is used from one of its targets' slots. extra-enchantable-items lets the table offer ours on items vanilla does not enchant.

Other settings

Commands

import lore reads lore lines written by plugins that store enchantments as lore; import registry reads minecraft: enchantment keys that name one of ours. An item that matches nothing is left as it was.

The names and aliases come from commands.conf. The reference lists the default aliases and every permission.

Placeholders

Troubleshooting

• A reload is refused. The console names the file, key and line; the old content stays loaded.
• An enchantment is struck through on an item. The player lacks its permission.
• The table never offers an enchantment. Its rarity's table-chance is 0, the table level is below minimum-level, the item is not in table-items, or obtaining.table is off.
• Too many enchantments come out of one table roll. Lower acquisition.table.cap or raise reduction.