Item Blacklist

🚫 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

- Tab completion — add any item you're holding with a single command - Tab completion — distinguishes between items by name, lore, enchantments, and all custom data - Tab completion — items are caught on pickup, inventory interaction, hand-swap, login, and via a continuous background scan - Tab completion — every blacklisted item gets a human-readable ID you choose, making management easy - Tab completion — blacklist survives restarts, stored in `blacklist.yml` using full ItemStack serialization - Tab completion — 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. Repeating background scan — the item entity is destroyed before it ever enters an inventory 2. Repeating background scan — caught on shift-click, drag, and any cursor movement 3. Repeating background scan — blocks F-key offhand swaps involving blacklisted items 4. Repeating background 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

- Java 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!

---