---

Paper Purpur Folia Spigot

Item, enchantment and potion effect restrictions for Paper, Folia, Purpur and Spigot, Minecraft 1.17 to 26.3. **[Read the full documentation](https://opuszek.gitbook.io/itemblocker)** 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](https://modrinth.com/plugin/itemblocker), [Hangar](https://hangar.papermc.io/kuqk/ItemBlocker) or the [releases](https://github.com/kuqk/ItemBlocker/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. | 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 [actions:...] [worlds:...] [in:preset] /ib block enchantment [level:n] [mode:block|downgrade|remove|confiscate] [in:preset] /ib block potion [level:n] [in:preset] /ib edit [actions:...] [worlds:...] [in:preset] /ib limit [stack:n|none] [inventory:n|none] [in:preset] /ib filter add [hand] [type:] [name:] [lore:] [model:] [data:] [enchantment:] [actions:] [worlds:] [in:preset] /ib filter remove [in:preset] /ib filter list [in:preset] /ib group add [actions:...] [worlds:...] [bypass:...] [in:preset] /ib group remove [in:preset] /ib group list [in:preset] /ib allow add|remove [in:preset] /ib allow list [in:preset] /ib scan players|containers [remove|confiscate] [actions:...] [radius:n] [world:name] /ib confiscated [take ] /ib log [player] /ib unblock [name] [in:preset] /ib show [name] /ib list [items|limits|enchantments|potions] [in:preset] /ib preset list | show | create | delete /ib preset edit [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 regions `. 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 [as:]` 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:`. - 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 ` 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/.log`, one line each: ``` 2026-11-02 17:40:01 | Steve | place | TNT | world | default ``` `/ib log` shows the last ten, `/ib log ` 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`: ```yaml 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.` | 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.` | 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 ```yaml 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. skips one kind of restriction ``` ### rules.yml Commands write this file, but you can also edit it and run `/ib reload`. ```yaml 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](https://jitpack.io/#kuqk/ItemBlocker) and declare it in your `plugin.yml` with `depend: [ItemBlocker]` or `softdepend: [ItemBlocker]`: ```kotlin repositories { maven("https://jitpack.io") } dependencies { compileOnly("com.github.kuqk:ItemBlocker:v2.6.3") } ``` ```java 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 ```bash ./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](LICENSE)

ItemBlocker

2.1.0

Added

Changed

Compatibility

Information

Platforms