HopperFlow Governor
⚖️ Smart hopper & inventory-move throttling for Minecraft servers (1.21+).
Keep TPS high without breaking vanilla mechanics — no NMS, no item loss.





✨ Features

• ️️ Protects TPS — throttles only the extra hopper / dropper / dispenser / hopper-minecart moves per tick.
• ⚙️ Fully configurable — per-chunk, per-type, and global rate limits with burst tokens.
• ⚙️ Real-time diagnostics — /hopperflow inspect, /detail, /where, /top.
• No NMS hacks — pure Spigot API; forward-compatible across versions.
• Player-friendly — no item loss, optional actionbar notices when throttling happens nearby.
• ️ ️ WorldGuard integration — exempt specific regions seamlessly.
• Exemptions — by world, region, or container name prefix (e.g. [FAST] hoppers).
• Optional metrics — bStats (opt-in) for server owners who want usage stats.
• Minimal overhead — optimized for large servers with thousands of hoppers.

Installation

1. Download the latest release from SpigotMC / Modrinth.
2. Drop HopperFlowGovernor-x.x.x.jar into your server’s plugins/ folder.
3. Restart the server. A default config.yml will be created.

⚙️ Configuration
The default config.yml comes heavily commented:

# HopperFlow Governor — caps inventory move events to stabilize TPS.
# Pure Bukkit. No item loss. Cancels only excess moves per tick window.

# Global per-chunk defaults (used when no per-type override exists)
rate_per_chunk_per_sec: 80 # default average moves/s per chunk
burst_per_chunk: 120 # default short-term burst tokens per chunk

# Global ceiling across all chunks
max_global_rate: 5000 # average moves/s allowed globally

# Optional per-type overrides; omit or set null to use the global defaults above
per_type_limits:
hopper_block: { rate: 80, burst: 120 }
hopper_minecart: { rate: 40, burst: 80 }
dropper: { rate: 40, burst: 80 }
dispenser: { rate: 20, burst: 40 }

# Which initiators are governed?
include:
hopper_blocks: true # vanilla block hoppers
hopper_minecarts: false # hopper minecart entities
droppers: false # droppers pushing into inventories
dispensers: false # dispensers pushing into inventories

# Name-prefix exemptions per type (renaming the container/minecart bypasses throttle)
exempt_name_prefixes:
hopper_block: "[FAST]"
hopper_minecart: ""
dropper: ""
dispenser: ""

# World and WorldGuard exemptions
exempt_worlds: [ the_end ]
exempt_regions: [ ] # WG region IDs (if WorldGuard is installed)

# Player feedback
notify_players_near_throttle: true
notify_radius: 16

# Accounting window + cleanup
stats_window_seconds: 60 # time window used by /inspect, /detail, /where, /top
cleanup_after_minutes: 15 # drop idle chunk stats/buckets

# Telemetry (bStats) — opt-in.
metrics:
enabled: true

️ Commands & Permissions

Command Permission Default Description
/hopperflow help hopperflow.command.help OP Shows help message
/hopperflow reload hopperflow.command.reload OP Reloads config.yml
/hopperflow inspect hopperflow.command.inspect OP Shows summary for current chunk
/hopperflow detail hopperflow.command.detail OP Per-initiator breakdown (hoppers, droppers, etc.)
/hopperflow where [N] hopperflow.command.where OP Lists top throttled block/entity locations in this chunk
/hopperflow top [N] hopperflow.command.top OP Ranks chunks globally by throttling
Aliases: /hflow, /hfg

Example Usage

• Rename a hopper to [FAST] → it bypasses limits (custom sorters, farms).
• /hopperflow top 5 → list 5 worst offending chunks in the last 60s.
• /hopperflow where 10 → find the exact block coordinates being throttled.
• Place hoppers inside a WorldGuard region → exempt automatically if region ID is listed.

Metrics

• bStats integration is included but disabled by default (metrics.enabled: false).
  
  
• If enabled, the plugin will anonymously report:
  • HopperFlowGovernor version
  • Minecraft version
  • Server count
• No personal or identifying data is collected.
  
  
• The use case for metrics is to help prioritize future development based on usage patterns.

Performance Notes

• This plugin does not delete or void items.
• It only cancels extra InventoryMoveItemEvent calls beyond configured thresholds.
• Works safely alongside plugins like ClearLag, WorldGuard, and Paper’s async chunk system.

API / Compatibility

• Pure Bukkit/Spigot API — no Paper-only hooks, no NMS.
• Compatible with Paper, Spigot, Purpur (tested on 1.21+).
• WorldGuard integration is optional (soft-depend).

Contributing

1. Fork this repo & clone locally.
2. Run mvn package to build.
3. Test in a local Paper server (/plugins/).
4. Submit a PR with clear commit history.

Bug reports & feature requests → GitHub Issues.

License
This project is licensed under the NFE-OSL License.

❤️ Credits

• Developed by Nolly (@TheNolle)
• Inspired by community feedback on hopper lag issues
• Thanks to bStats and SpigotMC for tooling