ItemBlocker

插件

· 作者 kuqk

适用于 Paper、Folia、Purpur 和 Spigot 的物品、附魔与药水效果限制

0 本站下载 0 关注 更新于 1 周前

最新 2.6.3 · 26.3 · Folia / Paper

一键开服(送7天)
ItemBlocker

Folia

适用于 Paper、Folia、Purpur 和 Spigot 的 Minecraft 1.17 至 26.3 版本的物品、附魔与药水效果限制插件。

阅读完整文档 以了解每条规则、命令、权限及设置的详细信息。

  • 针对合成、拾取、丢弃、使用、放置、穿戴、背包、漏斗和锻造台等操作限制物品。
  • 从指定等级起限制附魔和药水效果。
  • 限制物品的堆叠上限以及玩家可携带的数量。
  • 整组限制特定类型的物品(例如所有剑),同时允许其中少数几种。
  • 提供 API 供其他插件调用:检查规则、添加临时规则或放行被拦截的操作。
  • 将每次被拦截的操作记录到文件中,并可选择发送至 Discord 频道。
  • 查找玩家或容器中已存在的违禁物品,并将其移除或没收。
  • 通过权限让某个角色组忽略单条规则或整个预设配置。
  • 根据名称、描述(lore)、自定义模型数据、插件数据或附魔等条件,精确限制单个特定物品(例如来自 RPG 插件的剑)。
  • 将规则分组为预设配置,并将任意规则或预设限定于特定世界,或将预设限定于 WorldGuard 区域。
  • 支持通过菜单(/ib gui)、命令配合自动补全功能,或在单个 YAML 文件中进行全面管理。
  • 提供英语、波兰语、德语、西班牙语、法语和意大利语的消息提示,并兼容 PlaceholderAPI 占位符。

安装方法

  1. 从 Modrinth、Hangar 或 发布页面 下载 jar 文件。
  2. 将其放入 plugins/ 目录并启动服务器。
  3. 开始设置限制:执行 /ib block tnt actions:place。

ItemBlocker 运行在 Java 16 或更高版本上,因此它能适配你服务器当前使用的任何 Java 版本。

工作原理

规则存在于预设(presets)中。default 预设始终存在且应用于所有世界。你可以为不同世界、活动或游戏模式创建更多预设,并为每个预设设定独立的拦截提示信息原因。

一个预设可以限制以下内容:

  • 物品:针对具体操作进行限制。物品规则可限定于特定世界。
  • 附魔:从指定等级起生效。每种附魔都有一种处理模式,用于定义携带该附魔的物品会被如何处理: block(默认):该物品在所有操作中均被拦截,附魔台不再提供该附魔选项,铁砧也无法生成带有该附魔的物品; downgrade:附魔等级降低至最高允许等级。例如,若 Sharpness(锋利)从 5 级起被限制,则锋利 V 的剑会自动降级为锋利 IV; remove:移除该附魔; confiscate:收回该物品并存入 /ib confiscated 列表中。 当玩家拥有这些物品时,系统会立即修复它们:包括加入服务器、拾取、背包点击和附魔之后。可通过 mode: 参数设置模式,例如 /ib block enchantment sharpness level:5 mode:downgrade,或在菜单中按住 Shift 并左键点击。
  • 药水效果:从指定等级起生效。效果不会被应用,玩家在加入服务器或切换世界时会失去该效果。
  • 物品组:匹配特定模式的所有物品类型,如 *_sword、netherite_* 或物品标签 #swords,其作用范围和操作类型与物品规则相同。
  • 允许的物品:该预设中的物品规则和物品组永远不会拦截的物品类型。例如,在一个禁止所有剑的规则组中,可将 wooden_sword(木剑)设为例外。
  • 物品过滤器:根据物品名称或描述中的文本、自定义模型数据、持久化数据条目(Nexo、Oraxen 或 ExecutableItems 等插件标记其物品的方式)或附魔来匹配特定物品。每种条件都必须同时满足才能匹配成功。物品过滤器的优先级低于按物品类型定义的规则。
  • 物品数量限制:限制物品的最大堆叠数和玩家可持有的最大数量。如果多个预设对同一物品设置了限制,则以最小的限制值为准。
