✨ Why admins love it
- One smart hopper per system → far fewer ticking blocks, lower server load. - Remote routing across the same world with priorities, filters, round-robin/fill-first. - Lag-aware batching, skips blocked/unloaded targets, optional bounded retry queue. - Claim & trust built-in (or hook your region plugin); admin bypass supported. - No commands needed for normal play — everything via a clear in-game GUI. - Optional power system (free, redstone, or fuel chest → power units). - Demo: YouTube – Quick Tour
---
📦 Requirements & Compatibility
- Hard dependency: Hard dependency: (for economy; needed for smelter unlocks & upgrades).
- Soft dependencies: - Soft dependencies: — floating HUD above nodes (ACTIVE/IDLE, last transfer, power). - %%MD1%% — dynamic, permission-based limits. - %%MD2%% or %%MD3%% — per-island limits & trust interop.
- Servers: Paper/Spigot 1.20+ (API 1.21 targeted).
- Regions: Works with GriefPrevention/WorldGuard; ships a lightweight internal claim system if absent.
---
🚀 What it does (Core Features)
Remote Item Routing
Link one Improved Hopper to many containers in the same world. Configure:
- Per-target priority (higher first) - Whitelist/blacklist item filters - Distribution: Round-robin or Fill-first
Full In-Game GUI
Right-click: manage links, filters, power, trust, stats, simulate routes, toggle visuals.
Chat Search for Filters
Click the compass, type to search; Esc or “cancel” to exit.
Power Modes
- None: free operation - Redstone: `requireRedstonePower` or `pauseWhenPowered` - Fuel: link a Fuel Chest; fuel items convert to Power Units based on distance & amount
Trust & Claims
Hoppers must be claimed; owner can `/trust` users; admins bypass. Crafted nodes auto-claim.
Lag-Aware Batching
Per-tick caps & smart skipping of empty inputs/blocked/unloaded targets.
Visual Tools
Particle beams to targets; transfer trails; filter-focus visualization.
Built-in Smelter (optional)
Virtual smelting with Vault unlock & upgrades.
Craftable
Recipes configurable for both Improved Hopper and Fuel Chest.
---
🛠️ Installation
1. Place the JAR in `/plugins`. 2. Ensure Vault is installed and an economy plugin is active. 3. (Optional) Install DecentHolograms, LuckPerms, and your Skyblock plugin. 4. Start server. Edit `/plugins/ImprovedHoppers/config.yml` if desired. 5. `/improvedhoppers reload` to apply changes.
---
⚡ Quick Start (Player)
1. Craft an Improved Hopper (and a Fuel Chest if using Fuel mode). 2. Place & Claim the hopper (crafted nodes auto-claim). 3. Open GUI → Add Targets → click containers to link Tip: `/improvedhoppers wand` for fast multi-link. 4. Set filters, priorities, and distribution mode. 5. Choose Power Mode. If Fuel, link Fuel Chest and insert fuel. 6. (Optional) Add redstone depending on redstone settings.
---
⌨️ Commands
| Command | Description | Permission | |---------------------------------|------------------------------------------|-----------------------------------------------------------------| | `/improvedhoppers` | Show subcommands | (none) | | `/improvedhoppers wand` | Get link wand for multi-linking | `improvedhoppers.user.wand` | | `/improvedhoppers settings` | Open settings (node or admin view) | `improvedhoppers.user.settings` / `improvedhoppers.admin.settings` | | `/improvedhoppers remote` | Remote controller (view/manage anywhere) | `improvedhoppers.user.remote` | | `/improvedhoppers reload` | Reload config | `improvedhoppers.admin.reload` | | `/improvedhoppers power apply` | Re-apply power settings | `improvedhoppers.admin` |
---
🔐 Permissions
User
- `improvedhoppers.user.wand` (default: true) - `improvedhoppers.user.settings` (default: true) - `improvedhoppers.user.remote` (default: true) - `improvedhoppers.user.*` (default: true) - `improvedhoppers.user.restore` (default: true)
Admin
- `improvedhoppers.admin` (default: op) — moderation bypass - `improvedhoppers.admin.reload` (default: op) - `improvedhoppers.admin.settings` (default: op) - `improvedhoppers.admin.*` (default: op)
Limits (override config)
- `improvedhoppers.limit.player.<n>` - `improvedhoppers.limit.island.<n>` - `improvedhoppers.limit.links.<n>` - `improvedhoppers.limit.trusted.<n>` - `improvedhoppers.limit.filter.<n>` - `improvedhoppers.hopper.power.<n>`
---
🧪 Crafting
Improved Hopper — shaped recipe (all items configurable)
``` I C I R H R I C I ```
Fuel Chest — configurable (e.g., coal + chest) See `recipes.yml` for exact materials, names, and NBT settings.
---
⚙️ Config Highlights (sample)
```yaml general: storage: YAML # YAML | SQLITE locale: en_US holograms: enabled: true update_ticks: 20 particles: enabled: true transfer_trail: true filter_focus: true
claims: required: true auto_claim_on_craft: true admin_bypass: true
routing: link: max_distance: 256 owner_must_be_online: false cleanup_interval_ticks: 200 distribution: ROUND_ROBIN # ROUND_ROBIN | FILL_FIRST filters: default_mode: WHITELIST # WHITELIST | BLACKLIST per_hopper_max: 32
transfer: interval_ticks: 10 per_tick_item_cap: 256 suction: radius: 2.5 enabled: true cost_per_item: 0 retry_queue: enabled: true max_entries: 2048
power: mode: NONE # NONE | REDSTONE | FUEL redstone: require_power: false pause_when_powered: true fuel: enabled: false # flip to true to use fuel capacity: 10000 regen_per_tick: 0 distance_cost_per_block: 0.25 amount_cost_per_item: 0.05 auto_refuel: true link_limit: 1 max_link_distance: 16 fuels: COAL: 160 CHARCOAL: 160 BLAZE_ROD: 240
smelter: enabled: true base_cook_ticks: 200 queue_size: 128 unlock_cost: 1000 # Vault currency upgrade_costs: level_2: 2500 level_3: 5000
limits: per_player: 20 per_island: 50 links_per_material: 4 trusted_slots: 8
storage: type: yaml # Storage backend: yaml, sqlite, h2, or mysql (yaml default) save: debounceTicks: 30 # Delay in ticks before saving after changes (0 = immediate) intervalSeconds: 0 # Periodic autosave interval in seconds (0 = disabled) h2: file: hoppers # H2 database file (stored in plugin folder) options: "" # Optional H2 connection options (e.g. AUTO_SERVER=TRUE) username: "sa" password: "" mysql: host: localhost port: 3306 database: improvedhoppers username: root password: "" parameters: "useUnicode=true&characterEncoding=utf8&serverTimezone=UTC&useSSL=false&allowPublicKeyRetrieval=true" ```
> Note: Vanilla `InventoryMoveItemEvent`/`InventoryPickupItemEvent` are cancelled for claimed nodes to avoid conflicts.
---
🧭 Routing Logic (at a glance)
1. Pull up to `per_tick_item_cap` from source inventory. 2. Filter items (whitelist/blacklist). 3. Order targets by priority, remove unloaded or blocked. 4. Fill-first: - Fill-first: cycle targets per item type. - Fill-first: fill the first valid target until it can’t accept more. 5. Power accounting (if enabled): distance & amount → PU cost. 6. Apply retry queue if a move fails and queue is enabled.
---
📈 Performance Notes
- Batches and caps per tick to keep TPS smooth. - Skips empty sources & blocked/unloaded targets to save time. - Optional distance-scaled power discourages extreme cross-map links. - Visualizer is per-player; filter-focused trails reduce particle spam.
---
🧩 Compatibility & Hooks
- Hooks: Vault, LuckPerms, DecentHolograms, SuperiorSkyblock2, BentoBox, GriefPrevention, WorldGuard. - Ships internal claims if none detected.
---
🧰 Admin Tools
Look at a node and run `/improvedhoppers settings` (admin view) to live-tune: link distance, suction/transfer caps, fuel values, smelter rates, limits, particles/holograms, world allowlists, recipes, and more.
---
🧑💻 API & Events (for developers)
Events (examples)
- `HopperSorterTransferEvent` — per successful transfer - `HopperSorterFuelConsumeEvent` — on fuel → power conversion - `HopperSorterClaimEvent` — when ownership/claims change - Overflow & alert hooks
Example Listener
```java @EventHandler(ignoreCancelled = true, priority = EventPriority.MONITOR) public void onTransfer(HopperSorterTransferEvent e) { Player owner = e.getOwner(); ItemStack stack = e.getItem(); Location from = e.getSource(); Location to = e.getTarget(); int moved = e.getAmount(); // e.getCostPU() if fuel mode; e.isSimulated() for dry runs if (owner != null && owner.isOnline()) { owner.sendActionBar(Component.text("§aMoved " + moved + "x " + stack.getType() + " → " + pretty(to))); } } ```
Minimal API sketches available for fuel providers & virtual targets.
---
💾 Storage & Persistence
- YAML (default) or SQLite. - Persists node power, names, particle colors, links, smelter state safely.
---
❓ FAQ
Q: Can I disable the power system? A: Yes. It’s off by default; set `power.fuel.enabled: true` to use Fuel.
Q: Can players manage hoppers remotely? A: Yes. `/improvedhoppers remote` opens a network overview or the node GUI.
Q: Do vanilla hopper pulls still happen on claimed nodes? A: No. We cancel vanilla move/pickup events for claimed nodes to prevent conflicts.
---
🧪 Troubleshooting
- No transfers happening → Check claims/ownership and power mode. - Hologram missing → Install/enable DecentHolograms and ensure `holograms.enabled: true`. - Skyblock limits ignored → Ensure SSB2/BentoBox present; confirm LuckPerms dyn-limits if using permission overrides. - High distance cost → Lower `power.fuel.distance_cost_per_block` or increase capacity.
