# ✨ 管理员喜欢它的原因
- 每个系统一个智能漏斗 → 远比Tick方块少，服务器负载更低。
- 在同一世界中远程路由，具有优先级、过滤器、轮询/填满优先。
- 滞后感知批处理，跳过受阻/未加载的目标，可选的有限重试队列。
- 内置申领和信任（或链接您的区域插件）；管理绕过支持。
- 正常游戏无需命令 — 所有内容都通过清晰的游戏内 GUI 实现。
- 可选的电源系统（免费、红石或燃料箱 → 电源单位）。
- 演示：YouTube – 快速导览
---
# 📦 需求与兼容性
- **硬依赖:** [**Vault**](https://www.spigotmc.org/resources/vault.34315/) (用于经济；熔炉解锁和升级需要)。
- **软依赖:**
- [**DecentHolograms**](https://www.spigotmc.org/resources/decentholograms-1-8-1-21-8-papi-support-no-dependencies.96927/) — 节点上方悬浮的 HUD（活动/空闲、最后传输、电源）。
- [**LuckPerms**](https://luckperms.net/) — 基于动态、权限的限制。
- [**SuperiorSkyblock2**](https://www.spigotmc.org/resources/%E2%9A%A1%EF%B8%8F-superiorskyblock2-%E2%9A%A1%EF%B8%8F-the-best-core-on-market-%E2%9A%A1%EF%B8%8F-1-21-5-support.87411/) 或 [**BentoBox**](https://www.spigotmc.org/resources/bentobox-bskyblock-acidisland-skygrid-caveblock-aoneblock-boxed.73261/) — 每岛限制和信任互操作。
- **服务器:** Paper/Spigot 1.20+ (API 1.21 目标)。
- **区域:** 与 GriefPrevention/WorldGuard 兼容；如果不存在，则包含一个轻量级的内部申领系统。
---
# 🚀 它所做的事情（核心功能）
### 远程物品路由
将一个改进的漏斗链接到同一世界中的许多容器。配置：
- 每个目标的优先级（最高优先）
- 白名单/黑名单物品过滤器
- 分配：轮询或填满优先
### 全局游戏内 GUI
右键单击：管理链接、过滤器、电源、信任、统计信息、模拟路由、切换可视化。
### 聊天搜索过滤器
单击指南针，键入搜索；按下 Esc 或“取消”退出。
### 电源模式
- 无：免费操作
- 红石：`requireRedstonePower` 或 `pauseWhenPowered`
- 燃料：链接一个燃料箱；燃料物品根据距离和数量转换为电源单位
### 信任和申领
漏斗必须被申领；所有者可以 `/trust` 用户；管理员绕过。制作的节点自动申领。
### 滞后感知批处理
每Tick上限和明智的跳过空输入/受阻/未加载的目标。
### 可视化工具
到目标的粒子束；传输轨迹；过滤器聚焦可视化。
### 内置熔炉（可选）
使用 Vault 解锁和升级的虚拟熔炼。
### 可制作
改进漏斗和燃料箱的配方可配置。
---
# 🛠️ 安装
1. 将 JAR 放在 `/plugins` 中。
2. 确保安装了 Vault 并且已经激活了经济插件。
3. （可选）安装 DecentHolograms、LuckPerms 和你的 Skyblock 插件。
4. 启动服务器。如果需要，编辑 `/plugins/ImprovedHoppers/config.yml`。
5. `/improvedhoppers reload` 以应用更改。
---
# ⚡ 快速开始（玩家）
1. 制作一个改进的漏斗（如果使用燃料模式，则制作一个燃料箱）。
2. 放置和申领漏斗（制作的节点自动申领）。
3. 打开 GUI → 添加目标 → 单击容器以链接
提示：`/improvedhoppers wand` 用于快速多链接。
4. 设置过滤器、优先级和分配模式。
5. 选择电源模式。如果使用燃料，链接燃料箱并插入燃料。
6. （可选）根据红石设置添加红石。
---
# ⌨️ 命令
| 命令 | 描述 | 权限 |
|---------------------------------|------------------------------------------|-----------------------------------------------------------------|
| `/improvedhoppers` | 显示子命令 | (无) |
| `/improvedhoppers wand` | 获取链接魔杖进行多链接 | `improvedhoppers.user.wand` |
| `/improvedhoppers settings` | 打开设置 (节点或管理员视图) | `improvedhoppers.user.settings` / `improvedhoppers.admin.settings` |
| `/improvedhoppers remote` | 远程控制器 (随时查看/管理) | `improvedhoppers.user.remote` |
| `/improvedhoppers reload` | 重新加载配置 | `improvedhoppers.admin.reload` |
| `/improvedhoppers power apply` | 重新应用电源设置 | `improvedhoppers.admin` |
---
# 🔐 权限
## 用户
- `improvedhoppers.user.wand` (默认: true)
- `improvedhoppers.user.settings` (默认: true)
- `improvedhoppers.user.remote` (默认: true)
- `improvedhoppers.user.*` (默认: true)
## 管理员
- `improvedhoppers.admin` (默认: op) — 绕过管理
- `improvedhoppers.admin.reload` (默认: op)
- `improvedhoppers.admin.settings` (默认: op)
- `improvedhoppers.admin.*` (默认: op)
## 限制 (覆盖配置)
- `improvedhoppers.limit.player.`
- `improvedhoppers.limit.island.`
- `improvedhoppers.limit.links.`
- `improvedhoppers.limit.trusted.`
- `improvedhoppers.limit.filter.`
- `improvedhoppers.hopper.power.`
---
# 🧪 制作
**改进漏斗 — 形状配方（所有物品可配置）**
```
I C I
R H R
I C I
```
**燃料箱 — 可配置（例如，煤 + 箱子）**
参见 `recipes.yml` 获取确切材料、名称和 NBT 设置。
---
# ⚙️ 配置高亮 (示例)
```yaml
general:
storage: YAML # YAML | SQLITE
locale: en_US
holograms:
enabled: true
update_ticks: 20
particles:
enabled: true
transfer_trail: true
filter_focus: true
claims:
required: true
auto_claim_on_craft: true
admin_bypass: true
routing:
link:
max_distance: 256
owner_must_be_online: false
cleanup_interval_ticks: 200
distribution: ROUND_ROBIN # ROUND_ROBIN | FILL_FIRST
filters:
default_mode: WHITELIST # WHITELIST | BLACKLIST
per_hopper_max: 32
transfer:
interval_ticks: 10
per_tick_item_cap: 256
suction:
radius: 2.5
enabled: true
cost_per_item: 0
retry_queue:
enabled: true
max_entries: 2048
power:
mode: NONE # NONE | REDSTONE | FUEL
redstone:
require_power: false
pause_when_powered: true
fuel:
enabled: false # 设置为 true 以使用燃料
capacity: 10000
regen_per_tick: 0
distance_cost_per_block: 0.25
amount_cost_per_item: 0.05
auto_refuel: true
link_limit: 1
max_link_distance: 16
fuels:
COAL: 160
CHARCOAL: 160
BLAZE_ROD: 240
smelter:
enabled: true
base_cook_ticks: 200
queue_size: 128
unlock_cost: 1000 # Vault currency
upgrade_costs:
level_2: 2500
level_3: 5000
limits:
per_player: 20
per_island: 50
links_per_material: 4
trusted_slots: 8
storage:
sqlite:
file: data/ihoppers.db
```
> 注意：为了避免冲突，Vanilla `InventoryMoveItemEvent`/`InventoryPickupItemEvent` 会被取消用于申领的节点。
---
# 🧭 路由逻辑 (一览)
1. 从来源库存中提取高达 `per_tick_item_cap` 物品。
2. 过滤物品（白名单/黑名单）。
3. 按优先级对目标排序，移除未加载或受阻的目标。
4. **分配：**
- **轮询：** 每个物品类型循环目标。
- **填满优先：** 填充第一个有效目标，直到无法接受更多。
5. 电源核算（如果启用）：距离和数量 → PU 成本。
6. 如果启用重试队列，则在移动失败时应用重试队列。
---
# 📈 性能说明
- 使用批处理和每Tick上限，以保持 TPS 平稳。
- 跳过空来源和受阻/未加载的目标以节省时间。
- 可选的距离缩放电源可阻止极端跨地图链接。
- 可视化器按玩家设置；过滤器聚焦轨迹减少粒子垃圾。
---
# 🧩 兼容性与链接
- 链接: Vault, LuckPerms, DecentHolograms, SuperiorSkyblock2, BentoBox, GriefPrevention, WorldGuard。
- 如果未检测到，则包含内部申领。
---
# 🧰 管理员工具
查看一个节点并运行 `/improvedhoppers settings`（管理员视图）以实时微调：链接距离、吸入/传输上限、燃料值、熔炉费率、限制、粒子/全息图、世界允许列表、配方和更多。
---
# 🧑💻 API 和事件 (供开发者使用)
**事件 (示例)**
- `HopperSorterTransferEvent` — 每次成功转移
- `HopperSorterFuelConsumeEvent` — 在燃料 → 电源转换时
- `HopperSorterClaimEvent` — 当所有权/申领发生变化时
- 溢出和警报链接
**示例监听器**
```java
@EventHandler(ignoreCancelled = true, priority = EventPriority.MONITOR)
public void onTransfer(HopperSorterTransferEvent e) {
Player owner = e.getOwner();
ItemStack stack = e.getItem();
Location from = e.getSource();
Location to = e.getTarget();
int moved = e.getAmount();
// e.getCostPU() 如果使用燃料模式；e.isSimulated() 用于干运行
if (owner != null && owner.isOnline()) {
owner.sendActionBar(Component.text("§aMoved " + moved + "x " + stack.getType() + " → " + pretty(to)));
}
}
```
可以为燃料提供商和虚拟目标提供最小的 API 草图。
---
# 💾 存储与持久性
- YAML 或 SQLite。
- 持久化节点电源、名称、粒子颜色、链接、熔炉状态安全。
---
# ❓ 常见问题解答
**Q：我可以禁用电源系统吗？**
A：可以。默认情况下已禁用；将 `power.fuel.enabled: true` 设置为使用燃料。
**Q：玩家可以远程管理漏斗吗？**
A：是的。 `/improvedhoppers remote` 打开网络概述或节点 GUI。
**Q：申领节点上是否仍然发生 Vanilla 漏斗提取？**
A：不。我们取消了申领节点的移动/提取事件，以避免冲突。
---
# 🧪 故障排除
- 没有发生传输 → 检查申领/所有权和电源模式。
- 缺少全息图 → 安装/启用 DecentHolograms 并确保 `holograms.enabled: true`。
- Skyblock 限制被忽略 → 确保存在 SSB2/BentoBox；如果使用权限覆盖，请确认 LuckPerms dyn-limits。
- 距离成本过高 → 降低 `power.fuel.distance_cost_per_block` 或增加容量。
---
# 🧭 路由逻辑 (一览)
1. 从来源库存中提取高达 `per_tick_item_cap` 物品。
2. 过滤物品（白名单/黑名单）。
3. 按优先级对目标排序，移除未加载或受阻的目标。
4. **分配：**
- **轮询：** 每个物品类型循环目标。
- **填满优先：** 填充第一个有效目标，直到无法接受更多。
5. 电源核算（如果启用）：距离和数量 → PU 成本。
6. 如果启用重试队列，则在移动失败时应用重试队列。
---
# 📈 性能说明
- 使用批处理和每Tick上限，以保持 TPS 平稳。
- 跳过空来源和受阻/未加载的目标以节省时间。
- 可选的距离缩放电源可阻止极端跨地图链接。
- 可视化器按玩家设置；过滤器聚焦轨迹减少粒子垃圾。
---
# 🧩 兼容性与链接
- 链接: Vault, LuckPerms, DecentHolograms, SuperiorSkyblock2, BentoBox, GriefPrevention, WorldGuard。
- 如果未检测到，则包含内部申领。
---
# 🧰 管理员工具
查看一个节点并运行 `/improvedhoppers settings`（管理员视图）以实时微调：链接距离、吸入/传输上限、燃料值、熔炉费率、限制、粒子/全息图、世界允许列表、配方和更多。
---
# 🧑💻 API 和事件 (供开发者使用)
**事件 (示例)**
- `HopperSorterTransferEvent` — 每次成功转移
- `HopperSorterFuelConsumeEvent` — 在燃料 → 电源转换时
- `HopperSorterClaimEvent` — 当所有权/申领发生变化时
- 溢出和警报链接
**示例监听器**
```java
@EventHandler(ignoreCancelled = true, priority = EventPriority.MONITOR)
public void onTransfer(HopperSorterTransferEvent e) {
Player owner = e.getOwner();
ItemStack stack = e.getItem();
Location from = e.getSource();
Location to = e.getTarget();
int moved = e.getAmount();
// e.getCostPU() 如果使用燃料模式；e.isSimulated() 用于干运行
if (owner != null && owner.isOnline()) {
owner.sendActionBar(Component.text("§aMoved " + moved + "x " + stack.getType() + " → " + pretty(to)));
}
}
```
可以为燃料提供商和虚拟目标提供最小的 API 草图。
---
# 💾 存储与持久性
- YAML 或 SQLite。
- 持久化节点电源、名称、粒子颜色、链接、熔炉状态安全。
---
# ❓ 常见问题解答
**Q：我可以禁用电源系统吗？**
A：可以。默认情况下已禁用；将 `power.fuel.enabled: true` 设置为使用燃料。
**Q：玩家可以远程管理漏斗吗？**
A：是的。 `/improvedhoppers remote` 打开网络概述或节点 GUI。
**Q：申领节点上是否仍然发生 Vanilla 漏斗提取？**
A：不。我们取消了申领节点的移动/提取事件，以避免冲突。
---
# 🧪 故障排除
- 没有发生传输 → 检查申领/所有权和电源模式。
- 缺少全息图 → 安装/启用 DecentHolograms 并确保 `holograms.enabled: true`。
- Skyblock 限制被忽略 → 确保存在 SSB2/BentoBox；如果使用权限覆盖，请确认 LuckPerms dyn-limits。
- 距离成本过高 → 降低 `power.fuel.distance_cost_per_block` 或增加容量。