Zzclear 扫地大妈 - Minecraft 实体清理模组

中文版 | English Version (英文版)

Zzclear 是一款轻量级、智能化的 Minecraft Fabric 实体清理（扫地）模组。 它不仅能在后台静默运行并根据设定频率自动清理地图上的掉落物和冗余实体，还提供了强大的游戏内指令系统与支持热更新的精细化配置文件，帮助服主从源头上根治服务器卡顿问题！

---

✨ 核心特性

• 🕐 自动化定时清理： 自定义清理周期（支持按照分钟级别配置清扫时间），时间一到自动剿灭滞留的实体。
• 🛡️ 智能过滤与白名单： 告别"一刀切"！无论是掉落物、怪物、还是特定的实体，支持在配置文件中通过"黑名单/白名单"进行精准放行或彻底根除。
• 🐴 骑乘保护： 玩家正在骑乘的实体（马、船、矿车等）不会被误清。
• ⏱️ 掉落物保护期： 刚掉落的物品可设置免疫时间，防止新掉落的物品被立刻清理。
• 🌍 维度过滤： 支持按维度排除，指定维度（如末地）不参与清理。
• 📊 清理阈值： 当待清理实体数量低于阈值时跳过清理，避免无意义的空跑。
• 🌐 中英文配置： 配置文件注释支持中英文，通过 language 字段切换，/zzclear reload 即时生效。
• 🪓 全类型实体管控：
  • 常规清理： 掉落物 (Item)、经验球 (Experience Orb)
  • 生物清理： 敌对怪物 (Monsters)、中性/友好动物 (Animals)
  • 载具/装饰物管控： 船 (Boats)、画 (Paintings)、物品展示框 (Item Frames)
  • 物理/投掷物管控： 射出的箭矢、三叉戟、掉落的方块 (Falling Blocks)、点燃的 TNT、潜影弹、烟花火箭等。
• 🔄 热重载指令： 调整配置文件后无需重启服务器，一条指令直接生效。

---

⌨️ 游戏内指令用法

以下所有指令的主命令为 /zzclear：

1. 配置文件重载（管理员）

/zzclear reload

• 作用： 重新读取 config/config.json 文件并立即应用新的清理规则和白名单数据，同时刷新配置文件注释语言。

2. 查看清理倒计时（所有玩家）

/zzclear status

• 作用： 查看距离下一次自动清理还有多少分钟和秒数。

3. 手动清理指令（管理员）

如果你不想等后台计时器，可以使用这些指令立刻清理对应的实体类别：

• /zzclear items —— 强制立即清理所有掉落物。
• /zzclear monsters —— 强制立即清除所有敌对/中立怪物。
• /zzclear animals —— 强制立即清除所有动物。
• /zzclear xps —— 强制立即清除悬浮的经验球。
• /zzclear others —— 强制立即清除杂项（如画、船、掉落的方块、飞行中的箭矢等）。

4. 掉落物白名单管理（管理员）

当你手里拿着某件物品时，可以直接使用该系列指令将其加入或移出清理过滤名单：

• /zzclear white item add —— 将当前手持的主武器/物品加入全局白名单。
• /zzclear white item del —— 将当前手持的物品从白名单中彻底移除。

5. 指定实体 ID 名单管理（管理员）

如果你希望精准地保护或排除某种特定的生物或实体 (如 minecraft:zombie)，可以使用该系列指令：

• /zzclear white entity add <实体ID> —— 添加指定实体 ID 进入白名单。
• /zzclear white entity del <实体ID> —— 从白名单中移除指定的实体 ID。

  注：指令支持游戏内 ID 自动补全 (Tab suggestions)。

---

🔑 权限节点

无 LuckPerms 时默认按 OP 等级判断（管理员指令需要 OP 4）。安装 LuckPerms 后可使用以下权限节点精细控制：

权限节点	说明	默认
zzclear.command.admin	reload、白名单管理	仅 OP
zzclear.command.items	手动清理掉落物	仅 OP
zzclear.command.monsters	手动清理怪物	仅 OP
zzclear.command.animals	手动清理动物	仅 OP
zzclear.command.xps	手动清理经验球	仅 OP
zzclear.command.others	手动清理其他实体	仅 OP
zzclear.command.status	查看清理倒计时	所有玩家

---

⚙️ 配置文件说明

运行一次游戏后，模组会自动生成配置文件，路径为：

<游戏根目录>/Zzclear/config/config.json

配置文件自带中英文注释（由 language 字段控制）。

通用设置 (common)

配置项	默认值	说明
language	"zh"	配置文件注释语言，zh=中文，en=英文，reload 后生效
sweepIntervalMinutes	4	清理间隔（分钟）
warningTimeSeconds	20	清理前提前多少秒发出预警
finalCountdownSeconds	5	最后读秒阶段的秒数
countdownMessage	中文提示	倒计时警告消息模板，支持 {0} 占位符
sweepCompleteMessage	中文提示	清理完成通报模板，支持 {0}~{3} 占位符
statusMessage	中文提示	/zzclear status 显示的消息模板
ignoreNamedEntities	true	有自定义名称的实体不清理
ignoreRiddenEntities	true	玩家正在骑乘的实体不清理
newItemImmunitySeconds	0	掉落物保护秒数（刚掉落 N 秒内不清理），0=关闭
minEntityCountToSweep	0	至少有多少实体才执行清理，0=不限制
dimensionBlacklist	[]	不参与清理的维度列表，如 ["minecraft:the_end"]

掉落物设置 (item)

配置项	默认值	说明
sweepItems	true	是否清理掉落物
useItemWhitelist	false	白名单模式（白名单中的物品不清理）
useItemBlacklist	false	黑名单模式（只清理黑名单中的物品）
itemWhitelist	[]	掉落物白名单列表
itemBlacklist	["minecraft:diamond"]	掉落物黑名单列表

生物设置 (mob)

配置项	默认值	说明
sweepLivingEntities	true	是否开启生物清理
dropExp	false	清理生物时是否掉落经验
sweepPassiveAnimals	false	是否清理动物（非怪物）
sweepHostileMonsters	true	是否清理怪物
useMobWhitelist	true	生物白名单模式
useMobBlacklist	false	生物黑名单模式
mobWhitelist	村民、铁傀儡等	生物白名单列表
mobBlacklist	村民、铁傀儡	生物黑名单列表

其他实体设置 (other)

配置项	默认值	说明
sweepExperienceOrbs	false	清理经验球
sweepFallingBlocks	false	清理下落方块（如沙子）
sweepArrows	false	清理箭
sweepTridents	false	清理三叉戟
sweepProjectiles	false	清理投射物
sweepShulkerBullets	false	清理潜影弹
sweepFireworks	false	清理烟花
sweepItemFrames	false	清理展示框
sweepPaintings	false	清理画
sweepBoats	false	清理船
sweepPrimedTNT	false	清理点燃的 TNT

提示： 修改好 json 数据之后，回到游戏里敲一下 /zzclear reload 瞬间搞定，绝不拖泥带水！