RPGEnchantsPlus

A fully-featured RPG enchantment plugin for Spigot & Paper servers. Roll custom enchantment books from a slot-machine GUI, apply them to your gear, and let server operators create entirely new enchantments through YAML — no Java required.

Spigot / Paper 1.14+ Java 11 Vault support PlaceholderAPI 8 built-in enchants Unlimited custom enchants

What's Included

🎰 Slot Machine GUI

Roll for random enchants by rarity or category. Watch the animated reel before your enchant is revealed.

📚 8 Built-in Enchants

Lifesteal, Bleed, Execute, DamageReduce, Dodge, AutoSmelt, DoubleD rop, and VeinMiner.

🛠 YAML Custom Enchants

Define your own enchants in YAML files — triggers, effects, conditions, per-level configs.

⚙ Fully Configurable

Rarity weights, costs, max levels, lore text, book icons — all editable without touching Java code.

📦 Installation

Download RPGEnchantsPlus-1.0.0.jar and drop it into your server's plugins/ folder.
Restart the server. Config files are generated automatically in plugins/RPGEnchantsPlus/.
(Optional) Install Vault + an economy plugin to enable money-based enchant costs.
(Optional) Install PlaceholderAPI to use %rpgenchants_*% placeholders.
Adjust config.yml, enchantments.yml, and any files in custom-enchants/ to your liking.
Run /rpgenc reload to apply changes without restarting.

Soft Dependencies

Plugin	Purpose	Required?
Vault	Money-based enchant costs	No — XP mode always available
PlaceholderAPI	`%rpgenchants_*%` variables	No

💬 Commands

All commands use the root /rpgenc. Aliases: /rpe, /rpgenchants.

Command	Description	Permission
`/rpgenc`	Opens the main enchant GUI.	rpgenchants.use
`/rpgenc give <player> <id> <level>`	Gives an enchant book directly to a player's inventory.	rpgenchants.give
`/rpgenc reload`	Reloads all config files (config.yml, enchantments.yml, menus, messages, custom-enchants).	rpgenchants.reload

💡

Tab-completion is supported on all arguments of /rpgenc give: player names, enchant IDs, and valid level numbers.

🔑 Permissions

Permission	Default	Description
rpgenchants.use	Everyone	Open the enchant GUI with `/rpgenc`.
rpgenchants.give	OP	Give enchant books via `/rpgenc give`.
rpgenchants.reload	OP	Reload plugin configuration.
rpgenchants.admin	OP	Grants all three permissions above.

🎰 GUI System

Run /rpgenc to open the main menu. From there you can roll enchant books using money (requires Vault) or XP levels.

Menu Flow

Screen	Description
Main Menu	Entry point. Choose: Random (Money), Random (XP), By Rarity, or By Category.
Rarity Select	Pick a rarity tier. Shows the cost and all enchants available at that rarity.
Category Select	Pick Combat, Mining, Defense, or Utility. Shows the cost and enchants in that category.
Roll Animation	Slot-machine reel spins across 5 slots. Slows down as the winner is revealed.
Confirm / Cancel	After the roll, confirm to receive the book or cancel to keep your currency.

Roll Animation

Duration and speed are configurable in config.yml under the animation section. The reel uses weighted rarity chances — rarer enchants appear less often.

📖 Applying Books

Hold the enchant book in your main hand.
Hold the item you want to enchant in your off-hand.
Right-click (air or a block) to trigger the application roll.

Outcomes

Result	Default Chance	Effect
✅ Success	70%	The enchant is applied. The book is consumed.
❌ Fail	20%	Nothing happens. The book is consumed, item survives.
💥 Destroy	10%	The item in your off-hand is destroyed. The book is consumed.

Change apply.success-chance and apply.destroy-chance in config.yml. The remaining percentage is the fail chance.

⚠️

An enchant can only be applied to compatible items. Trying to put a sword enchant on boots will give you the "not compatible" message.

✨ All Enchantments

