✨ WarpHopper – The Ultimate Routing Engine ✨

✔ Cross-Dimensional • ✔ Multi-Storage • ✔ Smart Chunk Loading • ✔ Independent Routing • ✔ Physical Pipeline Cost

MC Versions: 1.17 – 1.26.2 • JAR Size: ~625 KB • Storage: SQL, JSON, YAML, NBT • Highly Optimized

🌐︎ What is WarpHopper?

WarpHopper is an enterprise-grade item distribution solution designed to replace messy, lag-inducing hopper lines with invisible, wireless connections. It transforms standard hoppers into intelligent gateways that beam items across your base—and even across dimensions—directly into the containers they belong in, optimized for high-performance servers.

🚀︎ Why Choose WarpHopper?

• Cross-Dimensional Mastery — Link containers across the Overworld, Nether, and The End with seamless item routing.
• Smart Infrastructure — Avoid server overhead with dynamic chunk loading that keeps logistics moving without permanent performance costs.
• Enterprise Storage — Choose your engine: .dat, .yml, .json, MySQL, or MariaDB with built-in connection pooling.
• Physical Realism — A virtual pipeline system that charges physical hoppers based on distance, ensuring balanced gameplay.

🛠︎ The Logistics Engine

WarpHopper serves as the backbone for your server's automation:

1. Intelligent Router: Uses Independent Whitelist/Blacklist logic to ensure items go exactly where they are needed.
2. Cross-World Bridge: Seamlessly transfers goods between dimensions with configurable costs and safety guards.
3. Data Powerhouse: Offers a Pluggable Multi-Provider Storage system and a complete Migration Suite.
4. Maintenance Utility: Includes Internal Storage Chests, Hopper Inventory Views, and Global Blacklists.

🛡︎ Technical Deep Dives

• Smart Chunk Loading (Zero-Stall): Temporarily loads destination chunks only when needed, with dynamic scaling based on item volume and per-player safety limits.
• Virtual Pipeline Cost: Links aren't free; they deduct hoppers from your inventory based on Manhattan distance, with shared backbone support to reward efficient network design.
• Independent Routing Logic: A dual-track filter system where Blacklist filters act as entirely independent routes, never spilling over into default containers.
• Hot-Swap Storage Engine: Change your database type in config.yml and the plugin can automatically trigger an asynchronous migration on the fly.

⚙︎ Core Capabilities

• Zero-Lag Asynchronous Pipeline — All heavy data operations and logistics processing occur off the main thread to maintain 20 TPS.
• Cross-Dimensional Transfer — Routing items across worlds with dedicated chunk loading and configurable flat-rate costs.
• Physical Cost Integration — A distance-based hopper deduction system with exploit-safe refunds and shared route efficiency.
• Multi-Provider Storage (SQL/NoSQL) — Support for MySQL, MariaDB, JSON, YAML, and NBT with HikariCP connection pooling.
• Independent Whitelist/Blacklist Routing — Precise control over item paths with a visual filter status indicator.
• Per-Filter Destroy Mode — Permanently delete specific items at the source with live session counters.
• Smart Chunk Management — Automatic loading and unloading of destination chunks with per-player caps.
• Migration & Backup Suite — Interactive /wh migrate command with safe async transfers and automatic file backups.
• Global Item Blacklist — Prevent specific items from entering the logistics network entirely.
• Route Analytics — Real-time breakdown of independent, shared, and backbone paths for every filter.
• Internal Storage (Unrouted Items) — A 54-slot virtual inventory for items with no destination, preventing clogs.
• Hopper Inventory View — Access the physical hopper's vanilla inventory directly from the GUI.
• Config Auto-Updater — Automatically merges new configuration properties without losing custom settings.
• Streamlined Deletion — Fast, single-click management across all GUIs for a frictionless experience.

🚀︎ What's New in 3.5-pre

• Cross-Dimensional Routing 🌌 — Seamless logistics between the Overworld, Nether, and The End.
• Physical Infrastructure Cost 📱 — Manhattan distance-based hopper fees with shared backbone support.
• Independent Routing Filters 🔀 — Whitelist vs Blacklist logic with separate paths for filtered items.
• Pluggable Storage & Migration 💾 — Move your data between SQL, JSON, and YAML with a single command.
• Smart Chunk Loading ⚡ — Zero-stall delivery with dynamic load scaling and safety caps.
• Route Analytics 📊 — Visual breakdown of how your hoppers are being used across your network.

🚀︎ How to Setup

