适用于 Paper、Folia、Purpur 和 Spigot 的 Minecraft 1.17 至 26.3 版本的物品、附魔与药水效果限制插件。
阅读完整文档 以了解每条规则、命令、权限及设置的详细信息。
- 针对合成、拾取、丢弃、使用、放置、穿戴、背包、漏斗和锻造台等操作限制物品。
- 从指定等级起限制附魔和药水效果。
- 限制物品的堆叠上限以及玩家可携带的数量。
- 整组限制特定类型的物品(例如所有剑),同时允许其中少数几种。
- 提供 API 供其他插件调用:检查规则、添加临时规则或放行被拦截的操作。
- 将每次被拦截的操作记录到文件中,并可选择发送至 Discord 频道。
- 查找玩家或容器中已存在的违禁物品,并将其移除或没收。
- 通过权限让某个角色组忽略单条规则或整个预设配置。
- 根据名称、描述(lore)、自定义模型数据、插件数据或附魔等条件,精确限制单个特定物品(例如来自 RPG 插件的剑)。
- 将规则分组为预设配置,并将任意规则或预设限定于特定世界,或将预设限定于 WorldGuard 区域。
- 支持通过菜单(
/ib gui)、命令配合自动补全功能,或在单个 YAML 文件中进行全面管理。
- 提供英语、波兰语、德语、西班牙语、法语和意大利语的消息提示,并兼容 PlaceholderAPI 占位符。
安装方法
- 从 Modrinth、Hangar 或 发布页面 下载 jar 文件。
- 将其放入
plugins/ 目录并启动服务器。
- 开始设置限制:执行
/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
Item, enchantment and potion effect restrictions for Paper, Folia, Purpur and Spigot, Minecraft 1.17 to 26.3.
Read the full documentation for every rule, command, permission and setting.
- Block items per action: crafting, pickup, drop, use, place, armor, inventory, hopper and smithing.
- Block enchantments and potion effects from a minimum level.
- Limit how big an item stacks and how many of it a player may carry.
- Block whole groups of items, such as every sword, and allow just a few of them.
- An API for other plugins: check rules, add temporary rules and let blocked actions through.
- Log every blocked action to files and, optionally, a Discord channel.
- Find forbidden items players and containers already have, and remove or confiscate them.
- Let a rank ignore one rule, or a whole preset, with a permission.
- Block one specific item, such as a sword from an RPG plugin, by its name, lore, custom model data, plugin data or enchantments.
- Group rules into presets and limit any rule or preset to specific worlds, or a preset to WorldGuard regions.
- Manage everything in a menu (
/ib gui), with commands and tab completion, or in one YAML file.
- Messages in English, Polish, German, Spanish, French and Italian, with PlaceholderAPI placeholders.
Installation
- Download the jar from Modrinth, Hangar or the releases.
- Put it in
plugins/ and start the server.
- Block something:
/ib block tnt actions:place.
ItemBlocker runs on Java 16 or newer, so it works with whatever Java your server already uses.
How it works
Rules live in presets. The default preset always exists and applies everywhere. Create more presets for worlds, events or game modes, and give each preset its own reason shown in block messages.
A preset can block:
- Items, per action. An item rule can be limited to some worlds.
- Enchantments from a minimum level, each with a mode that says what happens to items carrying it:
block (the default): the item is blocked for every action, enchanting tables stop offering the enchantment and anvils do not produce it;
downgrade: the enchantment is lowered to the highest allowed level, so with Sharpness blocked from 5 a Sharpness V sword becomes Sharpness IV;
remove: the enchantment is taken off;
confiscate: the item is taken away and kept with /ib confiscated.
Items are fixed as soon as a player has them: after joining, picking up, inventory clicks and enchanting. Set the mode with mode:, for example /ib block enchantment sharpness level:5 mode:downgrade, or with shift + left click in the menu.
- Potion effects from a minimum level. The effect is not applied, and players lose it when they join or change worlds.
- Item groups: every item type matching a pattern, such as
*_sword, netherite_* or the item tag #swords, with actions and worlds like an item rule.
- Allowed items: item types the preset's item rules and groups never block, for example a group blocking every sword with
wooden_sword allowed.
- Item filters: specific items matched by text in their name or lore, custom model data, a persistent data entry (how plugins such as Nexo, Oraxen or ExecutableItems mark their items) or an enchantment, each with its own actions and worlds. Every criterion you set must match. Item filters are checked after the rules by item type.
- Item limits: the largest stack of an item and the most of it a player may carry. If several presets limit the same item, the smallest limit wins.
| Action |
Blocks |
crafting |
Taking the item from a crafting result |
pickup |
Picking the item up |
drop |
Dropping the item |
use |
Right clicking with the item, eating or drinking it |
place |
Placing it as a block, emptying it as a bucket, or placing it as an entity (boats, minecarts, armor stands, item frames, paintings, end crystals) |
armor |
Wearing it, however it is put on. Blocked armor is taken off when a player joins or changes worlds |
inventory |
Moving it into or out of chests and other containers |
hopper |
Hoppers moving or picking it up |
smithing |
Getting it from a smithing table |
attack |
Hitting a mob or player while holding it |
break |
Breaking it as a block, or breaking any block while holding it as a tool |
crafter |
Crafters (1.21+) making it |
dispense |
Dispensers and droppers using it |
brew |
Brewing stands making it. Potions whose effect a preset blocks are not brewed either |
trade |
Getting it from a villager or wandering trader |
loot |
It appearing in chests and other generated loot; the rest of the loot is kept |
entity_drop |
Mobs dropping it when they die. Players always drop their own items |
obtain stands for every way of getting an item: crafting, crafter, smithing, brew, trade, loot, entity_drop and pickup. Use it to let players keep and use an item but not get more of it, for example /ib block mace actions:obtain.
Limits are kept like this: players only pick up as much as they may carry and as fits into stacks within the limit, and taking more out of a container is denied. Anything that still goes over, for example by crafting, is fixed right away: stacks above the limit are split into free slots and what does not fit or exceeds the inventory limit is dropped at the player's feet. Items are never deleted.
Commands
The command is /itemblocker, or /ib. Every command has tab completion.
/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: takes a comma separated list, all or obtain, for example actions:place,use. Without it, every action is blocked.
worlds: takes a comma separated list or all, for example worlds:world,world_nether.
stack: and inventory: set the largest stack and the most a player may carry, none removes the limit. Options you leave out keep their value.
hand in /ib filter add copies the held item's type, custom name, custom model data and plugin data; options you add replace what was copied. Values with spaces go in double quotes, for example name:"Sword of Kings". data: takes a key or key=value, such as data:nexo:id=ruby_sword.
bypass: names a permission that lets players ignore just that rule, for example bypass:vip.elytra; bypass:none removes it. It works on block, edit, filter add and group add.
in: picks the preset. Without it, the default preset is used.
block adds to an existing rule, edit replaces only the parts you give.
hand means the item in your main hand.
Examples:
/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
Integrations
Both are optional. ItemBlocker hooks into them when they are installed and works the same without them.
- WorldGuard: limit a preset to regions with
/ib preset edit <name> regions <region,...>. The preset then only applies inside those regions, and still only in its worlds. regions all removes the limit. Without WorldGuard, a preset limited to regions applies nowhere.
- PlaceholderAPI: placeholders such as
%player_name% work in every message sent to a player.
Permissions work with any permission plugin, such as LuckPerms, including per world and per server contexts.
Templates
/ib template lists ready-made presets and /ib template <name> [as:<preset>] creates one, as does the templates button in the menu. They are a starting point; change them like any other preset.
survival: keeps creative-only and operator items out of survival (bedrock, barriers, command blocks, structure blocks, debug sticks and more).
lifesteal: no end crystals or respawn anchors, one totem, one enchanted golden apple, Sharpness V and Protection IV lowered, Thorns removed, no Strength II, no new maces.
pvp: no end crystals, respawn anchors or TNT, no attacking with maces, one totem, Sharpness V and Power V lowered, no Strength II or Resistance III.
Scanning existing items
Rules only stop new actions. Items players got before a rule existed stay where they are, so /ib scan finds them:
/ib scan players checks the inventory and ender chest of every online player.
/ib scan containers checks chests, barrels, shulker boxes and other containers in loaded chunks around you (radius: chunks, 4 by default), or in a whole world with world:<name>.
- Without more arguments it only reports what it found. Add
remove to delete those items, or confiscate to move them to confiscated.yml. /ib confiscated lists them by owner and /ib confiscated take <owner> gives them to you.
- An item counts as forbidden if players may not pick it up or it carries a blocked enchantment. Use
actions: to count other actions, for example actions:use,place. Players' own bypass permissions apply.
Logs and Discord alerts
Every blocked action is written to plugins/ItemBlocker/logs/<date>.log, one line each:
2026-11-02 17:40:01 | Steve | place | TNT | world | default
/ib log shows the last ten, /ib log <player> those of one player. Holding a blocked item and clicking again within a second is only logged once.
To get alerts on Discord, create a webhook in the channel settings and put its URL in config.yml:
log:
enabled: true
discord:
webhook: "https://discord.com/api/webhooks/..."
cooldown-seconds: 60 # one alert per player, action and item per minute
Alerts never ping anyone, even if an item is named @everyone.
Menu
/ib gui lets you set up nearly everything without typing commands. It lists every preset, with buttons to create a new one or start from a template (Survival, Lifesteal, PvP). A preset opens a menu with these sections:
- Items: every item with a rule or limit. Click an item in your own inventory or search all items to add one, click an entry to edit it, shift + right click to remove it.
- Item groups: add a group by typing a pattern such as
*_sword or #swords in the chat.
- Item filters: click an item in your own inventory; the filter is named after it and copies its type, name, model data and plugin data.
- Allowed items: click an item in your own inventory to allow it, click an entry to remove it.
- Enchantments and Potion effects: left click raises the level something is blocked from, right click lowers it, shift + right click unblocks it. For enchantments, shift + left click changes the mode.
- Settings: description, reason, and the worlds and WorldGuard regions, picked from a list. Presets other than
default can be deleted with shift + right click.
The rule editor for items, groups and filters toggles each action and sets the worlds and the bypass permission. For items it also sets the stack and inventory limits (left click +1, right click -1, shift for steps of 16), and for filters every criterion: type, name, lore, model data, plugin data and enchantment.
Worlds are picked from a list everywhere. When a menu needs free text, such as a name, a pattern, a permission or a search, it closes and asks you to type it in the chat; your message is not shown to others. Click cancel in that message, or type it or the word from your language file such as anuluj, to go back without changing anything, or type none to clear a value. Every change is saved right away.
Permissions
| Permission |
Allows |
Default |
itemblocker.use |
Using /ib at all |
op |
itemblocker.add |
/ib block for items |
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 and /ib confiscated |
op |
itemblocker.log |
/ib log |
op |
itemblocker.remove |
/ib unblock for items |
op |
itemblocker.enchantment |
Blocking and unblocking enchantments |
op |
itemblocker.potion |
Blocking and unblocking potion effects |
op |
itemblocker.info |
/ib show and /ib preset show |
op |
itemblocker.list |
/ib list and /ib preset list |
op |
itemblocker.preset |
Creating, editing and deleting presets |
op |
itemblocker.reload |
/ib reload |
op |
itemblocker.gui |
/ib gui |
op |
itemblocker.admin |
All of the above |
op |
itemblocker.bypass |
Ignoring every restriction |
op |
itemblocker.bypass.<action> |
Ignoring one action, for example itemblocker.bypass.place |
no |
itemblocker.bypass.enchantment |
Ignoring enchantment restrictions |
no |
itemblocker.bypass.potion |
Ignoring potion effect restrictions |
no |
itemblocker.bypass.limit |
Ignoring stack and inventory limits |
no |
itemblocker.bypass.preset.<name> |
Ignoring one preset, for example itemblocker.bypass.preset.pvp |
no |
any permission set with bypass: |
Ignoring that one rule |
no |
The preset and rule permissions only count when they are granted explicitly, for example by a permission plugin, so operators do not get them just for being operators. Operators bypass every restriction by default. Test your rules with a player who is not an operator, or set both bypass.enabled: false and bypass.per-action: false in config.yml and run /ib reload.
Configuration
config.yml
language: en # en, pl, de, es, fr or it; messages are in the lang folder
messages:
cooldown-ms: 1000 # minimum time between two block messages to the same player
bypass:
enabled: true # itemblocker.bypass skips every restriction
per-action: true # itemblocker.bypass.<action> skips one kind of restriction
rules.yml
Commands write this file, but you can also edit it and run /ib reload.
presets:
default:
description: ''
reason: '&cThis item is disabled on this server'
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
If rules.yml has a YAML error, the previous rules stay active and commands refuse to change them until the file is fixed and reloaded, so a command can never overwrite your edits.
Messages
Message files are in plugins/ItemBlocker/lang/. They support & color codes, hex colors like &#ff8800 and, with PlaceholderAPI installed, its placeholders. Entries you delete fall back to the bundled text, so you only need to keep the ones you change. To add a language, copy en.yml to for example nl.yml and set language: nl.
API for other plugins
Add ItemBlocker through JitPack and declare it in your plugin.yml with depend: [ItemBlocker] or softdepend: [ItemBlocker]:
repositories {
maven("https://jitpack.io")
}
dependencies {
compileOnly("com.github.kuqk:ItemBlocker:v2.6.3")
}
ItemBlockerApi api = ItemBlockerApi.get();
// Is it blocked for this player here?
api.check(player, item, Action.USE).ifPresent(restriction ->
player.sendMessage("Blocked by " + restriction.preset()));
// Block ender pearls for one player during a quest, then lift it again.
TemporaryRule rule = api.blockTemporarily(player, Material.ENDER_PEARL, Set.of(Action.USE), "Not during the quest");
rule.remove();
check and isBlocked use the same rules, permissions and exceptions as the plugin itself.
blockTemporarily adds a rule for everyone or for one player. Temporary rules are never saved; a player's rules end when they leave.
ItemBlockedEvent is called before anything is blocked for a player. Cancel it to let the action through, for example in a minigame with its own rules.
Building
./gradlew build
The jar is written to build/libs/. ./gradlew runServer starts a Paper test server with the plugin, -Pmc=26.3 picks the Minecraft version.
The plugin compiles against the Spigot 1.21.11 API. Code that needs Paper-only API lives in the paper source set and is loaded only on Paper and its forks. CI checks that the jar links against every supported Spigot and Paper version.
License
GPL-3.0
评论 0
登录后参与评分
还没有评论,来抢沙发吧