ItemFilter

ItemFilter lets players create personal item-filter profiles and decide which items they do not want to pick up. Server owners control the categories players can browse, how entries are matched, how many profiles players may create, and what happens when a filtered item is encountered.

The plugin supports ordinary material-based filters, exact Bukkit item-stack matching for custom items, and an optional virtual /collect inventory.

Requirements

• Paper 1.21.11
• Java 21

ItemFilter stores persistent data in SQLite. The SQLite JDBC library is declared through Paper's plugin-library system and downloaded automatically at runtime.

No external database server or manual SQLite installation is required.

Installation

1. Place the ItemFilter jar in your server's plugins folder.
2. Start the server.
3. Edit the generated files as needed:
   • plugins/ItemFilter/config.yml
   • plugins/ItemFilter/messages.yml
   • plugins/ItemFilter/sounds.yml
4. Run /itemfilter reload after changing configuration files.

When new bundled configuration keys are introduced, ItemFilter adds missing keys automatically without overwriting existing values.

Quick Start

1. Install ItemFilter and start the server.
2. Keep the default filter mode or choose another with /itemfilter mode <mode>.
3. Open the category editor with /itemfilter category gui.
4. Create categories and add material or exact-item entries.
5. Give players itemfilter.use.
6. Players can open the profile manager with /itemfilter.

The optional collection system remains disabled until it is enabled in config.yml.

Player Usage

Open the main GUI with:

/itemfilter

Aliases:

/filter
/ifilter

From the GUI, players can:

• Create filter profiles
• Toggle profiles independently
• Shift click a profile to enable only that profile
• Disable all profiles
• Right click a profile to edit it
• Rename profiles through chat prompts
• Choose profile icons
• Delete profiles through a confirmation GUI
• Browse paginated categories and entries
• Toggle individual entries
• Toggle complete categories

Filtered entries represent items that will be filtered. Allowed entries represent items that will not be filtered.

GUI Indicators

• Filtered entries glow in the item browser.
• Allowed and filtered entries use distinct item text.
• Category colors summarize the selected entries:
  • Green: no entries in the category are filtered
  • Yellow: some entries are filtered
  • Red: every entry is filtered

GUI click sounds are configurable in sounds.yml.

Profiles

Each player can create multiple profiles. Profiles can be enabled or disabled independently, allowing players to prepare different filter sets for different activities.

Profile limits are configured in config.yml:

profile-limits:
  default: 1
  permissions:
    'itemfilter.profiles.3': 3
    'itemfilter.profiles.5': 5
    'itemfilter.profiles.10': 10

The highest matching profile-limit permission wins.

itemfilter.profiles.unlimited

grants unlimited profiles.

Filtering Modes

The active behavior is configured at:

filter:
  mode: PICKUP_ONLY

Available modes:

Mode	Behavior
PREVENT_PICKUP	Prevents matching items through the enabled filter event coverage.
PICKUP_ONLY	Blocks matching ground pickups only. Inventory and container movement remain allowed.
DROP_FROM_INVENTORY	Allows matching items to enter or move through an inventory, then drops them back out.
DESTROY	Permanently deletes matching items.

Destructive mode

DESTROY permanently removes items. It must be explicitly enabled through filter.allow-destructive-mode and confirmed through the mode command. Keep the configured warning messages enabled unless your staff fully understand the behavior.

Change the active mode with:

/itemfilter mode <prevent-pickup|pickup-only|drop-from-inventory|destroy>

Confirm destructive mode with:

/itemfilter mode destroy confirm

Event Coverage

Filtering can be enabled independently for supported event types:

filter:
  apply-to-pickup: true
  apply-to-inventory-click: true
  apply-to-inventory-drag: true

When PICKUP_ONLY is active, inventory click and drag filtering are skipped by design.

Bypass and Personal Filtering

Players with itemfilter.bypass bypass filtering by default.

A bypass user can choose whether filtering applies to them:

/itemfilter toggle
/itemfilter toggle on
/itemfilter toggle off

The following alias behaves the same way:

/itemfilter filtering
/itemfilter filtering on
/itemfilter filtering off

This is intended for staff, testing, and troubleshooting.

Status and Debugging

Players can inspect their own effective state:

/itemfilter status

Admins can inspect another online player:

/itemfilter debug <player>

Status output can include:

• Active filtering mode
• Whether filtering currently applies
• Bypass permission state
• Personal filtering toggle state
• Profile count and profile limit
• Enabled profile count
• Effective filtered-entry count
• Collection status and size

Custom Categories

Categories define the entries players see while editing profiles. Categories and entries are stored in SQLite and can be managed through the admin GUI or commands.

Open the category editor:

/itemfilter category gui

Required permission:

itemfilter.admin.categories

Category List Controls

Control	Action
Left click a category	Open its entry editor
Right click a category	Move it down
Shift left click a category	Move it up
Shift right click a category	Delete it
Emerald button	Create a category through chat

Category Entry Controls

Control	Action
Left click an entry	Rename its alias through chat
Right click an entry	Delete it
Shift left click an entry	Move it up
Shift right click an entry	Move it down
Hopper button	Add the held item as a material entry
Ender chest button	Add the held item as an exact entry
Name tag button	Rename the category through chat
Category icon button	Use the held item's material as the category icon

For controls and commands that use the held item, the admin must hold the target item in their main hand.

Category Commands

/itemfilter category list
/itemfilter category entries <id>
/itemfilter category create <id> <display name>
/itemfilter category delete <id>
/itemfilter category rename <id> <display name>
/itemfilter category icon <id>
/itemfilter category order <id> <number>
/itemfilter category add <id> <material|exact>
/itemfilter category remove <entry alias>
/itemfilter category entry-order <entry alias> <number>
/itemfilter category entry-alias <old alias> <new alias>