RPGEnchantsPlus ships with 8 enchantments across three categories. Each is fully configurable in enchantments.yml.

⚔ Combat Enchants

Lifesteal

RARE COMBAT Max Level: 5 Applies to: Swords, Axes

Heals the attacker for a portion of damage dealt on each hit. The heal scales with level and rarity multiplier.

Config Key	Default	Description
base-heal	`2.0`	Hearts healed per hit at level 1. (1.0 = ½ heart)

Bleed

UNCOMMON COMBAT Max Level: 3 Applies to: Swords

Inflicts a damage-over-time bleed effect. Deals damage every second for (3 + level) seconds. Shows an action bar message to the bleeding target.

Config Key	Default	Description
tick-damage	`0.5`	Damage per bleed tick. (0.5 = ¼ heart)

Execute

EPIC COMBAT Max Level: 5 Applies to: Swords, Axes

Deals bonus damage when the target is below a health threshold. The bonus scales with level × rarity multiplier.

Config Key	Default	Description
threshold	`30.0`	Target must be at or below this % of max HP to trigger the bonus.

🛡 Defense Enchants

Damage Reduce

RARE DEFENSE Max Level: 5 Applies to: All Armor

Reduces all incoming damage by a percentage. The reduction scales with level but is capped to prevent invincibility.

Config Key	Default	Description
base-reduction	`3.0`	% damage reduced at level 1.
max-reduction	`75.0`	Hard cap — reduction can never exceed this %.

Dodge

EPIC DEFENSE Max Level: 4 Applies to: Boots, Leggings

Grants a chance to completely negate incoming attacks. Shows a "Dodged!" action bar message. Has a 3-second cooldown.

Config Key	Default	Description
base-chance	`5.0`	Dodge chance at level 1 (%).
max-chance	`60.0`	Hard cap — dodge can never exceed this %.

⛏ Mining Enchants

AutoSmelt

UNCOMMON MINING Max Level: 1 Applies to: Pickaxes

Automatically smelts mined ores into their ingot form. Works with vanilla and 1.17+ deepslate ores, copper, ancient debris, and more.

Double Drop

RARE MINING Max Level: 3 Applies to: Pickaxes, Axes, Shovels

Gives a chance to drop double the items when breaking blocks. Chance scales with level and rarity multiplier.

Config Key	Default	Description
base-chance	`10.0`	Chance to double drops at level 1 (%).

Vein Miner

EPIC MINING Max Level: 3 Applies to: Pickaxes

Mines an entire connected ore vein at once. Hold Sneak while breaking an ore to activate. Works with all ore types including 1.17+ deepslate ores and ancient debris.

Config Key	Default	Description
base-blocks	`8`	Maximum blocks mined at level 1.
blocks-per-level	`4`	Extra blocks added per level above 1.

⚙ Configuration

All files live inside plugins/RPGEnchantsPlus/. Changes take effect after /rpgenc reload.

File	Purpose
`config.yml`	Rarities, economy costs, application chances, animation, particle settings.
`enchantments.yml`	Per-enchant settings: name, lore, icon, rarity, max-level, and mechanic values.
`messages.yml`	All player-facing text. Supports `&` color codes.
`menus/`	GUI layout files (slot positions, materials, item names) for each screen.
`custom-enchants/*.yml`	Your own YAML enchants. One or many files, each can define multiple enchants.

config.yml

Rarity System

# Six tiers — each controls roll weight, stat multiplier, and shop price.
rarities:
  common:
    chance:     50.0   # Roll weight (higher = more frequent)
    multiplier: 1.0    # Scales enchant power values
    color:      "&#B8B8B8"
    cost:       500    # Base shop price (requires Vault)
  # uncommon / rare / epic / legendary / mythic follow the same structure

Economy Costs

costs:
  random:     1000  # Any random enchant (money)
  random-xp:  30    # Any random enchant (XP levels)
  common:     500   # Roll a specific rarity
  rare:       2500
  # epic / legendary / mythic...
  combat:     1500  # Roll by category
  mining:     1000
  defense:    1200
  utility:    800

