高性能 Minecraft 服务器清理插件 - 自动清理地面物品和实体,支持智能清理、TPS 自适应和分批处理。
- 物品清理 - 定时清理地面掉落物,支持白名单和新掉落物保护
- 实体清理 - 定时清理指定类型的生物,保护命名/拴绳/驯服实体
- 阈值触发 - 当实体数量超过配置阈值时自动触发清理
- 冷却控制 - 防止短时间内重复触发智能清理
- TPS 自适应 - 根据服务器 TPS 动态调整清理阈值
- TPS < 18: 阈值降低 30%
- TPS < 15: 阈值降低 50%
- 分批处理 - 清理操作分批执行,每 tick 处理固定数量,避免卡顿
- 异步事件 - 清理完成事件异步触发,不阻塞主线程
- Paper 兼容 - 自动检测 Paper 服务器,使用优化 API
- 自定义事件 - 提供
PreItemCleanEvent、PreEntityCleanEvent和CleanCompleteEvent - 可取消清理 - 其他插件可监听事件并取消特定清理操作
- 统计回调 - 清理完成后触发事件,包含清理数量和耗时
- 确保已安装 UltiTools-API 6.3.0 或更高版本。本模块声明
api-version: 630, 更早的框架会拒绝加载它 - 下载最新版本的 UltiCleaner
- 将 JAR 文件放入
plugins/UltiTools/plugins/目录 - 重启服务器(
/ul reload只重载配置,不会加载新的模块 JAR) - 编辑
plugins/UltiTools/pluginConfig/UltiCleaner/config/cleaner.yml配置
| 命令 | 权限 | 描述 |
|---|---|---|
/clean items |
ulticleaner.clean |
立即清理地面物品 |
/clean entities |
ulticleaner.clean |
立即清理实体 |
/clean all |
ulticleaner.clean |
清理所有物品和实体 |
/clean check |
ulticleaner.clean |
查看服务器实体统计 |
/clean status |
ulticleaner.clean |
查看清理状态和倒计时 |
# ============ 物品清理 ============
item:
enabled: true # 启用物品清理
interval: 300 # 清理间隔(秒)
warn-times: [60, 30, 10, 5, 3, 2, 1] # 警告时间点
whitelist: # 物品白名单
- DIAMOND
- EMERALD
- NETHER_STAR
ignore-named: true # 忽略有自定义名称的物品
ignore-recent: 30 # 忽略刚掉落的物品(秒)
# ============ 实体清理 ============
entity:
enabled: true # 启用实体清理
interval: 600 # 清理间隔(秒)
warn-times: [60, 30, 10, 5, 3, 2, 1]
types: # 要清理的实体类型
- ZOMBIE
- SKELETON
- CREEPER
whitelist-named: true # 不清理有名称的实体
whitelist-leashed: true # 不清理被拴住的实体
whitelist-tamed: true # 不清理被驯服的实体
# ============ 智能清理 ============
smart:
enabled: false # 启用智能清理
item-threshold: 2000 # 物品数量阈值
mob-threshold: 1000 # 生物数量阈值
cooldown: 60 # 冷却时间(秒)
# ============ 分批处理 ============
batch:
size: 50 # 每tick清理数量
show-progress: false # 显示清理进度
# ============ TPS 自适应 ============
tps:
adaptive-enabled: true # 启用TPS自适应
sample-window: "1m" # 采样窗口(1m/5m/15m)
low-threshold: 18.0 # 低TPS阈值
critical-threshold: 15.0 # 严重低TPS阈值
low-reduction: 30 # 低TPS阈值降低百分比
critical-reduction: 50 # 严重低TPS阈值降低百分比
# ============ 世界设置 ============
worlds:
blacklist: # 不进行清理的世界
- world_creative@EventListener
public class CleanerListener implements Listener {
@EventHandler
public void onPreItemClean(PreItemCleanEvent event) {
// 取消特定世界的清理
if (event.getWorld() != null &&
event.getWorld().getName().equals("protected_world")) {
event.setCancelled(true);
return;
}
// 从清理列表中移除特定物品
event.getItemUuids().removeIf(uuid -> {
Entity entity = Bukkit.getEntity(uuid);
return entity != null && isProtectedItem(entity);
});
}
@EventHandler
public void onCleanComplete(CleanCompleteEvent event) {
// 记录清理统计
log.info("Cleaned {} {} in {}",
event.getCleanedCount(),
event.getCleanType(),
event.getFormattedDuration());
}
}| 事件 | 触发时机 | 可取消 |
|---|---|---|
PreItemCleanEvent |
物品清理前 | ✅ |
PreEntityCleanEvent |
实体清理前 | ✅ |
CleanCompleteEvent |
清理完成后 | ❌ |
Note
CleanCompleteEvent.CleanTypehas three constants:ITEMS,ENTITIESandALL.ALLis fired once per/clean all, after both halves have finished (each half first fires its ownITEMSorENTITIESevent), with the combined count. The formerCHUNKSconstant was removed with the chunk-unload feature (UltiKits/UltiCleaner#16,UltiKits/UltiCleaner#27).注意
CleanCompleteEvent.CleanType共三个常量:ITEMS、ENTITIES、ALL。ALL在每次/clean all的两半都完成后触发一次(两半各自先触发自己的ITEMS或ENTITIES事件),计数为两者之和。原来的CHUNKS常量已随区块卸载功能一并删除(UltiKits/UltiCleaner#16、UltiKits/UltiCleaner#27)。
| 功能 | UltiCleaner 模块 | 旧版 UltiTools |
|---|---|---|
| 物品清理 | ✅ | ✅ |
| 实体清理 | ✅ | ✅ |
| 智能清理 | ✅ | ✅ |
| 分批处理 | ✅ | ❌ |
| TPS 自适应 | ✅ | ❌ |
| 自定义事件 | ✅ | ❌ |
| Paper 优化 | ✅ | ❌ |
| 物品白名单 | ✅ | ❌ |
| 忽略新掉落物 | ✅ | ❌ |
| 忽略拴绳实体 | ✅ | ❌ |
| 实体清理警告 | ✅ | ❌ |
item:
interval: 600 # 10分钟清理一次
smart:
enabled: false # 关闭智能清理item:
interval: 300 # 5分钟清理一次
smart:
enabled: true
item-threshold: 1500
mob-threshold: 800
batch:
size: 100 # 增加批量大小item:
interval: 180 # 3分钟清理一次
smart:
enabled: true
item-threshold: 1000 # 降低阈值
mob-threshold: 500
tps:
adaptive-enabled: true
low-threshold: 19.0 # 更敏感的TPS检测- RCON replies: when an RCON command starts a batched cleanup with eligible targets, the client receives
only the "Started cleaning …" line. Removal finishes on later ticks, after the RCON reply has already been
collected, so its completion message is not included in that reply. Do not use the RCON reply as proof of
completion: run
clean items,clean entitiesorclean allfrom the direct server console when you need the completion line, or check the remaining counts withclean checkafterward. - RCON 回复: RCON 命令对符合条件的目标启动分批清理时,客户端只收到「已开始清理……」。实际移除发生在后续 tick,
此时 RCON 回复已收集完毕,因此完成消息不会包含在该回复里。不要把 RCON 回复当作清理完成的证据;需要完成消息时,
请在服务器直接控制台执行
clean items、clean entities或clean all,或稍后用clean check查看剩余数量。 - Commands proxied through
/execute: a player running/execute as <entity> run clean …can receive a completion message twice: once from the online-player broadcast and once through the proxied command sender. This duplicates the message, not the cleanup. Run/clean items,/clean entitiesor/clean alldirectly as the player, or run the command from the direct server console instead. - 通过
/execute转发的命令: 玩家执行/execute as <实体> run clean …时,可能收到两次完成消息:一次来自在线玩家广播, 另一次来自转发命令的发送者。重复的是消息,不是清理。请让玩家直接执行/clean items、/clean entities或/clean all, 或改用服务器直接控制台执行。
如遇到问题,请在 GitHub Issues 提交,并附上:
- 服务器版本 (Paper)
- UltiTools 版本
- 完整的错误日志
- 配置文件内容
本项目基于 MIT License 开源。