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 carry, store, pick up, move, or craft.

It helps prevent players from hoarding powerful items such as Totems, Ender Pearls, Golden Apples, Maces, or any other material by enforcing configurable limits per item.

The plugin is designed to be fully configurable, lightweight, and safe, while preventing bypasses through containers, bundles, 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 more of an item when the limit is reached
containers	Handles container-related limits, including taking items from containers and limiting how many can be stored in supported containers
inventory	Prevents moving items into the player's inventory when the limit would be exceeded
craft	Prevents crafting items if the player's inventory limit would be exceeded
global	Prevents crafting items if the player's lifetime/global crafted limit would be exceeded

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 the configured action. Inventory-based limits count items in the player's inventory, including bundle contents where applicable. Global limits track crafted totals per player and material.

---

Separate Container Storage Limits

The containers action can also limit how many of an item may be stored inside supported containers.

To use a separate storage-container limit for the same material, use the seperate flag:

/itemlimiter add TOTEM_OF_UNDYING 0 containers seperate

This creates a separate config entry:

{
  "TOTEM_OF_UNDYING": {
    "limit": 1,
    "action": ["pickup", "inventory"]
  },
  "TOTEM_OF_UNDYING#containers": {
    "limit": 0,
    "action": ["containers"]
  }
}

This allows players to carry 1 Totem while preventing Totems from being stored in containers.

Supported storage containers include:

Chests
Barrels
Shulker Boxes
Hoppers
Droppers
Dispensers
Furnaces
Smokers
Blast Furnaces
Crafters
Brewing Stands
Decorated Pots
Chiseled Bookshelves
Jukeboxes
Lecterns
Ender Chests

---

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 held items.

---

Container-Friendly Logic

Players can still store items in containers unless you configure a separate container storage limit.

Allowed by default:

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

Blocked when a personal limit is reached:

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

Blocked when a container storage limit is reached:

• Adding more than the allowed amount into supported containers
• Using hotbar keys or offhand swaps to bypass container limits

---

Global Craft Limits

The global action tracks how many times each player has crafted a configured item over time.

Global craft totals are stored persistently in:

crafted-limits.db

You can check your global crafted amount with:

/itemlimiter globalcheck <material>

Crafter block crafting is blocked for items using craft or global, because automated crafting cannot be reliably linked to a player for database tracking.

---

Fully Configurable

The plugin uses Bukkit material names and JSON configuration.

Structure:

plugins/ItemLimiter/

config.json
config-examples.txt
crafted-limits.db

translations/
  messages.json

Features include:

• Editable messages
• Configurable item limits
• Configurable actions per item
• Configurable global limit announcements
• 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 globalcheck <material>	Shows your global crafted amount for an item
/itemlimiter add <material> <limit> <actions> [seperate]	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	true
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.bypass	Bypasses all item limits	false
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
• Storing restricted items inside containers

ItemLimiter provides a clean and configurable way to balance gameplay while still letting server owners decide exactly what should be restricted.

---

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 or store, 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.