ItemFilter

ItemFilter lets players create personal item filter profiles and decide which items should not be picked up. Server owners control the categories players see, how entries are matched, where filtering is active, and what happens when a filtered item is encountered. Filtered pickup items can optionally be redirected into a virtual /collect inventory.

Downloads

• Spigot
• BuiltByBit

Version

Current version: 1.1

1.1 Highlights

• Added world blacklist/whitelist support.
• Added a dedicated world filter GUI.
• Added a shortcut from the admin category GUI to the world filter GUI.
• Fixed status/debug boolean output formatting.
• Warmed the category cache during plugin startup to avoid first-use category loading lag.
• Improved duplicate material-entry behavior so the same material acts as one logical filter across categories.

Requirements

• Paper 1.21.11
• Java 21

ItemFilter uses SQLite for persistent storage. 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 if needed:
   • plugins/ItemFilter/config.yml
   • plugins/ItemFilter/messages.yml
   • plugins/ItemFilter/sounds.yml
4. Run /itemfilter reload after changing configuration files.

Existing config files are updated automatically when new bundled keys are added. Existing values are not overwritten.

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. Configure world scope if filtering should only work in selected worlds.
6. Give players itemfilter.use.
7. Players can open the profile manager with /itemfilter.

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

Player Usage

Players open the main GUI with:

/itemfilter

Aliases:

/filter
/ifilter

From the main GUI, players can:

• Create filter profiles
• Toggle profiles on or off
• Right click a profile to edit it
• Shift click a profile to enable only that profile
• Disable all profiles
• Rename a profile
• Change a profile icon
• Delete a profile after confirmation
• Browse categories and items with pagination
• Toggle individual items
• Toggle entire categories

Filtered entries show as items that will not be picked up. Allowed entries show as items that will be picked up.

Profiles

Each player can have multiple profiles. A profile contains selected filter entries and can be enabled or disabled independently.

Profile limits are controlled in config.yml:

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

The highest matching permission wins. itemfilter.profiles.unlimited allows unlimited profiles.

Filtering Modes

The filter behavior is configured at:

filter:
  mode: PICKUP_ONLY

Available modes:

Mode	Behavior
PREVENT_PICKUP	Blocks filtered items from entering the player's inventory by pickup.
PICKUP_ONLY	Blocks filtered item pickup, but allows players to move filtered items through inventories and containers.
DROP_FROM_INVENTORY	Allows pickup/movement, then drops matching filtered items back out.
DESTROY	Permanently deletes filtered items.

warning

DESTROY permanently removes items. It must be explicitly allowed with filter.allow-destructive-mode, and warning messages should stay enabled unless your staff fully understand the behavior.

Event Coverage

Filtering can be applied to specific event types:

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

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

World Filtering

World filtering controls where ItemFilter is active. It is disabled by default, which means filtering works in every world.

world-filter:
  mode: DISABLED
  worlds: []

Available modes:

Mode	Behavior
DISABLED	Filtering works in every world.
BLACKLIST	Filtering works in every world except listed worlds.
WHITELIST	Filtering only works in listed worlds.

World filtering applies to:

• Pickup filtering
• Inventory click filtering
• Inventory drag filtering
• Pickup-to-collection redirection

It does not block profile editing, category editing, status commands, reload commands, or opening /collect.

Commands:

/itemfilter worlds
/itemfilter worlds gui
/itemfilter worlds mode <disabled|blacklist|whitelist>
/itemfilter worlds add <world>
/itemfilter worlds remove <world>
/itemfilter worlds list

The world GUI shows loaded worlds. Click a world to add or remove it from the configured list. The mode button cycles between disabled, blacklist, and whitelist.

Bypass and Personal Toggle

Players with itemfilter.bypass bypass filtering by default. They can toggle whether filtering applies to themselves with:

/itemfilter toggle
/itemfilter toggle on
/itemfilter toggle off

/itemfilter filtering works the same way.

This is intended for staff, testing, and troubleshooting.

Status and Debugging

Players can check their own status:

/itemfilter status

Admins can check another player:

/itemfilter debug <player>

The status output includes:

• Active filter mode
• Active world-filter mode
• Current world
• Whether filtering is allowed in the current world
• Whether filtering 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 control what players see when editing a profile. They are stored in SQLite and can be managed through commands or the admin GUI.

Open the admin category GUI:

/itemfilter category gui

Requires:

