![](\"https:\/\/github.com\/Nolly-MC\/HopperFlowGovernor\/blob\/main\/logo.png?raw=true\"){kind=logo}
<\/img> HopperFlow Governor<\/p>\n# <\/img> HopperFlow Governor<\/p>\n
> \u2696\ufe0f Smart hopper & inventory-move throttling for Minecraft servers (1.21+).
\n> Keep TPS high without breaking vanilla mechanics \u2014 no NMS, no item loss.<\/p>\n
\n
\n<\/p>\n
—<\/p>\n
## \u2728 Features<\/p>\n
– \ud83d\udee1\ufe0f **Protects TPS** \u2014 throttles only the *extra* hopper \/ dropper \/ dispenser \/ hopper-minecart moves per tick.
\n– \u2699\ufe0f **Fully configurable** \u2014 per-chunk, per-type, and global rate limits with burst tokens.
\n– \ud83d\udcca **Real-time diagnostics** \u2014 `\/hopperflow inspect`, `\/detail`, `\/where`, `\/top`.
\n– \ud83d\udeab **No NMS hacks** \u2014 pure Spigot API; forward-compatible across versions.
\n– \ud83c\udfae **Player-friendly** \u2014 no item loss, optional actionbar notices when throttling happens nearby.
\n– \ud83d\uddfa\ufe0f **WorldGuard integration** \u2014 exempt specific regions seamlessly.
\n– \ud83e\udde9 **Exemptions** \u2014 by world, region, or container name prefix (e.g. `[FAST]` hoppers).
\n– \ud83d\udcc8 **Optional metrics** \u2014 bStats (opt-in) for server owners who want usage stats.
\n– \ud83d\udd12 **Minimal overhead** \u2014 optimized for large servers with thousands of hoppers.<\/p>\n
—<\/p>\n
![\"help\"](\"https:\/\/github.com\/Nolly-MC\/HopperFlowGovernor\/blob\/main\/docs\/screenshots\/help.png?raw=true\")
<\/img> ![\"top\"](\"https:\/\/github.com\/Nolly-MC\/HopperFlowGovernor\/blob\/main\/docs\/screenshots\/top.png?raw=true\")
<\/img> ![\"where\"](\"https:\/\/github.com\/Nolly-MC\/HopperFlowGovernor\/blob\/main\/docs\/screenshots\/where.png?raw=true\")
<\/img> ![\"inspect\"](\"https:\/\/github.com\/Nolly-MC\/HopperFlowGovernor\/blob\/main\/docs\/screenshots\/inspect.png?raw=true\")
<\/img> ![\"detail\"](\"https:\/\/github.com\/Nolly-MC\/HopperFlowGovernor\/blob\/main\/docs\/screenshots\/detail.png?raw=true\")
<\/img> ![\"actionbar\"](\"https:\/\/github.com\/Nolly-MC\/HopperFlowGovernor\/blob\/main\/docs\/screenshots\/actionbar.png?raw=true\")
<\/img><\/p>\n
—<\/p>\n
## \ud83d\udce5 Installation<\/p>\n
1. Download the latest release from SpigotMC \/ `Modrinth`.
\n2. Drop `HopperFlowGovernor-x.x.x.jar` into your server\u2019s `plugins\/` folder.
\n3. Restart the server. A default `config.yml` will be created.<\/p>\n
—<\/p>\n
## \u2699\ufe0f Configuration<\/p>\n
The default `config.yml` comes heavily commented:<\/p>\n
“`yml
\n# HopperFlow Governor \u2014 caps inventory move events to stabilize TPS.
\n# Pure Bukkit. No item loss. Cancels only excess moves per tick window.<\/p>\n
# Global per-chunk defaults (used when no per-type override exists)
\nrate_per_chunk_per_sec: 80 # default average moves\/s per chunk
\nburst_per_chunk: 120 # default short-term burst tokens per chunk<\/p>\n
# Global ceiling across all chunks
\nmax_global_rate: 5000 # average moves\/s allowed globally<\/p>\n
# Optional per-type overrides; omit or set null to use the global defaults above
\nper_type_limits:
\n hopper_block: { rate: 80, burst: 120 }
\n hopper_minecart: { rate: 40, burst: 80 }
\n dropper: { rate: 40, burst: 80 }
\n dispenser: { rate: 20, burst: 40 }<\/p>\n
# Which initiators are governed?
\ninclude:
\n hopper_blocks: true # vanilla block hoppers
\n hopper_minecarts: false # hopper minecart entities
\n droppers: false # droppers pushing into inventories
\n dispensers: false # dispensers pushing into inventories<\/p>\n
# Name-prefix exemptions per type (renaming the container\/minecart bypasses throttle)
\nexempt_name_prefixes:
\n hopper_block: “[FAST]”
\n hopper_minecart: “”
\n dropper: “”
\n dispenser: “”<\/p>\n
# World and WorldGuard exemptions
\nexempt_worlds: [ the_end ]
\nexempt_regions: [ ] # WG region IDs (if WorldGuard is installed)<\/p>\n
# Player feedback
\nnotify_players_near_throttle: true
\nnotify_radius: 16<\/p>\n
# Accounting window + cleanup
\nstats_window_seconds: 60 # time window used by \/inspect, \/detail, \/where, \/top
\ncleanup_after_minutes: 15 # drop idle chunk stats\/buckets<\/p>\n
# Telemetry (bStats) \u2014 opt-in.
\nmetrics:
\n enabled: true
\n“`<\/p>\n
—<\/p>\n
## \ud83d\udda5\ufe0f Commands & Permissions<\/p>\n
| Command | Permission | Default | Description |
\n|————————-|——————————|———|———————————————————-|
\n| `\/hopperflow help` | `hopperflow.command.help` | OP | Shows help message |
\n| `\/hopperflow reload` | `hopperflow.command.reload` | OP | Reloads config.yml |
\n| `\/hopperflow inspect` | `hopperflow.command.inspect` | OP | Shows summary for current chunk |
\n| `\/hopperflow detail` | `hopperflow.command.detail` | OP | Per-initiator breakdown (hoppers, droppers, etc.) |
\n| `\/hopperflow where [N]` | `hopperflow.command.where` | OP | Lists top throttled block\/entity locations in this chunk |
\n| `\/hopperflow top [N]` | `hopperflow.command.top` | OP | Ranks chunks globally by throttling |<\/p>\n
**Aliases:** `\/hflow`, `\/hfg`<\/p>\n
—<\/p>\n
## \ud83d\udd0d Example Usage<\/p>\n
* Rename a hopper to `[FAST]` \u2192 **it bypasses limits** (custom sorters, farms).
\n* `\/hopperflow top 5` \u2192 list 5 worst offending chunks in the last 60s.
\n* `\/hopperflow where 10` \u2192 find the **exact block coordinates** being throttled.
\n* Place hoppers inside a WorldGuard region \u2192 exempt automatically if region ID is listed.<\/p>\n
—<\/p>\n
## \ud83d\udcc8 Metrics<\/p>\n
* bStats integration is included but **disabled by default** (`metrics.enabled: false`).
\n* If enabled, the plugin will anonymously report:<\/p>\n
* HopperFlowGovernor version
\n * Minecraft version
\n * Server count
\n* No personal or identifying data is collected.
\n* The use case for metrics is to help prioritize future development based on usage patterns.<\/p>\n
—<\/p>\n
## \ud83d\udd27 Performance Notes<\/p>\n
* This plugin does **not** delete or void items.
\n* It only cancels *extra* `InventoryMoveItemEvent` calls beyond configured thresholds.
\n* Works safely alongside plugins like ClearLag, WorldGuard, and Paper\u2019s async chunk system.<\/p>\n
—<\/p>\n
## \ud83d\udcda API \/ Compatibility<\/p>\n
* Pure **Bukkit\/Spigot API** \u2014 no Paper-only hooks, no NMS.
\n* Compatible with Paper, Spigot, Purpur (tested on 1.21+).
\n* WorldGuard integration is optional (soft-depend).<\/p>\n
—<\/p>\n
## \ud83e\udd1d Contributing<\/p>\n
1. Fork this repo & clone locally.
\n2. Run `mvn package` to build.
\n3. Test in a local Paper server (`\/plugins\/`).
\n4. Submit a PR with clear commit history.<\/p>\n
Bug reports & feature requests \u2192 GitHub Issues.<\/p>\n
—<\/p>\n
## \ud83d\udcdc License<\/p>\n
This project is licensed under the NFE-OSL License.<\/p>\n
—<\/p>\n
## \u2764\ufe0f Credits<\/p>\n
* Developed by **Nolly** (@TheNolle)
\n* Inspired by community feedback on hopper lag issues
\n* Thanks to bStats and SpigotMC for tooling<\/p>\n","protected":false},"excerpt":{"rendered":"
\u2696\ufe0f Smart hopper & inventory-move throttling for Minecraft servers (1.21+). Keep TPS high without breaking vanilla mechanics \u2014 no NMS, no item loss.<\/p>\n","protected":false},"featured_media":81880,"template":"","meta":{"_minecraft_slug":"hopperflow-governor","_minecraft_project_id":"M4jbI1T5","_minecraft_author":"Nolly","_minecraft_license":"LicenseRef-Nollys-Fair-and-Ethical-Open-Source-License","_minecraft_downloads":180,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"hopperflow-governor.zip","_minecraft_size_bytes":1820063,"_minecraft_version_count":2,"_minecraft_updated_at":"2026-05-16T13:01:35.112083Z","_minecraft_date_created":"2025-09-04T01:06:10.234945Z","_minecraft_date_modified":"2025-09-01T11:49:13.385851Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/hopperflow-governor","_minecraft_icon_attachment_id":81880,"_minecraft_imported_at":"2026-06-04T16:54:24+00:00","_minecraft_import_hash":"376a513954444e605874ca58e934014e","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[124,89,126,90,127,128,129,91,92],"mod_loader":[130,132,133,134],"minecraft_version":[62,37,73,74,38,78,79,80,81],"class_list":["post-81879","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-bukkit","mod_category-game-mechanics","mod_category-management","mod_category-optimization","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-storage","mod_category-utility","mod_loader-bukkit","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8"],"yoast_head":"\n