行为 方块
crafting 从合成结果中取出物品
pickup 拾取物品
drop 丢弃物品
use 右键点击使用物品,或食用/饮用它
place 将其放置为方块、作为桶清空液体,或将其放置为实体(船、矿车、盔甲架、物品展示框、画、末影水晶)
armor 穿戴它,无论以何种方式穿戴。当玩家加入服务器或切换世界时,被阻挡的装备会被脱下
inventory 将其移动进或移出箱子及其他容器
hopper 漏斗移动或拾取它
smithing 从锻造台获得它
attack 手持该物品攻击生物或玩家
break 将其作为方块破坏,或手持它作为工具破坏任意方块
crafter 由工匠方块(1.21+)制作它
dispense 发射器和投掷器使用它
brew 由酿造台制作它。预设方块效果下的药水也不会被酿造
trade 从村民或流浪商人处获得它
loot 出现在箱子及其他生成的战利品中;其余的战利品保持不变
entity_drop 生物死亡时掉落它。玩家总是掉落自己的物品

obtain 代表获取物品的所有方式:crafting、crafter、smithing、brew、trade、loot、entity_drop 和 pickup。使用它可以让玩家保留并使用某物品,但无法再获取更多,例如 /ib block mace actions:obtain。

限制条件保持如下:玩家仅能拾取他们能够携带且符合堆叠限制数量的物品,尝试从容器中取出更多数量将被拒绝。任何超出限制的情况(例如通过合成产生),都会立即修正:超过限制的堆叠会被拆分到空闲槽位,而剩余无法容纳或超出背包上限的物品会掉落在玩家脚下。物品永远不会被删除。

命令

命令为 /itemblocker,或简写为 /ib。每个命令都支持 Tab 补全。

/ib block <item|hand> [actions:...] [worlds:...] [in:preset]
/ib block enchantment <name> [level:n] [mode:block|downgrade|remove|confiscate] [in:preset]
/ib block potion <effect> [level:n] [in:preset]
/ib edit <item|hand> [actions:...] [worlds:...] [in:preset]
/ib limit <item|hand> [stack:n|none] [inventory:n|none] [in:preset]
/ib filter add <id> [hand] [type:] [name:] [lore:] [model:] [data:] [enchantment:] [actions:] [worlds:] [in:preset]
/ib filter remove <id> [in:preset]
/ib filter list [in:preset]
/ib group add <pattern> [actions:...] [worlds:...] [bypass:...] [in:preset]
/ib group remove <pattern> [in:preset]
/ib group list [in:preset]
/ib allow add|remove <item|hand> [in:preset]
/ib allow list [in:preset]
/ib scan players|containers [remove|confiscate] [actions:...] [radius:n] [world:name]
/ib confiscated [take <owner>]
/ib log [player]
/ib unblock <item|hand|enchantment|potion> [name] [in:preset]
/ib show <item|hand|enchantment|potion> [name]
/ib list [items|limits|enchantments|potions] [in:preset]
/ib preset list | show <name> | create <name> | delete <name>
/ib preset edit <name> <description|reason|worlds|regions> [value]
/ib template [name] [as:preset]
/ib gui
/ib reload
  • actions: 接受一个逗号分隔的列表,可以是 all 或 obtain,例如 actions:place,use。如果不提供此参数,则阻止所有行为。
  • worlds: 接受一个逗号分隔的列表或 all,例如 worlds:world,world_nether。
  • stack: 和 inventory: 分别设置最大堆叠数量和玩家可携带的最大数量,none 表示移除限制。未提供的选项将保留其原有值。
  • 在 /ib filter add 中,hand 会复制手中物品的类型、自定义名称、自定义模型数据和插件数据;你添加的选项将替换所复制的内容。包含空格的值需用双引号括起来,例如 name:"Sword of Kings"。data: 接受键名或 key=value 格式,如 data:nexo:id=ruby_sword。
  • bypass: 指定一个权限名,使玩家仅能忽略该条规则,例如 bypass:vip.elytra;bypass:none 用于移除绕过权限。它适用于 block、edit、filter add 和 group add。
  • in: 选择预设。如果不提供,则使用 default 预设。
  • block 会在现有规则基础上追加,edit 仅替换你提供的部分。
  • hand 指代主手中的物品。

