🚫 ItemBlacklist

Permanently ban specific ItemStacks from your server — with full NBT precision.

ItemBlacklist lets you blacklist exact items (including custom names, enchantments, lore, and NBT data) and automatically purges them from player inventories in real time. No more worrying about contraband items slipping through — if it's on the list, it's gone.

---

✨ Features

• Hold-to-blacklist — add any item you're holding with a single command
• NBT-aware matching — distinguishes between items by name, lore, enchantments, and all custom data
• Multi-layer removal — items are caught on pickup, inventory interaction, hand-swap, login, and via a continuous background scan
• Named entries — every blacklisted item gets a human-readable ID you choose, making management easy
• Persistent storage — blacklist survives restarts, stored in blacklist.yml using full ItemStack serialization
• Bypass permission — grant trusted players or staff immunity from removal
• Tab completion — commands auto-complete entry IDs

---

📋 Commands

Command	Description
/itemblacklist add <id>	Blacklist the item in your main hand
/itemblacklist remove <id>	Remove a blacklist entry by ID
/itemblacklist list	List all currently blacklisted items

Alias: /ibl

---

🔐 Permissions

Permission	Default	Description
itemblacklist.manage	OP	Use all /itemblacklist commands
itemblacklist.bypass	false	Items are never removed from this player

---

🛡️ How Removal Works

ItemBlacklist uses five separate enforcement layers to ensure no blacklisted item survives:

1. Pickup cancellation — the item entity is destroyed before it ever enters an inventory
2. Inventory click interception — caught on shift-click, drag, and any cursor movement
3. Hand-swap detection — blocks F-key offhand swaps involving blacklisted items
4. Login scan — inventories are checked 5 ticks after a player joins, catching items saved to disk while offline
5. Repeating background scan — all online players are scanned every second as a safety net

---

🚀 Getting Started

1. Drop the .jar into your plugins/ folder and restart the server
2. Hold the item you want to ban
3. Run /ibl add my_item_id
4. Done — that item will now be removed from every player's inventory automatically

To undo it: /ibl remove my_item_id

---

⚙️ Config & Storage

The blacklist is saved at plugins/ItemBlacklist/blacklist.yml. Entries are stored as Base64-encoded serialized ItemStacks, preserving all item data exactly as-is. You don't need to edit this file manually — the commands handle everything.

---

🔧 Requirements

• Paper 1.21.4+ (or any fork — Purpur, Folia*)
• Java 21+

*Folia compatibility is not officially tested but may work for the listener and command portions.

---

📦 Source Code

Source is available on GitHub. Contributions and issue reports are welcome!

---