HopperFlow Governor
> ⚖️ 为 Minecraft 服务器 (1.21+) 提供智能漏斗和物品移动限速。
> 在不破坏原版机制的情况下保持高 TPS — 无需 NMS，无物品损失。
[](https://github.com/nolly-mc/HopperFlowGovernor/actions)
[](LICENSE)
[](https://bstats.org/plugin/bukkit/HopperFlowGovernor)
---
## ✨ 功能
- 🛡️ **保护 TPS** — 只限速每个刻特中 *额外* 的漏斗/投掷器/发射器/漏斗矿车的移动次数。
- ⚙️ **完全可配置** — 每个区块、每个类型和全局限速带有脉冲令牌。
- 📊 **实时诊断** — `/hopperflow inspect`, `/detail`, `/where`, `/top`。
- 🚫 **无 NMS 技巧** — 纯 Spigot API; 在版本之间具有前向兼容性。
- 🎮 **玩家友好** — 无物品损失，附近限速发生时可选的操作栏通知。
- 🗺️ **世界保卫战整合** — 轻松排除特定区域。
- 🧩 **排除** — 按世界、区域或容器名称前缀（例如 `[FAST]` 漏斗）排除。
- 📈 **可选指标** — bStats（可选）用于希望获取使用统计信息的服务器所有者。
- 🔒 **最低开销** — 针对拥有数千个漏斗的大型服务器进行了优化。
---
---
## 📥 安装
1. 从 [SpigotMC](https://www.spigotmc.org/resources/hopperflow-governor.128524/) / `Modrinth` 下载最新版本。
2. 将 `HopperFlowGovernor-x.x.x.jar` 放入服务器的 `plugins/` 文件夹中。
3. 重启服务器。 将创建一个默认的 `config.yml`。
---
## ⚙️ 配置
默认的 `config.yml` 上面有很多注释：
```yml
# HopperFlow Governor — 限制物品移动事件以稳定 TPS。
# 纯 Bukkit。 无物品损失。 仅取消刻特窗口中多余的移动。
# 全局每个区块默认值（当不存在每类型覆盖时使用）
rate_per_chunk_per_sec: 80 # 每个区块的默认平均移动次数/秒
burst_per_chunk: 120 # 每个区块的默认短期脉冲令牌数
# 全局所有区块的上限
max_global_rate: 5000 # 允许的全局平均移动次数/秒
# 可选的每类型覆盖；省略或设置 null 以使用上面的全局默认值
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 }
# 根据哪些发起者进行管理？
include:
hopper_blocks: true # 原版区块漏斗
hopper_minecarts: false # 漏斗矿车实体
droppers: false # 向物品栏推送的投掷器
dispensers: false # 向物品栏推送的发射器
# 按类型排除名称前缀（重命名容器/矿车会绕过限速）
exempt_name_prefixes:
hopper_block: "[FAST]"
hopper_minecart: ""
dropper: ""
dispenser: ""
# 世界和世界保卫战排除
exempt_worlds: [ the_end ]
exempt_regions: [ ] # WG 区域 ID (如果安装了世界保卫战)
# 玩家反馈
notify_players_near_throttle: true
notify_radius: 16
# 会计窗口 + 清理
stats_window_seconds: 60 # /inspect、/detail、/where、/top 使用的时间窗口
cleanup_after_minutes: 15 # 删除空闲区块统计数据/桶
# 遥测 (bStats) — 可选。
metrics:
enabled: true
```
---
## 🖥️ 命令 & 权限
| 命令 | 权限 | 默认 | 描述 |
|-------------------------|------------------------------|---------|-------------------------------------------------|
| `/hopperflow help` | `hopperflow.command.help` | OP | 显示帮助消息 |
| `/hopperflow reload` | `hopperflow.command.reload` | OP | 重新加载 config.yml |
| `/hopperflow inspect` | `hopperflow.command.inspect` | OP | 显示当前区块的摘要 |
| `/hopperflow detail` | `hopperflow.command.detail` | OP | 各发起者（漏斗、投掷器等）的细分 |
| `/hopperflow where [N]` | `hopperflow.command.where` | OP | 列出此区块中限速的前 N 个位置 |
| `/hopperflow top [N]` | `hopperflow.command.top` | OP | 在最后 60 秒内对区块进行全局排名 |
**别名:** `/hflow`, `/hfg`
---
## 🔍 用法示例
* 将漏斗重命名为 `[FAST]` → **它会绕过限制**（自定义分类器、农场）。
* `/hopperflow top 5` → 列出过去 60 秒内受影响最严重的 5 个区块。
* `/hopperflow where 10` → 找到正在限速的 **确切区块坐标**。
* 将漏斗放置在世界保卫战区域内 → 如果区域 ID 列出，则自动排除。
---
## 📈 指标
* 包含 [bStats](https://bstats.org/) 整合，但 **默认禁用** (`metrics.enabled: false`)。
* 如果启用，插件会匿名报告：
* HopperFlowGovernor 版本
* Minecraft 版本
* 服务器计数
* 不收集任何个人或身份识别信息。
* 使用指标是为了帮助根据使用模式来确定未来开发的优先级。
---
## 🔧 性能说明
* 此插件 **不会** 删除或作废物品。
* 它只会取消超过配置阈值范围内的 *额外* `InventoryMoveItemEvent` 调用。
* 与 ClearLag、WorldGuard 和 Paper 的异步区块系统等插件安全地协同工作。
---
## 📚 API / 兼容性
* 纯 **Bukkit/Spigot API** — 无 Paper 专用挂钩，无 NMS。
* 与 Paper、Spigot、Purpur 兼容（在 1.21+ 上测试过）。
* 世界保卫战整合是可选的（软依赖）。
---
## 🤝 贡献
1. 分叉此仓库 & 克隆到本地。
2. 运行 `mvn package` 以构建。
3. 在本地 Paper 服务器上进行测试 (`/plugins/`)。
4. 提交具有清晰提交历史记录的拉取请求。
Bug 报告和功能请求 → [GitHub Issues](https://github.com/nolly-mc/HopperFlowGovernor/issues)。
---
## 📜 许可证
本项目的许可证为 [NFE-OSL 许可证](https://github.com/Nolly-MC/HopperFlowGovernor/blob/main/LICENSE)。
---
## ❤️ 鸣谢
* 由 **Nolly** ([@TheNolle](https://github.com/thenolle)) 开发
* 灵感来自社区对漏斗滞后的反馈
* 感谢 [bStats](https://bstats.org/) 和 [SpigotMC](https://spigotmc.org/) 提供的工具