1. Download: Get the latest version of WarpHopper.
2. Install: Place the .jar file in your server's /plugins folder.
3. Configure: Start the server to generate config.yml. Choose your storage-type.
4. Reload: Use /wh reload to apply changes.

📜︎ Commands

Admin Commands

/wh reload — Force-refresh configurations and data with auto-field updating.
/wh migrate <type> — Migrate all data to a new storage format (SQL, YAML, etc.).
/wh stats — Monitor global throughput, total items warped, and network scale.

General Commands

/wh hopper — Convert the hopper you are looking at into a WarpHopper.
/wh unregister — Decommission the hopper and purge its routing data.
/wh info — Display ownership, link saturation, and active admins.
/wh addadmin <p> — Grant a teammate management rights to your hopper.
/wh removeadmin <p> — Revoke management authorization from a player.

Permissions

warphopper.use    — Standard access to convert and manage hoppers. (Default: true)
warphopper.admin  — Access to global stats and administration tools. (Default: OP)
warphopper.reload — Permission to reload the plugin configuration. (Default: OP)

# ─────────────────────────────────────────────
#   WarpHopper v3.5-pre  ·  Configuration
# ─────────────────────────────────────────────

# Ticks between each transfer cycle. 20 ticks = 1 second.
# Raise this to reduce CPU usage on busy servers.
transfer-interval-ticks: 20

# Max items transferred to a SINGLE linked container per cycle.
# Increasing this will move items faster but may impact performance if set too high.
transfer-amount: 5

# Max items taken from the source hopper inventory per cycle.
# This governs how many items the hopper can pull out in one go.
source-take-amount: 5

# Auto-save interval in ticks. 6000 ticks = 5 minutes.
# Data is also saved immediately on server shutdown.
auto-save-interval: 6000

# Maximum size of a region selection (per axis) when using Region Link.
# e.g. 100 means up to 100×100×100 block cube = 1,000,000 blocks scanned.
# Keep this reasonable; scanning is performed synchronously.
max-region-size: 100

# Maximum number of containers that can be linked to a single WarpHopper.
# Default: 300 (can be set to 500 or more as needed).
max-links-per-hopper: 300

# Round-robin item distribution across linked containers.
# true  → items cycle evenly: chest1 → chest2 → chest3 → chest1 …
# false → fill-first: fill chest1 before moving to chest2
round-robin: false

# When round-robin is true, should leftover items that didn't fit in one container
# continue to the NEXT container in the list within the same cycle?
round-robin-overflow: true

# ─────────────────────────────────────────────
#   Storage Configuration
# ─────────────────────────────────────────────
# Available types: yml, json, dat, mysql, mariadb
storage-type: yml

# Database credentials (only used if storage-type is mysql or mariadb)
database:
  host: "localhost"
  port: 3306
  name: "warphopper"
  username: "root"
  password: "password"

# ─────────────────────────────────────────────
#   Enterprise Features
# ─────────────────────────────────────────────
# Allow linking containers across different worlds/dimensions (e.g. Overworld -> Nether)
allow-cross-dimensional-transfer: true

# Smart Chunk Loading: Temporarily load target chunks if they are unloaded,
# guaranteeing item delivery even when no players are nearby.
smart-chunk-loading: true

# Base ticks to keep the chunk loaded. (20 ticks = 1 second)
# The plugin will dynamically increase this based on the amount being transferred.
base-chunk-load-ticks: 20

# Max number of chunks a single player can force-load at once (prevents abuse)
max-temp-chunks-per-player: 2

# Should transferring across dimensions load the target chunk in the other dimension?
cross-dim-chunk-loading: true

# Base ticks to keep cross-dimensional chunks loaded.
cross-dim-chunk-load-ticks: 20

# Max number of cross-dimension chunks a single player can force-load at once
cross-dim-max-chunks-per-player: 2

# Flat hopper cost charged ONCE when a cross-dimensional link is created.
# This represents the "portal infrastructure" fee for bridging two dimensions.
# Set to 0 to disable (cross-dim links cost only distance, same as same-world links).
# Shared routes: if you already have a link to the same destination world, the fee
# is NOT charged again — the portal infrastructure is considered shared.
cross-dim-flat-cost: 0

# ─────────────────────────────────────────────
#   Hopper Deposit System
# ─────────────────────────────────────────────
# Set to true to require physical hopper items to be deposited to link containers.
use-hopper-deposit-system: true

# The maximum distance (radius) within which multiple WarpHoppers can share routes.
shared-connection-radius: 25.0

Superior logistics. Optimized performance. Smarter storage.
Developed with Precision by BlackForge Studio