BanItem - 轻量跨世界物品封禁插件

BanItem 是一款简单、强大、轻量且高度可配置的插件，它允许服务器管理员针对特定世界、特定物品和特定操作（如放置、使用、合成等）设置禁令，并支持精细的权限控制。

💡核心特性

BanItem 提供了两种主要模式来管理物品使用：

• 黑名单模式：默认模式。在此模式下，玩家将无法对配置中指定的物品执行被禁止的操作。
• 白名单模式（反向黑名单）：在此模式下，所有物品和操作默认都被禁止。你需要在配置中明确指定哪些物品的哪些操作是被允许的。

插件的主要特点包括

• 支持按世界配置禁令规则。
• 支持按世界、按物品、按操作的精细权限控制。
• 支持元物品（匹配具有特定元数据的物品，如药水、附魔物品等）。
• 可以创建和筛选自定义物品。
• 提供实用的管理命令。
• 代码轻量，只激活必要的监听器。
• 提供开发者 API。
• 完整文档位于：https://banitem.andross.fr/

🎮可禁止的操作

插件支持禁止以下多种物品交互行为（部分操作需要特定 Minecraft 版本）：

• Armorstandplace：尝试将物品放置在盔甲架上。（MC>=1.8）
• Armorstandtake：尝试从盔甲架上取下物品。（MC>=1.8）
• Attack：用主手物品左键攻击实体。
• Bookedit：编辑或签署书与笔。
• Break：破坏物品（方块）。
• Brew：在酿造台中酿造药水。
• Click：用主手物品左键点击。
• Consume：尝试食用食物或饮用药水。
• Craft：使物品无法被合成。
• Crafter：使物品无法被制作者方块合成。（MC>=1.21）
• Delete：当玩家打开并关闭一个容器时，检查并删除具有此禁令标记的物品。
• Dispense：物品从发射器/投掷器中射出。
• Drop：玩家丢弃物品。
• Drops：方块被破坏时掉落物品。
• Enchant：尝试附魔物品。
• Entitydrop：实体死亡时掉落物品。
• Entityinteract：用物品右键点击实体。
• Fill：用物品（如桶）右键点击流体（水/岩浆）。
• Glide：尝试使用（激活）鞘翅。（MC>=1.9）
• Hangingplace：尝试放置悬挂实体（物品展示框、画等）。
• Hold：尝试将物品拿在手中。
• Interact：用主手右键点击已放置的物品（如打开箱子）。
• Inventoryclick：在容器界面中点击物品。
• Mending：通过经验修补附魔修复物品。（MC>=1.13）
• Pickup：拾取物品。
• Place：放置物品（方块）。
• Rename：在铁砧或通过命令重命名物品。
• Smelt：使物品无法被熔炼。
• Smith：在锻造台完成物品的合成配方。（MC>=1.16）
• Swap：尝试交换双手的物品。（MC>=1.9）
• Sweepingedge：用带有横扫之刃附魔的物品攻击实体（横扫伤害将被取消，原始攻击继续）。
• Transfer：尝试将物品从一个容器转移到另一个容器。
• Unfill：尝试清空桶（如收集水）。
• Use：尝试使用物品（右键点击）。
• Wear：尝试将物品作为盔甲穿上（通常需要同时禁止 place 操作）。

🔧配置指南

配置文件 (config.yml) 结构清晰且功能强大。以下是一些关键概念：

基本结构

禁令规则在 blacklist（黑名单）或 whitelist（白名单）节点下配置。

• 世界：可以指定单个世界、多个世界（用逗号分隔）、所有世界（）、所有世界除某些外（, !world_the_end）或使用正则表达式（以 # 开头，如 #world）。
• 物品：使用 Material 名称。格式与世界类似，支持单个、多个、所有（*，包括空手）、所有除某些外以及正则表达式。
• 操作：使用上述操作名称。格式同上。

操作数据

每个禁令操作可以附加额外的检查数据，例如

• cooldown：设置操作冷却时间（毫秒）。
• entity：指定相关的实体类型。
• gamemode：仅在玩家处于特定游戏模式时生效。
• inventory-from / inventory-to：指定物品转移的源容器和目标容器类型。
• material：检查玩家手中或相关的另一个物品。
• permission：检查玩家是否拥有特定权限。
• log：设置为 true 时，拥有 /banitem log 权限的玩家会收到该禁令触发的消息。
• message：当禁令触发时发送给玩家的消息。
• placeholderapi_condition：当 PlaceholderAPI 的某个值匹配时才生效。
• region：指定 WorldGuard 区域。
• run：禁令触发时执行的控制台命令列表（支持 {player}, {world}, {itemname} 变量）。