示例:

/ib block tnt actions:place,crafting
/ib block elytra actions:armor worlds:world_the_end
/ib block enchantment sharpness level:5
/ib limit ender_pearl stack:4 inventory:16
/ib filter add excalibur hand actions:use,drop
/ib filter add soulbound lore:Soulbound actions:drop
/ib group add *_sword actions:use in:pvp
/ib allow add wooden_sword in:pvp
/ib block elytra actions:armor bypass:vip.elytra
/ib preset create pvp
/ib preset edit pvp worlds arena
/ib block potion strength level:2 in:pvp
/ib preset create spawn
/ib preset edit spawn regions spawn,market

集成

以下两个集成均为可选。ItemBlocker 会在安装这些插件时与之挂钩,并在没有它们的情况下照常工作。

  • WorldGuard:使用 /ib preset edit <name> regions <region,...> 将预设限制在特定区域。此后,该预设仅在那些区域内生效,并且仍然仅限于其指定的世界中。regions all 用于移除区域限制。如果没有 WorldGuard,那么限制在区域的预设将不会在任何地方生效。
  • PlaceholderAPI:占位符(如 %player_name%)可用于发送给玩家的每条消息中。

权限系统兼容任何权限插件(如 LuckPerms),包括基于世界和服务器的上下文权限。

模板

/ib template 列出预设好的模板,/ib template <name> [as:<preset>] 可创建其中一个,菜单中的模板按钮也可实现相同功能。它们是起点;你可以像编辑其他预设一样修改它们。

  • survival:阻止生存模式获取仅创造模式或管理员可用的物品(基岩、壁垒方块、命令方块、结构方块、调试棒等)。
  • lifesteal:禁止末影水晶和重生锚,限用 1 个不死图腾和 1 个附魔金苹果,锋利 V 和保护 IV 等级降低,移除荆棘,禁止力量 II,禁止新增的战锤。
  • pvp:禁止末影水晶、重生锚和 TNT,禁止使用战锤攻击,限用 1 个不死图腾,锋利 V 和力量 V 等级降低,禁止力量 III 和抗性提升 III。

扫描现有物品

规则仅阻止新操作。在规则存在之前玩家已获得的物品仍保留在原处,因此 /ib scan 可以找到它们:

  • /ib scan players 检查所有在线玩家的背包和末影箱。
  • /ib scan containers 检查你周围加载区块中的箱子、 barrels、潜影盒和其他容器(radius: 区块,默认为 4),或使用 world:<name> 检查整个世界。
  • 不带其他参数时,它仅报告找到的内容。添加 remove 可删除这些物品,或添加 confiscate 将其移至 confiscated.yml。/ib confiscated 按所有者列出这些物品,而 /ib confiscated take <owner> 将它们交给你。
  • 如果玩家无法拾取该物品或携带了被禁用的附魔,则该物品被视为禁止物品。使用 actions: 统计其他动作,例如 actions:use,place。玩家自身的绕过权限适用。

日志和 Discord 警报

每个被阻止的操作都会写入 plugins/ItemBlocker/logs/<date>.log,每行一条:

2026-11-02 17:40:01 | Steve | place | TNT | world | default

