EnchantLimits

Overview

EnchantLimits is the ultimate safety net for server administrators who want strict control over their server's combat balance and economy. Rather than ruthlessly deleting items that players have spent hours obtaining (which causes extreme player frustration and support tickets), EnchantLimits operates silently in the background. It mathematically caps enchantments to your defined limits, seamlessly downgrading an overpowered Sharpness X sword to a balanced Sharpness V the moment a player attempts to use it.

Real-World Use Cases

• Factions & Competitive PvP Servers: Keep combat times predictable. Prevent players from snowballing by capping Protection at IV and Sharpness at V. If an admin accidentally distributes a Sharpness X sword in a crate, it fixes itself automatically without ruining the server economy.
• Hardcore Economy Control: Completely disable game-breaking vanilla features. Set the MENDING limit to 0. This completely removes Mending from the server, forcing players to constantly spend diamonds to repair gear, fixing inflation.
• Anarchy & Semi-Vanilla Servers: Automatically neutralize hacked items. When a client exploits a backlog to spawn a "32k" weapon (an item with level 32,767 enchantments), EnchantLimits instantly scrubs it down to vanilla limits before it can be used to instantly kill players or crash the server.
• Staged Server Wipes: Slowly increase the max limits as a season progresses. Week 1: Max Sharpness III. Week 2: Max Sharpness V.

Key Features

• Hard Caps & Silent Downgrades: Safely lowers the level of an enchantment on an item instead of destroying the item entirely. Preserves the item's name, lore, and other balanced enchantments.
• Total Disabling: Setting any limit to 0 will violently rip that specific enchantment off any item in the game, completely disabling it server-wide.
• Proactive Prevention: Doesn't just scan inventories. It hooks into Anvil mechanics, Enchanting Tables, and Villager trades to physically prevent the items from being created in the first place.
• Zero TPS Impact: Built with asynchronous NBT scanning. Scanning a player's entire inventory filled with shulker boxes takes mere microseconds and won't drop server TPS.

Step-by-Step Setup Guide

Follow these exact steps to lock down your server's enchantment economy.

Step 1: Installation

1. Download the EnchantLimits.jar file.
2. Place it in your server's /plugins directory.
3. Restart your server to generate the configuration file.

Step 2: Defining the Limits

1. Open /plugins/EnchantLimits/config.yml.
2. Look at the limits: section. This is a dictionary of Bukkit Enchantment Names mapped to integers.
3. Set your desired maximums. For example, to nerf bows, set ARROW_DAMAGE: 3 (Power 3).
4. To completely ban an enchantment, such as Frost Walker, add FROST_WALKER: 0.

Step 3: Configuring the Scanner

1. Decide how aggressive the plugin should be. If you want items fixed the moment players log in, set scan-on-join: true.
2. If you want to catch items inside shulker boxes, ensure deep-scan-shulkers: true is enabled (requires a bit more CPU).

Step 4: Enforcement & Rollout

1. If you are adding this plugin to a pre-existing server, run the command /enchantlimits scanall from the console.
2. This will silently process every online player's inventory and enderchest, fixing years of economy imbalance in a single second.

Deep-Dive Mechanics

The Inventory Scanner

EnchantLimits doesn't just rely on a timer. It is highly reactive, listening to Bukkit events. The plugin scans an item's NBT data when:

• A player joins the server.
• A player picks up an item from the ground.
• A player clicks an item inside any inventory (Chests, Hoppers, Barrels, Enderchests).
• A player equips armor.
• A player deals damage (final safety check before damage is calculated).

If an item exceeds the limits, it modifies the NBT on the fly. The player might see a slight visual flicker in their inventory as the item updates.

Anvil & Crafting Interception

Downgrading items is great, but preventing their creation is better. When a player places two Sharpness V swords into an anvil, the vanilla result would be a Sharpness VI sword. EnchantLimits intercepts the PrepareAnvilEvent. If the max limit is 5, it artificially forces the output item to be Sharpness V. The player can still spend the XP to repair the item, but the enchantment will not merge upward.

Villager Trade Scrubbing