itemfilter.admin.categories

Category GUI Controls

Category list:

Click	Action
Left click	Edit category entries
Right click	Move category down
Shift left click	Move category up
Shift right click	Delete category
Emerald button	Create a new category through chat
Compass button	Open the world filter GUI

Category entry editor:

Click	Action
Left click entry	Rename entry alias through chat
Right click entry	Delete entry
Shift left click entry	Move entry up
Shift right click entry	Move entry down
Hopper button	Add held item as a material entry
Ender chest button	Add held item as an exact entry
Name tag button	Rename category through chat
Category icon button	Set category icon from held item material

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>

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

Entry Matching

Category entries have two match types.

Material Entries

material entries match every item with the same Bukkit material.

Example:

/itemfilter category add tools material

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

Material entries are treated as one logical filter across categories. If the same material appears in multiple categories, toggling one copy filters or unfilters that material everywhere.

Exact Entries

exact entries match the serialized Bukkit item stack.

Example:

/itemfilter category add crates exact

Exact entries are useful for custom items, crate keys, and plugin-created items. They respect item meta and PersistentDataContainer data that Bukkit preserves during item 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 has a short alias, such as:

blocks:stone
crates:tripwire_hook
crates:tripwire_hook-2

Aliases are used by admin commands instead of UUIDs. UUIDs still work as a fallback for old notes or troubleshooting.

Rename an alias:

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

Allowed alias characters:

• Letters
• Numbers
• Underscores
• Dashes
• Colons

Collection System

The collection system is optional and disabled by default:

collection:
  enabled: false

When enabled, filtered pickup items can be moved into a virtual player-owned inventory instead of staying on the ground.

Players open it with:

/collect

Collection settings:

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

allow-deposit: false means players can take items from /collect but cannot put unrelated items into it.

Admins can set a per-player size override:

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

Messages

All plugin messages are configurable in:

plugins/ItemFilter/messages.yml

Messages support the {prefix} placeholder and command-specific placeholders such as {player}, {profile}, {mode}, {amount}, {item}, and {alias}.

Sounds

GUI sounds are configurable in:

plugins/ItemFilter/sounds.yml

Default sound sections:

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.

Permissions

Permission	Default	Description
itemfilter.use	true	Allows using item filter profiles.
itemfilter.collect	true	Allows opening /collect.
itemfilter.bypass	op	Bypasses filtering and allows personal filtering toggle.
itemfilter.admin.reload	op	Allows /itemfilter reload.
itemfilter.admin.mode	op	Allows changing the filter behavior mode.
itemfilter.admin.debug	op	Allows checking another player's status.
itemfilter.admin.collection-size	op	Allows setting per-player collection size overrides.
itemfilter.admin.categories	op	Allows managing filter categories.
itemfilter.admin.worlds	op	Allows managing world filtering.
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.

Commands

Command	Permission	Description
/itemfilter	itemfilter.use	Opens the player profile GUI.
/filter	itemfilter.use	Alias for /itemfilter.
/ifilter	itemfilter.use	Alias for /itemfilter.
/itemfilter status	itemfilter.use	Shows personal filter status.
/collect	itemfilter.collect	Opens the collection inventory if enabled.
`/itemfilter toggle [on	off]`	itemfilter.bypass
`/itemfilter filtering [on	off]`	itemfilter.bypass
/itemfilter reload	itemfilter.admin.reload	Reloads config, messages, and sounds.
/itemfilter mode <mode>	itemfilter.admin.mode	Changes the active filter mode.
/itemfilter debug <player>	itemfilter.admin.debug	Shows debug status for a player.
/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 admin category editor.
/itemfilter category ...	itemfilter.admin.categories	Manages filter categories and entries.
/itemfilter worlds gui	itemfilter.admin.worlds	Opens the world filter editor.
/itemfilter worlds ...	itemfilter.admin.worlds	Manages the world filter mode and world list.

Storage

ItemFilter stores data by UUID in SQLite.

Stored data includes:

• Player records
• Filter profiles
• Profile entry selections
• Player bypass toggle state
• Custom categories
• Category entries
• Entry aliases
• Collection contents
• Collection size overrides

The database file is stored in the plugin data folder.

Performance Notes

ItemFilter warms category data into memory during startup. This avoids the first player or administrator opening a category-related GUI being responsible for the initial category load.

Filtering checks use cached category and profile state instead of loading category definitions from SQLite for every item event.