Entry Matching

Category entries support two matching strategies.

Material Entries

A material entry matches every item using the same Bukkit material.

Example:

/itemfilter category add tools material

When the admin is holding FLINT_AND_STEEL, this creates an entry that matches all flint and steel items.

Material entries behave as one logical filter across categories. When the same material appears in multiple categories, toggling any copy filters or unfilters that material everywhere.

Exact Entries

An exact entry compares the Bukkit-serialized item stack.

Example:

/itemfilter category add crates exact

Exact entries are intended for custom items, crate keys, rewards, and plugin-created items. They include item meta and PersistentDataContainer data preserved by Bukkit serialization.

Exact entries remain independent from material entries and from other exact entries.

Custom-item compatibility

Exact matching depends on the metadata the originating plugin exposes and Bukkit preserves during serialization. Test important third-party custom items before deploying them broadly.

Entry Aliases

Every category entry receives a readable alias, such as:

blocks:stone
crates:tripwire_hook
crates:tripwire_hook-2

Admin commands accept aliases instead of requiring UUIDs. Entry UUIDs remain valid as a fallback for legacy references and troubleshooting.

Rename an alias with:

/itemfilter category entry-alias <old alias> <new alias>

Allowed alias characters:

• Letters
• Numbers
• Underscores
• Dashes
• Colons

Optional Collection System

The collection system is disabled by default:

collection:
  enabled: false

When enabled, filtered pickup items can be moved into a private virtual inventory instead of remaining on the ground.

Players open their collection with:

/collect

Example settings:

collection:
  enabled: false
  allow-deposit: false
  default-size: 27
  permissions:
    'itemfilter.collection.36': 36
    'itemfilter.collection.45': 45
    'itemfilter.collection.54': 54

When allow-deposit is false, players can remove collected items but cannot use the interface to deposit unrelated items.

Admins can set or clear a per-player size override:

/itemfilter collection-size <player> <slots>
/itemfilter collection-size <player> clear

Collection contents and size overrides are stored persistently in SQLite.

Messages

All plugin messages are configurable in:

plugins/ItemFilter/messages.yml

Messages support {prefix} and command-specific placeholders such as:

• {player}
• {profile}
• {mode}
• {amount}
• {item}
• {alias}

Available placeholders depend on the message being rendered.

Sounds

GUI sounds are configurable in:

plugins/ItemFilter/sounds.yml

Default sections include:

enabled: true

gui-click:
  enabled: true
  sound: UI_BUTTON_CLICK
  volume: 0.8
  pitch: 1.2

collection-click:
  enabled: true
  sound: UI_BUTTON_CLICK
  volume: 0.8
  pitch: 1.0

Sound names are parsed through Bukkit's sound registry.

Commands

Player Commands

Command	Permission	Description
/itemfilter	itemfilter.use	Opens the profile manager.
/filter	itemfilter.use	Alias for /itemfilter.
/ifilter	itemfilter.use	Alias for /itemfilter.
/itemfilter status	itemfilter.use	Displays the player's effective filter state.
/collect	itemfilter.collect	Opens the collection inventory when enabled.

Staff and Admin Commands

Command	Permission	Description
/itemfilter reload	itemfilter.admin.reload	Reloads config, messages, and sounds.
/itemfilter mode <mode>	itemfilter.admin.mode	Changes the active filtering behavior.
/itemfilter mode destroy confirm	itemfilter.admin.mode	Confirms and enables destructive mode when allowed by config.
/itemfilter toggle [on|off]	itemfilter.bypass	Toggles personal filtering for a bypass user.
/itemfilter filtering [on|off]	itemfilter.bypass	Alias for the personal filtering toggle.
/itemfilter debug <player>	itemfilter.admin.debug	Displays another player's effective filter state.
/itemfilter collection-size <player> <slots|clear>	itemfilter.admin.collection-size	Sets or clears a collection-size override.
/itemfilter category gui	itemfilter.admin.categories	Opens the category editor.
/itemfilter category ...	itemfilter.admin.categories	Manages categories and entries.

Permissions

Permission	Default	Description
itemfilter.use	true	Allows use of item-filter profiles.
itemfilter.collect	true	Allows opening /collect.
itemfilter.bypass	op	Bypasses filtering and grants the personal filtering toggle.
itemfilter.admin.reload	op	Allows /itemfilter reload.
itemfilter.admin.mode	op	Allows changing filtering behavior.
itemfilter.admin.debug	op	Allows inspecting another player's status.
itemfilter.admin.collection-size	op	Allows setting per-player collection-size overrides.
itemfilter.admin.categories	op	Allows managing categories and entries.
itemfilter.profiles.3	false	Allows up to 3 profiles.
itemfilter.profiles.5	false	Allows up to 5 profiles.
itemfilter.profiles.10	false	Allows up to 10 profiles.
itemfilter.profiles.unlimited	op	Allows unlimited profiles.
itemfilter.collection.36	false	Sets collection size to at least 36 slots.
itemfilter.collection.45	false	Sets collection size to at least 45 slots.
itemfilter.collection.54	false	Sets collection size to at least 54 slots.

Storage

ItemFilter stores persistent data by player UUID in SQLite.

Stored data includes:

• Player records
• Filter profiles
• Profile entry selections
• Bypass-user filtering preferences
• Custom categories
• Category entries
• Entry aliases
• Collection contents
• Collection-size overrides

The database file is stored in the ItemFilter plugin data folder.