When a player interacts with a Librarian Villager, the plugin intercepts the trade list sent to the client. If the Villager is trying to sell a Mending book (and Mending is set to 0), the plugin dynamically rewrites the trade to offer a generic Book instead, or a permitted enchantment, effectively neutralizing Villager RNG exploits.

Integrations & Compatibility

Custom Enchantment Plugins

EnchantLimits is designed primarily for Vanilla enchantments. If you use plugins like EcoEnchants or ExcellentEnchants, those plugins usually handle their own limits internally. However, if they register their enchantments directly into the Bukkit Enchantment Registry, EnchantLimits CAN control them. Simply use their registered namespace key in the config (e.g., ecoenchants:telepathy: 1).

mcMMO

mcMMO sometimes relies on super-enchanted items temporarily for certain abilities (like Super Breaker). EnchantLimits is smart enough to detect temporary metadata flags added by mcMMO and will ignore those items until the ability expires.

ViaVersion / Multi-Version Servers

Because Bukkit changed the names of enchantments in version 1.13+ (e.g., DAMAGE_ALL became sharpness), EnchantLimits uses an internal smart-mapper. You can type "SHARPNESS" or "DAMAGE_ALL" in the config, and the plugin will translate it to the correct NBT data for your specific server version automatically.

Commands

There are no player commands. All commands require administrator privileges.

Permissions

Use these permission nodes in LuckPerms to control access and bypasses.

Configuration (Line-by-Line Breakdown)

The configuration file is designed to be highly specific. Read through the comments to understand exactly what each toggle does.

# EnchantLimitUI Configuration
# Version 1.1

# General Settings
debug-mode: false
# Where to show the scaled-down warning?
# Options: ACTION_BAR, CHAT
warning-location: ACTION_BAR
# If "ItemLimiter" plugin is detected, force warning to CHAT to prevent Action Bar overwrite?
auto-resolve-actionbar-conflict: true

# Sound Effects
# Use standard Bukkit Sound names: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html
sounds:
  clamp: "BLOCK_ENCHANTMENT_TABLE_USE"
  ui-click: "UI_BUTTON_CLICK"
  ui-success: "ENTITY_EXPERIENCE_ORB_PICKUP"

# Default Enchantment Limits
# Format: "namespace:key": max_level
default-limits:
  # Add limits here manually or via the /elimit GUI
  # Example: "minecraft:sharpness": 5

# Messages (MiniMessage format)
# Dynamic Placeholders:
# <prefix> - The prefix defined below
messages:
  prefix: "<gradient:#00ffee:#0099ff><bold>EnchantLimit</bold></gradient> <dark_gray>»</dark_gray> "
  
  # Sent when an item is passively downgraded (Action Bar)
  scaled-down: "<yellow>Enchantment scaled down to server max.</yellow>"
  
  # Admin Messages
  reload-success: "<prefix><green>Configuration reloaded successfully.</green>"
  no-permission: "<prefix><red>You do not have permission to use this command.</red>"
  
  # GUI Messages
  gui-set-limit: "<prefix><gray>Limit for <aqua><enchantment></aqua> set to <green><limit></green>.</gray>"

Troubleshooting & FAQ

Common Issues

• Items are not being downgraded instantly when sitting in chests.

  This is intentional by design to save server TPS. EnchantLimits does not actively scan every single block in the world. An item inside a chest is completely harmless until a player opens the chest and clicks on it. The moment they click it, it is scanned and downgraded.

• I set an enchantment to 0, but players still have it!

  Make sure you are using the exact Bukkit Enum name for the enchantment. For example, protection will fail, you must use PROTECTION_ENVIRONMENTAL. Always check your console after running /enchantlimits reload; if a name is invalid, the plugin will print a bright yellow warning telling you which name failed.

• Villagers are offering blank books instead of Mending.

  If you set Mending to 0 and cap-villager-trades: true, the plugin intercepts the trade. Because it strips the Mending enchantment away, the resulting item is just a blank book. This is normal behavior. If you want to completely remove the trade slot instead of offering a blank book, you will need a dedicated Villager modification plugin.

• Players are bypassing limits using grindstones.

  Grindstones only remove enchantments, they do not add them. Therefore, grindstones cannot be used to exceed server limits and do not need to be intercepted by the plugin.