Application System

apply:
  success-chance: 70.0  # % chance enchant is applied
  destroy-chance: 10.0  # % chance item is destroyed
  # remaining 20% = fail (item survives, book consumed)

max-enchants-per-item: 5

Animation

animation:
  roll-duration-ticks: 60  # 20 ticks = 1 second
  speed-start:         2   # Fast spin at start
  speed-end:           10  # Slow spin at end

enchantments.yml

Controls every built-in enchantment. All fields are optional — missing keys fall back to defaults.

lifesteal:
  enabled:    true
  rarity:     rare          # COMMON/UNCOMMON/RARE/EPIC/LEGENDARY/MYTHIC
  max-level:  5
  base-heal:  2.0           # mechanic value
  name:       "&cLifesteal"  # display name (supports & colors)
  item:       ENCHANTED_BOOK# book icon material
  lore:                       # shown on the book
    - "&7Steals HP on hit."
    - "&7Level: &e{level}&7/&e{max-level}"

✅

Lore supports two placeholders: {level} and {max-level}. Color codes use the & prefix.

messages.yml

Every player-facing message. Supports & color codes and {placeholder} variables.

Key	Placeholders	Default
`success`	`{enchant}`	Enchant applied successfully.
`fail`	—	Enchantment failed, item unharmed.
`destroy`	—	Item destroyed in the process.
`no-money`	`{amount}`	Not enough coins.
`no-xp`	`{amount}`	Not enough XP levels.
`give-success`	`{player}` `{enchant}` `{level}`	Book given to player.
`roll-result`	`{enchant}` `{level}`	Roll result announcement.

🛠 Custom Enchants

Create entirely new enchantments by dropping .yml files into plugins/RPGEnchantsPlus/custom-enchants/. No Java, no recompiling — just YAML.

Custom enchants are full citizens of the plugin: they appear in the GUI roll, can be given via /rpgenc give, applied to items with books, and reload with /rpgenc reload.

ℹ️

Custom enchants always use the Utility category. They appear in the By-Category GUI under Utility and are rollable by rarity.

File Structure

Each file can contain one or many enchants. The top-level key is the enchant's ID (must be unique across all files).

# custom-enchants/my-enchants.yml

my-enchant-id:               # unique ID, lowercase, no spaces
  enabled:          true
  name:             "&6My Enchant"
  rarity:           EPIC
  max-level:        3
  trigger:          ATTACK_MOB
  applicable-items:
    - ALL_SWORDS
  item:             ENCHANTED_BOOK
  lore:
    - "&7Does something cool."
    - "&7Level: &e{level}&7/&e{max-level}"
  levels:
    1:
      chance:    20      # 20% chance per hit
      cooldown:  3.0    # 3 seconds between triggers
      conditions: []
      effects:
        - "DAMAGE:2"
        - "ACTION_BAR:&6Hit!"
    2:
      chance:    25
      cooldown:  2.5
      effects:
        - "DAMAGE:4"
        - "ACTION_BAR:&6Hit!"
    3:
      chance:    30
      cooldown:  2.0
      effects:
        - "DAMAGE:6"
        - "ACTION_BAR:&6Hit!"

Triggers

A trigger defines when the enchant fires. The item must be in the correct slot (weapon in hand, armor equipped) for the trigger to detect it.

Trigger	Event	Item Slot	Notes
`ATTACK`	Player hits a player	Main hand (weapon)
`ATTACK_MOB`	Player hits a mob	Main hand (weapon)
`DEFENSE`	Player is hit by a player	Armor slots
`DEFENSE_MOB`	Player is hit by a mob	Armor slots
`MINING`	Player breaks a block	Main hand (tool)
`KILL`	Player kills a player	Main hand (weapon)
`KILL_MOB`	Player kills a mob	Main hand (weapon)
`RIGHT_CLICK`	Player right-clicks air or block	Main hand	Does not fire when applying an enchant book.