/ib log 显示最近十条,/ib log <player> 显示单个玩家的记录。如果在持有一个被阻止的物品后一秒钟内再次点击,则仅记录一次。

要在 Discord 上接收警报,请在频道设置中创建一个 Webhook,并将其 URL 放入 config.yml:

log:
  enabled: true
  discord:
    webhook: "https://discord.com/api/webhooks/..."
    cooldown-seconds: 60   # 每分钟每个玩家、每个动作和每个物品一条警报

警报永远不会 ping 任何人,即使物品名称为 @everyone。

菜单

/ib gui 允许你无需输入命令即可设置几乎所有内容。它列出了每个预设,并提供按钮来创建新的预设或从模板(Survival、Lifesteal、PvP)开始。一个预设会打开包含以下部分的菜单:

  • Items:具有规则或限制的所有物品。在你的背包中点击一个物品或搜索所有物品以添加一个,点击条目以编辑它,Shift + 右键点击以移除它。
  • Item groups:通过在聊天中输入诸如 *_sword 或 #swords 这样的模式来添加组。
  • Item filters:在你的背包中点击一个物品;过滤器以其命名并复制其类型、名称、模型数据和插件数据。
  • Allowed items:在你的背包中点击一个物品以允许它,点击条目以移除它。
  • Enchantments 和 Potion effects:左键点击提高禁用等级,右键点击降低等级,Shift + 右键点击解除禁用。对于附魔,Shift + 左键点击更改模式。
  • Settings:描述、原因,以及从列表中选择的世界和 WorldGuard 区域。除 default 之外的预设可以通过 Shift + 右键点击删除。

物品、组和过滤器的规则编辑器切换每个动作,并设置世界和绕过权限。对于物品,它还设置堆叠和背包限制(左键点击 +1,右键点击 -1,Shift 表示步长为 16),对于过滤器,设置每个标准:类型、名称、lore、模型数据、插件数据和附魔。

在世界选择方面,所有内容均从列表中选择。当菜单需要自由文本时,例如名称、模式、权限或搜索,它会关闭并要求你在聊天中输入;你的消息不会显示给其他人。在该消息中点击 cancel,或输入它或你语言文件中的单词如 anuluj,以不更改任何内容返回,或输入 none 以清除值。每次更改都会立即保存。

权限

Permission Allows Default
itemblocker.use 使用 /ib 的所有功能 op
itemblocker.add 对物品使用 /ib block op
itemblocker.edit /ib edit op
itemblocker.limit /ib limit op
itemblocker.filter /ib filter op
itemblocker.group /ib group op
itemblocker.allow /ib allow op
itemblocker.scan /ib scan 和 /ib confiscated op
itemblocker.log /ib log op
itemblocker.remove 对物品使用 /ib unblock op
itemblocker.enchantment 禁用和启用附魔 op
itemblocker.potion 禁用和启用药水效果 op
itemblocker.info /ib show 和 /ib preset show op
itemblocker.list /ib list 和 /ib preset list op
itemblocker.preset 创建、编辑和删除预设 op
itemblocker.reload /ib reload op
itemblocker.gui /ib gui op
itemblocker.admin 以上所有功能 op
itemblocker.bypass 忽略所有限制 op
itemblocker.bypass.<action> 忽略单个动作,例如 itemblocker.bypass.place no
itemblocker.bypass.enchantment 忽略附魔限制 no
itemblocker.bypass.potion 忽略药水效果限制 no
itemblocker.bypass.limit 忽略堆叠和背包限制 no
itemblocker.bypass.preset.<name> 忽略单个预设,例如 itemblocker.bypass.preset.pvp no
any permission set with bypass: 忽略该特定规则 no

预设和规则权限仅在明确授予时才有效,例如通过权限插件,因此操作员不会仅仅因为他们是操作员而获得这些权限。操作员默认情况下可以绕过所有限制。请使用非操作员玩家测试你的规则,或在 config.yml 中设置 bypass.enabled: false 和 bypass.per-action: false 并运行 /ib reload。

