SUPERHOPPER | Custom Upgradeable Hoppers v1.0.0

SUPERHOPPER transforms ordinary Minecraft hoppers into powerful, fully manageable automation tools.

Players can purchase custom hopper types, place and upgrade them, connect remote containers, create precise item filters, manage fuel, and teleport to their owned hoppers—all through intuitive in-game menus and commands.

Server owners have complete control over hopper types, upgrade paths, prices, permissions, GUI layouts, storage systems, integrations, and gameplay restrictions.

Whether you run a Survival, Skyblock, Prison, Economy, or Farming server, SUPERHOPPER provides a flexible hopper system that can be adapted to your server's progression and economy.

• Create Meaningful Progression — Players can gradually improve their hoppers instead of receiving maximum performance immediately.
  
• Reduce Complicated Redstone Setups — Link containers and automate item movement without requiring large vanilla hopper networks.
  
• Build an Economy Around Automation — Charge players for hopper purchases, upgrades, fuel, and teleportation.
  
• Give Players Complete Control — Manage filters, links, upgrades, names, transfer order, and other settings through configurable GUIs.
  
• Adapt It to Your Server — Create custom hopper types, prices, upgrade tiers, permissions, layouts, and integration rules.

• Upgradeable Hopper Tiers — Configure independent upgrade levels for transfer amount, transfer speed, suction radius, maximum links, and link distance.
  
• Custom Hopper Types — Create multiple hopper types with their own prices, permissions, behavior, statistics, and upgrade paths.
  
• Hopper Shop GUI — Allow players to browse available hopper types and purchase them through a configurable in-game shop.
  
• Complete Management GUI — Players can manage links, filters, upgrades, fuel, names, and hopper settings from organized menus.
  
• Remote Container Linking — Connect hoppers to chests and supported containers through the GUI or commands.
  
• Advanced Item Filters — Use blacklist or whitelist filtering with optional strict matching and CustomModelData support.
  
• Fuel and Charge System — Charge players using Vault economy or configurable command-based currencies.
  
• Hopper Teleportation — Players can locate and teleport to their owned hoppers with configurable costs and delays.
  
• SQLite and MySQL Storage — Use local SQLite storage or connect the plugin to MySQL, with built-in migration and import commands.
  
• Highly Configurable GUIs — Customize menu titles, buttons, materials, slots, borders, panes, and border animation styles.
  
• Safe Hopper Removal — Tracked hoppers require crouching to break, helping prevent accidental removal.
  
• Paper and Folia Support — Designed for modern Minecraft server environments running Java 21 or newer.

Hopper types are configured inside hoppers.yml. The default configuration includes:

• Super Hopper — A standard upgradeable hopper designed for general automation.
  
• Chunk Hopper — A larger farming hopper with chunk-scaled item suction.

Each hopper type can define its own:

• Display name and item appearance
• Enabled and default states
• Purchase cost
• Transfer and suction intervals
• Direct suction behavior
• Container linking behavior
• Required permission
• Available upgrade levels

• Transfer Amount — Controls how many items or stacks are moved during each transfer cycle.
  
• Transfer Speed — Controls how frequently the hopper performs transfers.
  
• Suction Radius — Controls how far away dropped items can be collected.
  
• Link Amount — Controls the maximum number of containers that can be connected.
  
• Link Distance — Controls the maximum distance between a hopper and its linked containers.

Every upgrade path can have its own values, prices, permissions, and progression tiers.

1. Open the hopper shop.
2. Purchase an available hopper type.
3. Place the custom hopper.
4. Left-click it to open the management menu.
5. Connect supported containers.
6. Configure blacklist or whitelist filters.
7. Upgrade the hopper's statistics.
8. Manage fuel and additional settings.
9. Crouch and break the hopper to remove it safely.

When a tracked hopper is removed, SUPERHOPPER clears its stored location data and returns the corresponding custom hopper item to the player.


The built-in filter system gives players precise control over which items a hopper may transfer.

Filters can operate in either blacklist or whitelist mode. Optional strict matching can inspect additional item information, including CustomModelData, making the system suitable for servers using custom items and resource packs.

• Whitelist Mode — Only configured items are accepted.
  
• Blacklist Mode — Configured items are rejected.
  
• Strict Matching — Provides more precise comparisons for supported item properties.
  
• CustomModelData Support — Allows custom items to be distinguished from their vanilla base materials.

Connect a hopper to supported containers without building long chains of vanilla hoppers.

Links can be created through menus or commands and may be individually enabled, disabled, or removed. The maximum link count and link distance can also be controlled through hopper upgrades.

• Add container links
• Remove existing links
• Temporarily enable or disable links
• View linked container information
• Control maximum links through upgrades
• Control maximum link distance through upgrades

SUPERHOPPER includes an optional fuel and charge system that can create an ongoing economy cost for automated hoppers.

Fuel can be purchased through Vault economy or through configurable command-based currencies.

• Configure items provided per charge
• Set the cost of each charge
• Customize the displayed currency name
• Use Vault-supported economy plugins
• Use custom currency take and give commands

Players can locate and teleport to their owned hoppers using commands.

Server owners can configure:

• Teleport price
• Teleport preparation time
• Instant teleportation by setting the delay to 0
• Permission-based access

GUI configuration files are stored inside:


You can customize menu titles, materials, names, lore, buttons, slots, borders, pane colors, and border animation behavior.

