ItemBlocker

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

1. Download the jar from Modrinth, Hangar or the releases.
2. Put it in plugins/ and start the server.
3. 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.

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

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