Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

176 Commits

Folders and files

Repository files navigation

UltiCleaner

高性能 Minecraft 服务器清理插件 - 自动清理地面物品和实体,支持智能清理、TPS 自适应和分批处理。

UltiTools-API

✨ 功能特性

🧹 基础清理功能

  • 物品清理 - 定时清理地面掉落物,支持白名单和新掉落物保护
  • 实体清理 - 定时清理指定类型的生物,保护命名/拴绳/驯服实体

🧠 智能清理系统

  • 阈值触发 - 当实体数量超过配置阈值时自动触发清理
  • 冷却控制 - 防止短时间内重复触发智能清理
  • TPS 自适应 - 根据服务器 TPS 动态调整清理阈值
    • TPS < 18: 阈值降低 30%
    • TPS < 15: 阈值降低 50%

⚡ 性能优化

  • 分批处理 - 清理操作分批执行,每 tick 处理固定数量,避免卡顿
  • 异步事件 - 清理完成事件异步触发,不阻塞主线程
  • Paper 兼容 - 自动检测 Paper 服务器,使用优化 API

🔌 扩展性

  • 自定义事件 - 提供 PreItemCleanEvent、PreEntityCleanEvent 和 CleanCompleteEvent
  • 可取消清理 - 其他插件可监听事件并取消特定清理操作
  • 统计回调 - 清理完成后触发事件,包含清理数量和耗时

📦 安装

  1. 确保已安装 UltiTools-API 6.3.0 或更高版本。本模块声明 api-version: 630, 更早的框架会拒绝加载它
  2. 下载最新版本的 UltiCleaner
  3. 将 JAR 文件放入 plugins/UltiTools/plugins/ 目录
  4. 重启服务器(/ul reload 只重载配置,不会加载新的模块 JAR)
  5. 编辑 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

🔧 开发者 API

监听清理事件

@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.CleanType has three constants: ITEMS, ENTITIES and ALL. ALL is fired once per /clean all, after both halves have finished (each half first fires its own ITEMS or ENTITIES event), with the combined count. The former CHUNKS constant 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 优化 ✅ ❌
物品白名单 ✅ ❌
忽略新掉落物 ✅ ❌
忽略拴绳实体 ✅ ❌
实体清理警告 ✅ ❌

📊 性能建议

小型服务器 (< 20 玩家)

item:
  interval: 600        # 10分钟清理一次
smart:
  enabled: false       # 关闭智能清理

中型服务器 (20-100 玩家)

item:
  interval: 300        # 5分钟清理一次
smart:
  enabled: true
  item-threshold: 1500
  mob-threshold: 800
batch:
  size: 100            # 增加批量大小

大型服务器 (100+ 玩家)

item:
  interval: 180        # 3分钟清理一次
smart:
  enabled: true
  item-threshold: 1000  # 降低阈值
  mob-threshold: 500
tps:
  adaptive-enabled: true
  low-threshold: 19.0   # 更敏感的TPS检测

Known limitations / 已知限制

  • 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 entities or clean all from the direct server console when you need the completion line, or check the remaining counts with clean check afterward.
  • 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 entities or /clean all directly 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 开源。

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages