? ItemBlacklist
永久禁止特定物品堆栈进入你的服务器 —— 支持完整的 NBT 精度。
ItemBlacklist 允许你屏蔽精确的物品(包括自定义名称、附魔、描述和 NBT 数据),并实时自动将其从玩家背包中清除。再也不用担心违禁品漏网——只要在名单上,就会被移除。
✨ 功能特性
- 按住即屏蔽 — 只需一条命令即可将你手持的任意物品加入黑名单
- NBT 感知匹配 — 能够根据名称、描述、附魔以及所有自定义数据区分物品
- 多层级清除 — 物品在拾取、背包交互、副手切换、登录时均会被拦截,并通过持续后台扫描进行兜底
- 命名条目 — 每个被屏蔽的物品都拥有你自定义的人类可读 ID,便于管理
- 持久化存储 — 黑名单在重启后依然存在,使用完整的 ItemStack 序列化存储在
blacklist.yml 中
- 豁免权限 — 可为受信任的玩家或管理员授予免受清除的免疫权
- Tab 补全 — 命令支持输入条目的 ID 自动补全
? 命令
| 命令 |
描述 |
/itemblacklist add <id> |
将主手持有的物品加入黑名单 |
/itemblacklist remove <id> |
通过 ID 移除黑名单条目 |
/itemblacklist list |
列出当前所有被屏蔽的物品 |
别名: /ibl
? 权限
| 权限节点 |
默认值 |
描述 |
itemblacklist.manage |
OP |
使用所有 /itemblacklist 命令 |
itemblacklist.bypass |
false |
该玩家的物品永远不会被移除 |
?️ 清除机制
ItemBlacklist 使用五个独立的执行层级来确保没有任何黑名单物品能幸存:
- 拾取取消 — 物品实体在进入任何背包之前即被销毁
- 背包点击拦截 — 在 Shift 点击、拖拽以及任何光标移动时被捕获
- 副手切换检测 — 阻止涉及黑名单物品的 F 键副手切换操作
- 登录扫描 — 玩家加入游戏 5 刻后检查背包,捕获离线期间保存至磁盘的物品
- 重复后台扫描 — 每秒扫描所有在线玩家作为安全网
? 快速开始
- 将
.jar 文件放入 plugins/ 文件夹并重启服务器
- 手持你想要禁止的物品
- 运行
/ibl add my_item_id
- 完成 —— 该物品现在会自动从所有玩家的背包中移除
若要撤销:/ibl remove my_item_id
⚙️ 配置与存储
黑名单保存在 plugins/ItemBlacklist/blacklist.yml。条目以 Base64 编码的序列化 ItemStack 形式存储,完整保留所有物品数据。无需手动编辑此文件 —— 命令即可处理一切。
? 依赖要求
- Paper 1.21.4+(或其分支 —— Purpur、Folia*)
- Java 21+
*Folia 兼容性未经官方测试,但监听器和命令部分可能可用。
? 源代码
源码可在 GitHub 获取。欢迎贡献代码和报告问题!
? 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:
- Pickup cancellation — the item entity is destroyed before it ever enters an inventory
- Inventory click interception — caught on shift-click, drag, and any cursor movement
- Hand-swap detection — blocks F-key offhand swaps involving blacklisted items
- Login scan — inventories are checked 5 ticks after a player joins, catching items saved to disk while offline
- Repeating background scan — all online players are scanned every second as a safety net
? Getting Started
- Drop the
.jar into your plugins/ folder and restart the server
- Hold the item you want to ban
- Run
/ibl add my_item_id
- 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!
评论 0
登录后参与评分
还没有评论,来抢沙发吧