• common.yml — Shared GUI defaults and border settings
• shop.yml — Hopper shop layout
• hopper_main.yml — Main hopper management menu
• links.yml — Container link management menu
• filter.yml — Item filter management menu
• filter_search.yml — Filter search and anvil menu settings

GUI borders can be configured as animated, static, or completely disabled.


SUPERHOPPER supports both local and remote database storage.

• SQLite — Simple local storage suitable for single-server setups.
  
• MySQL — Remote database storage suitable for larger or managed environments.
  
• Database Migration — Move hopper data between supported storage types using an administrator command.
  
• SQLite Import — Import hopper data from an existing SQLite file.

Main Command


Command Aliases


Player Commands

• /superhopper — Open the hopper shop.
• /superhopper help — Display player help.
• /superhopper shop — Open the hopper shop.
• /superhopper get <type> — Purchase or obtain an enabled hopper type.
• /superhopper list — List your placed hoppers.
• /superhopper view — List nearby hoppers.
• /superhopper view <query> — Toggle visualization for a matching hopper.
• /superhopper teleport <query> — Teleport to an owned hopper.
• /superhopper abort — Cancel a pending link or teleport action.
• /superhopper link stop — Exit link mode.
• /superhopper link list <hopper-id> — List a hopper's container links.
• /superhopper link add <hopper-id> <x> <y> <z> [world] — Add a container link.
• /superhopper link remove <hopper-id> <index> — Remove a link by its index.
• /superhopper link toggle <hopper-id> <index> <true/false> — Enable or disable a link.
• /superhopper rename <hopper-id> <name> — Rename an owned hopper.
• /superhopper delete <hopper-id> — Delete tracked hopper data.
• /superhopper toggleorder <hopper-id> <true/false> — Toggle ordered insertion behavior.

Administrator Commands

• /superhopper reload — Reload the plugin configuration and state.
• /superhopper admin — Display administrator help.
• /superhopper admin about — Display version, storage, hopper count, and integration information.
• /superhopper admin reload — Reload the plugin configuration and state.
• /superhopper admin give <player> <type> — Give a hopper item to a player.
• /superhopper admin playerhoppers <player> — List another player's hoppers.
• /superhopper admin listperms — Display common permission nodes.
• /superhopper admin migratedb <sqlite/mysql> — Migrate hopper data to another storage type.
• /superhopper admin import <sqlite-file> — Import hopper data from a SQLite file.

Player Permissions

• uhoppers.command.shop — Open the hopper shop.
• uhoppers.command.help — Use the help command.
• uhoppers.command.get — Use the hopper get command.
• uhoppers.command.list — List owned hoppers.
• uhoppers.command.view — View nearby hoppers and visualizations.
• uhoppers.command.abort — Cancel pending actions.
• uhoppers.teleport.hopper — Teleport to owned hoppers.

Administrator Permissions

• uhoppers.admin.command — Access the base administrator command.
• uhoppers.admin.command.about — View plugin and storage information.
• uhoppers.admin.command.reload — Reload the plugin.
• uhoppers.admin.command.give — Give hopper items to players.
• uhoppers.admin.command.playerhoppers — View another player's hoppers.
• uhoppers.admin.command.listperms — List plugin permissions.
• uhoppers.admin.command.migratedb — Migrate database storage.
• uhoppers.admin.command.import — Import SQLite hopper data.

Bypass Permissions

• uhoppers.bypass.open — Bypass supported opening and linking restrictions.
• uhoppers.bypass.upgrade — Bypass upgrade permission checks.
• uhoppers.bypass.delete — Bypass supported deletion restrictions.

When permission-based upgrades are enabled, upgrade permissions use the following format:


Example:

1. Stop your Minecraft server.
2. Place the SUPERHOPPER JAR file inside the server's plugins folder.
3. Start the server to generate the default configuration files.
4. Configure the files inside plugins/SuperHoppers/.
5. Run /superhopper admin reload or restart the server.
6. Assign the required permissions to your players and staff.

• Confirm that Java 21 or newer is installed.
• Install Vault and an economy plugin when using economy-based purchases or upgrades.
• Configure database and economy settings inside config.yml.
• Configure hopper types, prices, statistics, and upgrade levels inside hoppers.yml.
• Customize the menu files inside the gui folder if required.
• Give players the appropriate command and upgrade permissions.
• Test purchasing, placing, linking, filtering, upgrading, teleporting, and breaking hoppers.

• Paper-compatible Minecraft servers
• Folia server environments
• Java 21 or newer
• SQLite and MySQL databases

On Folia, linked container transfers use conservative behavior. Direct linked inventory access is limited to containers located within the same chunk as the hopper. Standard Paper servers retain normal linked-container behavior.


Required

• Java 21 or newer
• A compatible Paper or Folia server

Optional Economy Dependency

• Vault — Recommended when using economy-based hopper purchases, upgrades, fuel, or teleportation.

Optional Integrations

• RoseStacker
• FancyHolograms
• ShopGUIPlus
• Lands
• SuperiorSkyblock2
• BentoBox
• IridiumSkyblock
• PlotSquared
• WorldGuard
• WildStacker
• WildChests
• AdvancedChests
• SkinsRestorer
• NobleIslands

Optional integrations are not required for the core plugin to operate. Install only the integrations used by your server.