Warp Hopper

WarpHopper v3.5-pre – The Ultimate Cross-Dimensional Logistics & Storage Engine

WarpHopper v3.5-pre introduces a massive architectural evolution. This update features cross-dimensional item routing, highly-optimized smart chunk loading to prevent server overhead, a pluggable multi-provider storage system supporting SQL databases, an automated data migration and backup suite, and a completely redesigned filter system with independent Whitelist/Blacklist routing, per-filter destroy mode, and deep route analytics. ---

Version 3.5-pre Change-log

Physical Infrastructure Cost (Virtual Pipeline)

- Distance-Based Cost: Linking containers now deducts physical hoppers from your inventory based on exact Manhattan distance. - Shared Routes: Overlapping paths in the same direction share hopper costs, forming an efficient, branching pipeline. - Pending Deposits: If you lack enough hoppers, the plugin sets a 10-minute pending state (use deposit all or cancel). - Exploit-Safe Refunds: Unlinking containers smartly calculates orphaned route segments and dynamically refunds the exact unused hoppers. [Click here for more detailed about the architecture of the 3.5-pre](https://github.com/BlackForgeStudio/Warp-Hopper/blob/main/Architecture.md)

Cross-Dimensional Routing

- Cross-World Links: Containers can now be linked across different dimensions (Overworld, Nether, and The End). WarpHopper routes items across dimensions seamlessly. - Configurable Control: Toggle cross-dimensional transfers server-wide via allow-cross-dimensional-transfer (default: true).

Smart Chunk Loading

- Zero-Stall Delivery: If a linked destination container resides in an unloaded chunk, WarpHopper temporarily loads the chunk to deposit the item and schedules it to unload immediately after. - Dynamic Load Scaling: Chunk load duration scales dynamically. It starts at a base load time (base-chunk-load-ticks, default: 20 ticks / 1 second) and adds 8 ticks per item transferred to guarantee complete logistics delivery. - Per-Player Safety Limits: Players are capped to a configurable maximum of concurrent temporarily loaded chunks (max-temp-chunks-per-player, default: 2) to safeguard server performance. - Cross-Dimensional Load Protection: Cross-dimensional loading is independently controlled via cross-dim-chunk-loading (default: true), cross-dim-chunk-load-ticks (default: 20 ticks), and its own per-player ticket cap cross-dim-max-chunks-per-player (default: 2). - Source Chunk Keeps Alive: Optionally loads the source hopper's chunk if it unloads during a cross-dimensional transfer to keep high-speed transfers active.

Pluggable Multi-Provider Storage

- 5 Supported Engines: Swap between .dat (NBT), .yml (YAML), .json (JSON), MySQL, and MariaDB by updating the storage-type option in config.yml. - Database Connection Pooling: Built-in connection pooling for MySQL and MariaDB via shaded HikariCP for fast, non-blocking off-thread operations. - Robust Schema Auto-Creation: Database tables are automatically initialized and indexed for rapid queries.

Migration & Auto-Config Suite

- Interactive Migration Command: Use /wh migrate <type> to migrate all WarpHopper data from the active storage type to any of the other four formats. - Safe Async Transfers: Data migration runs asynchronously in a background thread to ensure zero gameplay spikes or server lag. - Automatic Backups: Migrating from file-based storage automatically creates a backup of the source files named in the format (storage).(storageType).backup (e.g. hoppers.yml.backup). - Config Auto-Updater: Whenever /wh reload or the plugin starts, WarpHopper merges new configuration properties from the default template into the user's existing config.yml without modifying their custom settings (e.g., maintaining a user's custom round-robin or transfer-interval-ticks). - Hot-Swap Engine: Reloading the plugin with a changed storage-type in config.yml automatically triggers an asynchronous migration on the fly.

Whitelist vs Blacklist Filters — Independent Routing

Every item filter now carries an explicit type that controls exactly how items are routed through the system: | Type | Behaviour | |---|---| | Whitelist (default) | Items go to the filter containers first; any remainder falls through to default routing as normal. | | Blacklist | Items go to filter containers only — they are never forwarded to default routing, giving them a fully independent route. | - Status displayed on every filter — the main menu shows each filter's type with colour coding: [W] in green for Whitelist, [B] in red for Blacklist, so you can tell at a glance which filters are independent. - Default routing is smart — default containers only receive items that have no filter at all, or items from a Whitelist filter that still have remainder capacity. Blacklist filter items never reach default routing under any circumstance. - Change Status button — inside every filter menu, a dedicated Change Status button (slot 3) lets you flip a filter between Whitelist and Blacklist instantly with a single click. The change is saved immediately.

Dual "Add Filter" Buttons

The main menu now has two dedicated filter creation buttons instead of one: | Slot | Button | Effect | |---|---|---| | 0 | Add Whitelist Filter (green glass pane) | Creates a Whitelist filter for the item held in your main hand. Remainder items fall through to default routing. | | 1 | Add Blacklist Filter (red glass pane) | Creates a Blacklist filter for the item held in your main hand. Items follow this filter exclusively and never reach default routing. | Hold the item you want to filter in your main hand, then click the appropriate button.

Per-Filter Destroy Mode

Feature suggested by [@mhk924](https://github.com/mhk924) — thank you for the idea!

Each individual filter can have its own Destroy Mode, giving fine-grained control over which item types are permanently deleted rather than routed. - Destroy Mode toggle — slot 4 inside every filter menu. Lava Bucket icon means destroy mode is ON; empty Bucket means it is OFF. - Live destroyed-items counter — hovering over the lava bucket shows exactly how many items that specific filter has destroyed during the current server session. The counter resets on server restart. - Routing priority — destroy mode fires before any container routing. If a filter has destroy mode enabled, matching items are permanently deleted and the counter is incremented; no containers are touched at all. - Works with both filter types — destroy mode is independent of whether the filter is Whitelist or Blacklist. - Fully persisted — destroy filter settings are saved across all five storage backends.

Global Item Blacklist (Default Routing)

- Per-Hopper Blacklist: Block specific item types from ever being transferred by a WarpHopper, no matter how many default links are configured. - In-GUI Management: Open the Default Routing menu and click the red glass pane (slot 1 of the toolbar): - Hold an item + click to toggle that item type on or off the blacklist. - Empty hand + click to print the current blacklist to chat. - Empty hand + shift-click to clear the entire blacklist instantly. - Fully Persisted: The blacklist is saved and loaded across restarts for all five storage backends (YAML, JSON, DAT, MySQL, MariaDB). - Zero Performance Overhead: Blacklist rejection happens at the very start of the transfer pipeline — blacklisted items are skipped in a single Set.contains() check before any container access.

Per-Filter Route Analytics

Every filter entry in the main menu now displays a full route breakdown without needing to open the filter menu: - **Li