ItemFilter

ItemFilter lets players decide which items they do not want to pick up. Players build personal filter profiles through an inventory GUI, while server owners control the available categories, matching behavior, profile limits, active worlds, and what happens to filtered items.

Version 1.1

• World blacklist and whitelist support
• Dedicated world-filter administration GUI
• Shortcut from the category editor to the world-filter GUI
• World-aware status and debug output
• Startup category-cache warm-up
• Consistent material filtering across duplicate category entries

Player Profiles

• Multiple filter profiles per player
• Enable or disable profiles independently
• Enable only one selected profile
• Disable all profiles at once
• Rename profiles through chat prompts
• Choose profile icons from the item browser
• Delete profiles through a confirmation GUI
• Persistent storage by player UUID
• Permission-based profile limits

Inventory GUI

• Paginated profile, category, and item browsers
• Left click a profile to toggle it
• Right click a profile to edit it
• Shift click a profile to enable only that profile
• Filtered entries glow in the item browser
• Clear visual distinction between filtered and allowed items
• Category status colors show whether none, some, or all entries are filtered
• Toggle an entire category at once
• Configurable GUI click sounds

Filtering Modes

Server owners choose how filtered items behave:

• PREVENT_PICKUP — prevents matching items through the enabled filter event coverage
• PICKUP_ONLY — blocks ground pickup only while allowing inventory and container movement
• DROP_FROM_INVENTORY — drops matching items back out after pickup or inventory movement
• DESTROY — permanently deletes matching items

Warning: DESTROY is intentionally protected by a separate safety setting and confirmation command because deleted items cannot be recovered.

Filtering coverage can be configured independently for:

• Item pickup
• Inventory clicks
• Inventory drags

World Filtering

World filtering is disabled by default. When enabled, admins can restrict ItemFilter to selected worlds or exclude selected worlds.

• DISABLED — filtering works in every world
• BLACKLIST — filtering works everywhere except listed worlds
• WHITELIST — filtering works only in listed worlds
• Dedicated GUI for managing loaded worlds
• Command-based world management
• World state shown in status and debug output

World filtering applies to pickup filtering, inventory click and drag filtering, and pickup-to-collection redirection.

Custom Categories

Admins control the categories and entries shown to players.

• Create, delete, rename, reorder, and re-icon categories
• Add, remove, rename, and reorder category entries
• Manage categories through an admin GUI or commands
• Open the world-filter GUI directly from the category editor
• Use readable aliases such as blocks:stone or crates:tripwire_hook
• Use UUIDs as a fallback for legacy references and troubleshooting

Material and Exact Matching

• Material entries match every item using the same Bukkit material
• Exact entries match the Bukkit-serialized item stack, including item meta and PersistentDataContainer data preserved by Bukkit

Material entries behave as one logical filter across categories. If the same material appears in more than one category, toggling any copy updates that material everywhere.

Exact entries remain independent and are intended for custom items, crate keys, and plugin-created items. Compatibility depends on the item data exposed and preserved through Bukkit serialization.

Optional Collection Inventory

The optional /collect system is disabled by default. When enabled, filtered pickup items can be moved into a private virtual inventory instead of remaining on the ground.

• Configurable default size
• Permission-based collection sizes
• Per-player admin overrides
• Optional manual deposits
• Configurable pickup-to-collection messages

Administration and Diagnostics

• Runtime filter-mode switching
• World-filter GUI and commands
• Bypass permission for staff and testing
• Personal filtering toggle for bypass users
• Player status command
• Admin debug command for inspecting another player's effective filter state
• Reload command for config, messages, and sounds
• Startup config updater adds missing bundled keys without replacing existing values
• Category cache is warmed during startup to avoid first-use loading spikes

Storage and Configuration

• SQLite storage for players, profiles, selections, categories, entries, aliases, collection contents, and overrides
• SQLite JDBC loaded through Paper's plugin-library system
• No external database setup required
• Configurable messages in messages.yml
• Configurable sounds in sounds.yml
• Configurable profile limits, collection sizes, event coverage, filter mode, world scope, and destructive-mode safety

Main Commands

The full command and permission reference is available in the wiki.

Requirements

• Paper 1.21.11
• Java 21

Documentation

• ItemFilter Wiki