配置

config.yml

language: en          # 支持的语言:en(英语)、pl(波兰语)、de(德语)、es(西班牙语)、fr(法语)或 it(意大利语);消息文件位于 lang 文件夹中
messages:
  cooldown-ms: 1000   # 向同一玩家发送两次区块/物品消息之间的最小间隔时间(毫秒)
bypass:
  enabled: true       # itemblocker.bypass 权限将跳过所有限制
  per-action: true    # itemblocker.bypass.<action> 权限将跳过特定类型的限制

rules.yml

该文件由命令生成,但你也可以手动编辑它并运行 /ib reload 来重新加载。

presets:
  default:
    description: ''
    reason: '&c此物品在此服务器上被禁用'
    worlds: all
    regions: all
    items:
      tnt:
        actions:
        - place
        - crafting
        worlds: all
    limits:
      ender_pearl:
        stack: 4
        inventory: 16
    filters:
      excalibur:
        type: diamond_sword
        name: Excalibur
        data: nexo:id=excalibur
        actions:
        - use
        worlds: all
    enchantments:
      sharpness:
        level: 5
        mode: downgrade
      thorns: 1
    potions: {}
  pvp:
    description: Arena rules
    reason: ''
    worlds:
    - arena
    regions: all
    items:
      ender_pearl:
        actions: all
        worlds: all
    enchantments: {}
    potions:
      strength: 2

如果 rules.yml 存在 YAML 语法错误,之前的规则仍将保持生效,并且命令会拒绝修改它们,直到文件修复并重新加载。因此,你的手动编辑永远不会被命令覆盖。

Messages

消息文件位于 plugins/ItemBlocker/lang/ 目录下。它们支持 & 颜色代码、十六进制颜色代码(如 &#ff8800),并且在安装了 PlaceholderAPI 的情况下还支持其占位符。如果你删除了某些条目,系统将回退到内置的默认文本,因此你只需保留那些你希望修改的条目即可。要添加一种新语言,请将 en.yml 复制为例如 nl.yml,并在配置文件中设置 language: nl。

其他插件的 API

通过 JitPack 添加 ItemBlocker,并在你的 plugin.yml 中声明依赖项 depend: [ItemBlocker] 或 softdepend: [ItemBlocker]:

repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.kuqk:ItemBlocker:v2.6.3")
}
ItemBlockerApi api = ItemBlockerApi.get();

// 检查该物品在此处对该玩家是否被阻止?
api.check(player, item, Action.USE).ifPresent(restriction ->
        player.sendMessage("Blocked by " + restriction.preset()));

// 在任务期间为一位玩家临时阻止末影珍珠,然后再解除限制。
TemporaryRule rule = api.blockTemporarily(player, Material.ENDER_PEARL, Set.of(Action.USE), "Not during the quest");
rule.remove();
  • check 和 isBlocked 方法与插件本身使用相同的规则、权限和例外设置。
  • blockTemporarily 会为所有玩家或单个玩家添加一条临时规则。临时规则不会被保存;当玩家退出服务器时,其临时规则自动结束。
  • ItemBlockedEvent 会在任何操作被阻止之前触发。你可以取消该事件以允许操作通过,例如在一个拥有独立规则的迷你游戏中。

构建

./gradlew build

生成的 jar 文件位于 build/libs/ 目录中。运行 ./gradlew runServer 可以启动一个包含该插件的 Paper 测试服务器,使用参数 -Pmc=26.3 可以选择特定的 Minecraft 版本。

该插件基于 Spigot 1.21.11 API 进行编译。需要使用仅 Paper API 的代码应放在 paper 源集中,并且仅在 Paper 及其分支上加载。CI 流程会检查生成的 jar 是否与所有支持的 Spigot 和 Paper 版本兼容。

许可证

GPL-3.0

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源