ItemLimiter

ItemLimiter is a lightweight and highly configurable Minecraft plugin that allows server owners to limit how many of a specific item a player can hold in their inventory.

It prevents players from hoarding powerful items such as Totems, Ender Pearls, Golden Apples, or any other material by enforcing a configurable maximum amount per item.

The plugin is designed to be fully configurable, lightweight, and safe, while preventing bypasses through containers, crafting, inventory manipulation, and item pickups.

---

Key Features

📦 Inventory Item Limits

Each configured item can have a maximum amount that a player may carry.

If a player attempts to exceed that amount:

• the action will be blocked
• or the excess items will automatically drop from their inventory

Example use cases:

• Limit Totems to 1
• Limit Ender Pearls to 16
• Limit Golden Apples to 8

---

🧩 Configurable Item Actions

Each item can restrict different types of interactions:

Action	Description
pickup	Prevents players from picking up additional items when the limit is reached
containers	Prevents players from taking the item out of containers
inventory	Prevents moving items into the player's inventory
craft	Prevents crafting items if the limit from their inventory would be exceeded
global	Prevents crafting items if the global limit from this item would be reached

Example config:

{
  "TOTEM_OF_UNDYING": {
    "limit": 1,
    "action": ["pickup", "containers", "inventory"]
  },
  "ENDER_PEARL": {
    "limit": 16,
    "action": ["pickup"]
  }
  "MACE": {
    "limit": 1,
    "action": ["global"]
  }
}

Limits are based on total items in the player's inventory/global crafting.

---

🛡️ Smart Limit Enforcement

If a player already exceeds a limit, for example after plugin installation or configuration changes, the plugin will automatically:

1. Detect the excess items
2. Remove them from the player's inventory
3. Drop them naturally on the ground

This prevents players from bypassing limits with previously stored items.

---

📦 Container-Friendly Logic

Players can still store items in containers without restriction.

Allowed:

• Inventory to chest using shift-click
• Inventory to shulker boxes
• Inventory to bundles

Blocked when limit is reached:

• Chest to inventory
• Bundle to inventory
• Hopper to inventory

This ensures players can store items but cannot exceed their personal limit.

---

⚙️ Fully Configurable

The plugin uses Bukkit material names and JSON configuration.

Structure:

plugins/ItemLimiter/

config.json
config-examples.txt

translations/
  messages.json

Features include:

• Editable messages
• Configurable item limits
• Configurable actions per item
• Built-in documentation examples

---

🔄 Hot Reload Support

You can reload the configuration and translation files without restarting the server.

/itemlimiter reload

If configuration files are missing, the plugin will automatically recreate them.

---

Commands

Command	Description
/itemlimiter help	Displays all plugin commands
/itemlimiter list [page]	Lists configured item limits
/itemlimiter info <material>	Shows information about an item
/itemlimiter check <material>	Shows how many items you currently have
/itemlimiter add <material> <limit> <actions>	Adds a new item limit
/itemlimiter edit <material> <limit> <actions>	Edits an existing item
/itemlimiter remove <material>	Removes an item limit
/itemlimiter reload	Reloads plugin configuration

---

Permissions

Permission	Description	Default
itemlimiter.help	Allows /itemlimiter help	true
itemlimiter.info	Allows /itemlimiter info	op
itemlimiter.list	Allows /itemlimiter list	op
itemlimiter.check	Allows /itemlimiter check	op
`itemlimiter.globalcheck	Allows `/itemlimiter globalcheck	op
itemlimiter.reload	Allows /itemlimiter reload	op
itemlimiter.add	Allows adding new item limits	op
itemlimiter.edit	Allows editing item limits	op
itemlimiter.remove	Allows removing item limits	op
itemlimiter.update.notify	Allows receiving update notifications	op

---

Why Use ItemLimiter?

Many servers suffer from item hoarding or stacking issues, such as:

• Carrying dozens of Totems
• Excessive Ender Pearl stacking
• Golden Apple hoarding
• Item imbalance in PvP or survival

ItemLimiter provides a clean and configurable way to balance gameplay without restricting storage.

---

Compatibility

• Minecraft 1.20+
• Spigot / Paper
• Lightweight with minimal performance impact

---

Example Use Cases

Common items servers limit:

TOTEM_OF_UNDYING
ENDER_PEARL
ELYTRA
MACE
GOLDEN_APPLE
ENCHANTED_GOLDEN_APPLE
SHIELD
TRIDENT

---

Configuration Philosophy

ItemLimiter is designed to be:

• Simple
• Flexible
• Server-friendly

You decide which items, how many players can carry, and which interactions are restricted.

---

Support

If you encounter issues or have feature requests, feel free to open a ticket in the Discord server.

Enjoy a balanced and controlled inventory system for your server.