配置示例

blacklist:
  world:
    diamond_block:
      place: '&cYou are not allowed to place a diamond block in world.'
      break: '&cYou are not allowed to break a diamond block in world.'
    stick:
      entityinteract:
        entity: item_frame
        message: '&cYou can not put a stick into an itemframe!'
        log: true
  '*, !world_the_end':
    ender_pearl:
      use: '&cYou can use enderpearls only in the end.'

whitelist:
  world_the_end:
    message: '&cOnly thing allowed in this world: placing dirt.'
    ignored: 'interact'
    dirt: place

✨权限系统

BanItem 的权限系统非常精细，可以精确控制对特定世界、物品、操作和数据的绕过。

绕过权限

格式：banitem.bypass.<世界名>.<物品名>.<操作名>.<数据名>

• 使用 allworlds 代表所有世界。
• 使用 allitems 代表所有物品。
• 使用 * 作为通配符。

**示例**

• banitem.bypass.allworlds.stone.place.*：允许玩家在所有世界放置石头。
• banitem.bypass.*：绕过所有禁令。
• banitem.bypass.world_nether.allitems：允许玩家在地狱世界对所有物品进行所有操作。

命令权限

• banitem.command.add
• banitem.command.check
• banitem.command.help
• banitem.command.info
• banitem.command.load
• banitem.command.log
• banitem.command.metaitem
• banitem.command.reload
• banitem.command.remove

⭐命令列表

• /banitem add <actions> [-m materials] [-w worlds] [message]

将你手中的物品（不含元数据）在当前世界加入禁令。可指定操作、材料、世界和提示信息。

• /banitem check [delete]

列出所有玩家库存中存在的黑名单物品（按世界规则）。使用 delete 参数同时删除这些物品。

• /banitem metaitem 或 /bi mi
• /bi mi add <name> [action] [message]：将手中的物品（包含元数据）保存为自定义元物品并可选设置禁令。
• /bi mi get <name>：获取指定名称的元物品到你的库存。
• /bi mi list：列出所有已定义的元物品。
• /bi mi remove <name>：移除指定的元物品。
• /banitem help [type]

获取关于指定类型（worlds, actions, entities, gamemodes, inventories）的详细信息。

• /banitem info [debug]

获取手中物品的信息（例如在配置中使用的材料名称）。

• /banitem load <filename>

加载指定的配置文件。

• /banitem log

切换日志模式。拥有此权限的玩家会收到所有标记了 log: true 的禁令触发信息。

• /banitem reload 或 /bi rl

重载 config.yml 配置文件。

• /banitem remove [-m materials] [-w worlds]

解除你手中物品的禁令。

❓使用自定义物品

你可以创建具有特定属性（如附魔、药水效果）的自定义物品进行管理。

步骤

• 在 customitems.yml 中定义自定义物品：

customItemName:
  material: DIAMOND_SWORD
  enchantment-contains: 'unbreaking:3'

• 在 config.yml 的黑名单中引用它：

blacklist:
  world:
    customItemName:
      attack: '&cYou can not attack with this sword.'

完成！玩家将无法使用任何带有“耐久 III”附魔的钻石剑进行攻击。

🔧开发者 API

重要提示：BanItem 的数据库会在下一个可用的服务器 tick 加载，以便让其他插件（如世界管理、物品管理插件）先完成加载。因此，在插件启动时直接调用 API 可能会得到空数据库。建议在延迟 2-3 秒的任务中加载你的插件逻辑。

获取 API 实例

// 方法一：通过 PluginManager
final BanItem banItem = (BanItem) getServer().getPluginManager().getPlugin("BanItem");
final BanItemAPI banItemApi = banItem.getApi();

// 方法二：直接通过 API 单例
final BanItemAPI banItemApi = BanItemAPI.getInstance();

// 方法三：通过 BanItem 实例
final BanItemAPI banItemApi = BanItem.getInstance().getApi();

API 事件

• PlayerBanItemEvent：当一个物品/操作即将被禁止时触发，可取消。
• DeleteBannedItemEvent：当一个物品即将被 delete 操作删除时触发，可取消。

💡支持与致谢

感谢所有支持者！如果你喜欢这个插件，请给它评分和/或留下评论！

你也可以请开发者喝杯咖啡以示支持。

完整文档：https://banitem.andross.fr/

如有任何漏洞、问题或建议，请通过 SpigotMC 站内信或 Discord (andross96) 联系我。