SmartHoppers

# SmartHoppers: Next-Gen Item Logistics & Filtering

Tired of massive, lag-inducing redstone sorters eating your server’s tick rates? Frustrated by vanilla’s sluggish 8-tick hopper cooldown bottlenecking your players' farms?

**SmartHoppers** is a modern, high-performance item transport and sorting plugin built for Paper, Purpur, and Folia servers. It combines granular, multi-tiered hopper speed control with an intuitive in-game GUI for whitelist/blacklist filtering and priority routing—giving your players industrial-grade item sorting in a single block.

---

### ⚡ Why Server Owners Love SmartHoppers

* ** Lag-Free Speed Engine**: Accelerate item transfers down to 1-tick intervals without running aggressive polling loops on idle containers.
* **️ Zero-Redstone GUI Filtering**: Shift-click items into a virtual GUI to configure Whitelist or Blacklist modes. No more hoppers clogged with junk items or multi-story comparator towers!
* ** Positional Priority Routing**: Sort items by importance. Items in Slot 1 of the whitelist take extraction precedence over later slots, enabling compact multi-item sorting setups.
* ** Built for Multi-Threading (Folia-Native)**: Designed from day one with region-aware scheduling (`SchedulerAdapter`). Runs flawlessly on both single-threaded Paper and multi-threaded Folia servers without race conditions or chunk desyncs.
* ** Hopper Minecart Parity**: Fast-moving farm collection lines enjoy identical speed control, filtering, and priority options.
* ** Zero Database Overhead**: All rules and speeds persist natively inside Minecraft's `PersistentDataContainer` (PDC). Zero SQL queries, zero flatfiles, and zero risk of database corruption.

---

### How It Works

1. **Grab a Tuner**: Hold the designated tuner item (default: a standard piece of `Paper`).
2. **Right-Click Any Hopper**: Open the clean, interactive settings interface on block hoppers or hopper minecarts.
3. **Choose Your Filter Mode**:
* **Whitelist**: Only allow specific items through.
* **Blacklist**: Block unwanted junk items (like seeds, bows, or poison potatoes) from ever entering the pipeline.
* **Pass-Through**: Standard vanilla item flow.
4. **Set Your Priority**: Place target items into filter slots from your inventory. Items placed in earlier slots are pulled first from source containers!
5. **Close & Play**: Changes save instantly directly to the block.

---

### ️ Configuration & Customization

Tune global rates, set dimensional rules (e.g., conservative speeds in the Nether or End), or alter the tuner item in seconds via `config.yml`:

```yaml
settings:
check-for-updates: true
default-tick-interval: 4 # Vanilla is 8 ticks (lower = faster)
minecart-tick-interval: 4
min-tick-interval: 1 # Safety clamp preventing CPU spikes
allow-per-hopper-override: true
allow-per-world-override: true

world-overrides:
world_nether: 6
world_the_end: 6

gui:
tuner-item: "PAPER"
title: "&8Hopper Settings"
size: 27