HopperFilterX

A lightweight, multilingual Minecraft plugin that lets you filter what hoppers can pick up using a simple in-game GUI. Designed for performance, survival, and technical servers.

---

🔧 Features

• /hopper give <player> [amount]: Give special filter-enabled hoppers to players.
• /hopper remove <player> <uuid>: Remove a filtered hopper from a player or the world.
• /hopper list <player>: List all filtered hoppers owned by a player.
• /hopper addperm <player> <uuid>: Grant players access to your filtered hoppers.
• /hopper removeperm <player> <uuid>: Remove player access from your filtered hoppers.
• /hopper reload: Reload the plugin's configuration and language files.
• ✨ Visual Distinction: Filtered hoppers have an enchantment glint effect in item form.
• 🔨 Craftable: Custom recipe using iron, redstone, and a chest (configurable).
• 🔍 Filter System: Shift + right-click a HopperFilterX hopper to open a GUI.
• 📥 Drag and Drop Items: Insert any items into the GUI to define the hopper's filter.
• ✅ Selective Item Movement: Hopper will only move items matching the filter.
• 🔄 Fallback Behavior: If no filter is defined, it behaves like a regular vanilla hopper.
• 🧊 Seamless vanilla integration: Works with all vanilla mechanics and hoppers.
• 🗃️ Persistent Filters: Filter settings are saved and restored even after server restarts.
• 🛡️ Owner Protection: Only the owner can pick up or configure their filtered hoppers.
• 🛠️ Creative/Survival Support: Handles creative/survival mode transitions safely.
• 🗣️ Multilanguage: See below for details.

🗂️ Supported Minecraft Versions (uses PaperLib for compatibility)

• Paper/Spigot 1.14.x
• Paper/Spigot 1.15.x
• Paper/Spigot 1.16.x
• Paper/Spigot 1.17.x
• Paper/Spigot 1.18.x
• Paper/Spigot 1.19.x
• Paper/Spigot 1.20.x
• Paper/Spigot 1.21.x

🌐 Multilanguage Support

HopperFilterX is fully translated and ready for international servers. It currently supports:

• English
• Spanish
• German
• French
• Portuguese
• Russian
• Simplified Chinese

The plugin automatically detects the player’s language based on their Minecraft client settings. All messages are customizable in lang.yml.

⚙️ Configuration

config.yml

• debug.enabled: Enable/disable debug mode for detailed logging (default: false)
• recipe.enabled: Enable/disable the crafting recipe for filtered hoppers (default: true)
  • If disabled, filtered hoppers can only be obtained via /hopper give command

lang.yml

• Contains all translatable messages and can be edited for custom language support
• Automatically detects player's language based on their Minecraft client settings

🛠️ Commands

Command	Description
/hopper give <player> [amount]	Give filter hoppers to a player
/hopper remove <player> <uuid>	Remove a filtered hopper from a player/world
/hopper list <player>	List all filtered hoppers owned by a player
/hopper addperm <player> <uuid>	Grant a player access to your filtered hoppers
/hopper removeperm <player> <uuid>	Remove a player's access from your filtered hoppers
/hopper reload	Reload plugin configuration and language

🔐 Permissions

Node	Description
hopperfilterx.use	Allows players to use the filter GUI
hopperfilterx.give	Allows use of the /hopper give command
hopperfilterx.remove	Allows use of the /hopper remove command
hopperfilterx.list	Allows use of the /hopper list command
hopperfilterx.addperm	Allows use of the /hopper addperm command
hopperfilterx.removeperm	Allows use of the /hopper removeperm command
hopperfilterx.reload	Allows reloading the plugin via command
hopperfilterx.*	Grants all HopperFilterX permissions

🎮 How it Works

Obtaining Filtered Hoppers

Option 1: Crafting Recipe (Default)

[Iron] [Redstone] [Iron]
[Iron]  [Chest]   [Iron]
       [Iron]

Craft a filtered hopper using 5 Iron Ingots, 1 Redstone, and 1 Chest.

Option 2: Command Use /hopper give <player> [amount] to give a player filtered hoppers directly.

Using Filtered Hoppers

1. Place the filtered hopper like any normal hopper.
2. Shift + Right-Click on it to open the filter configuration GUI.
3. Add items you want the hopper to accept into the GUI.
4. The hopper will now only move the selected items. If the filter is empty, it works like vanilla.

🔗 Permission System

HopperFilterX includes a built-in permission system that allows you to share access to your filtered hoppers with other players:

• Grant Access: Use /hopper addperm <player> <uuid> to allow another player to use your filtered hoppers
  • Without UUID: Grants access to all your current and future filtered hoppers
  • With UUID: Grants access only to a specific hopper
• Revoke Access: Use /hopper removeperm <player> <uuid> to remove a player's access
• Owner Protection: Only the hopper owner can modify filters and manage permissions
• Persistent: Permissions are saved in the database and persist across server restarts

💡 Use Cases

• Create automated item sorters.
• Prevent specific items from being picked up in complex redstone systems.
• Set up refined farms and storage systems with ease.

🧪 Demonstration

📝 Technical & Legal

• License: GPL-3.0-only (see LICENSE)
• Author: MrH00k
• Database: Uses SQLite for persistent filter storage.
• No suppression of static analysis warnings: All warnings remain visible for maintainability.
• No external dependencies required (except PaperLib for version compatibility).

---

Start organizing your hoppers like a pro — with HopperFilterX!