Effects

Effects are strings listed under each level. They execute in order from top to bottom.

Damage / Healing

Effect	Arguments	Description
`DAMAGE`	`<amount>`	Deal extra damage to the target (victim).
`HEAL`	`<amount>`	Heal the caster (player) by this many HP.
`HEAL_VICTIM`	`<amount>`	Heal the victim (player targets only).
`BURN`	`<ticks>`	Set the victim on fire. 20 ticks = 1 second.
`BURN_PLAYER`	`<ticks>`	Set the caster on fire.

Potions

Effect	Arguments	Description
`POTION`	`<type>:<level>:<ticks>`	Apply a potion effect to the caster.
`POTION_VICTIM`	`<type>:<level>:<ticks>`	Apply a potion effect to the victim.

Potion type names: SPEED, SLOWNESS, HASTE, STRENGTH, INSTANT_HEALTH, INSTANT_DAMAGE, JUMP_BOOST, REGENERATION, RESISTANCE, FIRE_RESISTANCE, WATER_BREATHING, INVISIBILITY, BLINDNESS, NIGHT_VISION, WEAKNESS, POISON, WITHER, LUCK, SLOW_FALLING…

Messages & UI

Effect	Arguments	Description
`MESSAGE`	`<text>`	Send a chat message to the caster. Supports `&` colors.
`MESSAGE_VICTIM`	`<text>`	Send a chat message to the victim (players only).
`ACTION_BAR`	`<text>`	Show an action bar message to the caster.
`ACTION_BAR_VICTIM`	`<text>`	Show an action bar message to the victim.

Visual / Audio

Effect	Arguments	Description
`PARTICLE`	`<type>:<count>`	Spawn particles at the caster's location. Type is any Bukkit `Particle` name (e.g. `FLAME`, `HEART`, `CRIT`).
`SOUND`	`<sound>:<volume>:<pitch>`	Play a sound for the caster. Sound is a Bukkit `Sound` name (e.g. `ENTITY_PLAYER_LEVELUP`).

Other

Effect	Arguments	Description
`COMMAND`	`<command>`	Run a console command. Use `{player}` for the triggering player's name.
`CANCEL_EVENT`	—	Cancel the triggering event (e.g. negate the incoming damage entirely).

Examples

effects:
  - "DAMAGE:4"                                  # deal 4 extra damage to victim
  - "POTION:SPEED:2:100"                        # Speed II for 5 seconds to caster
  - "POTION_VICTIM:SLOWNESS:1:60"               # Slowness I for 3 seconds to victim
  - "BURN:60"                                    # set victim on fire for 3 seconds
  - "ACTION_BAR:&6⚡ Triggered!"                 # action bar message
  - "PARTICLE:FLAME:10"                         # 10 flame particles
  - "SOUND:ENTITY_LIGHTNING_BOLT_THUNDER:0.7:1.2"
  - "COMMAND:give {player} diamond 1"           # run as console
  - "CANCEL_EVENT"                              # cancel the event

Conditions

Conditions are evaluated before effects. All conditions must pass for the effects to execute.

Condition	Description
`chance:<0-100>`	Random percent chance. Applied on top of the level's base `chance` field.
`health><value>`	Caster's health is greater than the value. Also supports `<`, `>=`, `<=`.
`victim_health><value>`	Same but for the victim.
`sneaking`	Caster must be sneaking.
`not_sneaking`	Caster must not be sneaking.
`flying`	Caster must be flying.
`not_flying`	Caster must not be flying.
`sprinting`	Caster must be sprinting.

Examples

conditions:
  - "chance:50"              # 50% chance (stacks with level chance)
  - "health>10"             # only fire if caster has more than 10 HP
  - "victim_health<8"       # only fire if victim is below 8 HP
  - "sneaking"               # caster must be sneaking

Item Patterns

The applicable-items list accepts pattern wildcards or exact material names.

