✨ 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: Vault (for economy; needed for smelter unlocks & upgrades).

• Soft dependencies:

  • DecentHolograms — floating HUD above nodes (ACTIVE/IDLE, last transfer, power).
  • LuckPerms — dynamic, permission-based limits.
  • SuperiorSkyblock2 or BentoBox — 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)

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. Distribution:
   • Round-robin: 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

@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.