Pattern	Matches
`ALL_SWORDS`	Wood/Stone/Iron/Gold/Diamond/Netherite Sword
`ALL_AXES`	Wood/Stone/Iron/Gold/Diamond/Netherite Axe
`ALL_PICKAXES`	All pickaxe types
`ALL_SHOVELS`	All shovel types
`ALL_HOES`	All hoe types
`ALL_BOWS`	Bow and Crossbow
`ALL_TOOLS`	Pickaxes + Axes + Shovels + Hoes
`ALL_HELMETS`	All helmet types
`ALL_CHESTPLATES`	All chestplate types
`ALL_LEGGINGS`	All legging types
`ALL_BOOTS`	All boot types
`ALL_ARMOR`	All four armor slots combined
`ALL`	Every item
`DIAMOND_SWORD`	Exact Bukkit material name

Full Example

This is the example.yml included with the plugin. Rename it or create a new file alongside it.

# custom-enchants/example.yml

# ── THUNDERSTRIKE ─────────────────────────────────────
#  Chance to deal bonus fire damage on hit.
thunderstrike:
  enabled:  true
  name:     "&bThunderstrike"
  rarity:   EPIC
  max-level: 3
  trigger:  ATTACK_MOB
  applicable-items:
    - ALL_SWORDS
    - ALL_AXES
  item:     ENCHANTED_BOOK
  lore:
    - "&7Chance to strike with lightning force on hit."
    - "&7Level: &e{level}&7/&e{max-level}"
  levels:
    1:
      chance:   12
      cooldown: 3.0
      conditions: []
      effects:
        - "DAMAGE:2"
        - "BURN:60"
        - "ACTION_BAR:&b⚡ Thunderstrike!"
        - "SOUND:ENTITY_LIGHTNING_BOLT_THUNDER:0.6:1.2"
    2:
      chance:   18
      cooldown: 2.5
      effects:
        - "DAMAGE:4"
        - "BURN:80"
        - "ACTION_BAR:&b⚡ Thunderstrike!"
        - "SOUND:ENTITY_LIGHTNING_BOLT_THUNDER:0.7:1.2"
    3:
      chance:   25
      cooldown: 2.0
      effects:
        - "DAMAGE:6"
        - "BURN:100"
        - "ACTION_BAR:&b⚡ Thunderstrike!"
        - "SOUND:ENTITY_LIGHTNING_BOLT_THUNDER:0.8:1.2"

# ── SWIFTNESS ─────────────────────────────────────────
#  Grants Speed when the wearer takes a hit.
swiftness:
  enabled:  true
  name:     "&aSwiftness"
  rarity:   UNCOMMON
  max-level: 2
  trigger:  DEFENSE_MOB
  applicable-items:
    - ALL_BOOTS
  item:     ENCHANTED_BOOK
  lore:
    - "&7Grants Speed when hit."
    - "&7Level: &e{level}&7/&e{max-level}"
  levels:
    1:
      chance:   100
      cooldown: 5.0
      effects:
        - "POTION:SPEED:1:80"
        - "ACTION_BAR:&aDash!"
    2:
      chance:   100
      cooldown: 4.0
      effects:
        - "POTION:SPEED:2:100"
        - "ACTION_BAR:&aDash!"

💰 Vault Integration

When Vault is detected, the plugin enables money-based rolling. Prices are pulled from costs in config.yml. Without Vault, only the XP-based roll option is shown.

⚠️

You need a Vault-compatible economy plugin (EssentialsX, CMI, etc.) in addition to Vault itself.

📊 PlaceholderAPI

When PlaceholderAPI is present, the following placeholders are registered under the rpgenchants expansion.

Placeholder	Returns
`%rpgenchants_enchants_count%`	Number of custom enchants on the player's held item.
`%rpgenchants_level_<id>%`	Level of a specific enchant on the held item, or `0`.
`%rpgenchants_has_<id>%`	`true` / `false` — whether the held item has the enchant.

RPGEnchantsPlus · Built by nasheent · Spigot / Paper 1.14 – 1.21+