[MD]
## 简介
ZzaiClear 是一款面向 Minecraft Fabric 服务端的轻量级高智能实体清除与性能优化模组。它在后台静默运行，依据可自由配置的定时周期，自动清理掉落物、废弃实体及导致卡顿的对象，并提供完善的游戏内命令系统与热重载配置机制，从根源上消除实体堆积带来的服务器卡顿。
# ZzaiClear
**ZzaiClear** 是一款面向 Minecraft Fabric 服务端的轻量级高智能实体清除与性能优化模组。它在后台静默运行，依据可自由配置的定时周期，自动清理掉落物、废弃实体及导致卡顿的对象，并提供完善的游戏内命令系统与热重载配置机制，从根源上消除实体堆积带来的服务器卡顿。
---
## 核心功能
- **定时自动清理：** 自定义清扫周期（精确到分钟），计时结束时自动清除滞留实体。
- **智能白名单与过滤：** 无论是掉落物、特定怪物还是单独的实体类型，均支持通过黑名单/白名单数组进行精确排除或定向清理。
- **骑乘保护：** 正在被玩家骑乘的实体（马、船、矿车等）自动豁免，不会被清除。
- **掉落物保护期：** 新掉落的物品可设置宽限时间，避免刚落地即被清扫。
- **维度过滤：** 支持将特定维度（如末地）完全排除在清扫范围之外。
- **清扫阈值：** 当目标实体数量低于可配置的最小值时跳过本轮清扫，避免空跑。
- **双语配置注释：** 配置文件注释支持中英文切换，由 `language` 字段控制，重载后（`/zzclear reload`）生效。
- **全类型实体管理：**
- 掉落物清理：掉落物品、经验球
- 生物清理：敌对/中立怪物、被动动物
- 载具与装饰：船、画、物品展示框
- 物理与抛射物：已射出的箭、三叉戟、下落方块、已点燃的 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 <Entity ID>` — 将指定实体注册 ID 加入白名单。
- `/zzclear white entity del <Entity ID>` — 将指定实体注册 ID 从白名单移除。
> 以上命令均支持游戏内 Tab 键自动补全。
---
## 权限节点
未安装 LuckPerms 时，管理员命令需要 OP 等级 4。安装 LuckPerms 后，可使用以下权限节点进行精细化授权：
| 权限节点 | 说明 | 默认 |
| :--- | :--- | :--- |
| `zzclear.command.admin` | 重载配置、白名单管理 | 仅 OP |
| `zzclear.command.items` | 手动清除掉落物 | 仅 OP |
| `zzclear.command.monsters` | 手动清除怪物 | 仅 OP |
| `zzclear.command.animals` | 手动清除动物 | 仅 OP |
| `zzclear.command.xps` | 手动清除经验球 | 仅 OP |
| `zzclear.command.others` | 手动清除其他实体 | 仅 OP |
| `zzclear.command.status` | 查看清扫倒计时 | 所有玩家 |
---
## 配置说明
首次启动游戏后，模组会自动在以下路径生成配置文件：
```
<game root>/Zzclear/config/config.json
```
配置文件注释语言由 `language` 字段控制，支持中文与英文切换。
### 通用设置
| 参数 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `language` | `"zh"` | 配置注释语言，`zh` = 中文，`en` = 英文，重载后生效 |
| `sweepIntervalMinutes` | `4` | 清扫间隔（分钟） |
| `warningTimeSeconds` | `20` | 清扫前预警时间（秒） |
| `finalCountdownSeconds` | `5` | 最终倒计时时长（秒） |
| `countdownMessage` | 中文文本 | 倒计时预警消息模板，支持 `{0}` 占位符 |
| `sweepCompleteMessage` | 中文文本 | 清扫完成汇报模板，支持 `{0}`～`{3}` 占位符 |
| `statusMessage` | 中文文本 | `/zzclear status` 消息模板 |
| `ignoreNamedEntities` | `true` | 忽略拥有自定义名称的实体 |
| `ignoreRiddenEntities` | `true` | 保护正在被玩家骑乘的实体 |
| `newItemImmunitySeconds` | `0` | 物品掉落后的保护期（秒），`0` = 禁用 |
| `minEntityCountToSweep` | `0` | 触发清扫所需的最低实体数量，`0` = 不限制 |
| `dimensionBlacklist` | `[]` | 排除在清扫范围外的维度，例如 `["minecraft:the_end"]` |
### 物品设置
| 参数 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `sweepItems` | `true` | 启用掉落物品清除 |
| `useItemWhitelist` | `false` | 白名单模式（保护列表内物品） |
| `useItemBlacklist` | `false` | 黑名单模式（仅清除列表内物品） |
| `itemWhitelist` | `[]` | 物品白名单 |
| `itemBlacklist` | `["minecraft:diamond"]` | 物品黑名单 |
### 生物设置
| 参数 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `sweepLivingEntities` | `true` | 启用生物实体清除 |
| `dropExp` | `false` | 击杀生物时掉落经验 |
| `sweepPassiveAnimals` | `false` | 清除被动动物 |
| `sweepHostileMonsters` | `true` | 清除敌对怪物 |
| `useMobWhitelist` | `true` | 启用生物白名单模式 |
| `useMobBlacklist` | `false` | 启用生物黑名单模式 |
| `mobWhitelist` | 村民、铁傀儡等 | 生物白名单 |
| `mobBlacklist` | 村民、铁傀儡 | 生物黑名单 |
### 其他实体设置
| 参数 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `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` 即可立即生效，无需重启服务端。
---
## 截图
[/MD]
## 简介
ZzaiClear 是一款面向 Minecraft Fabric 服务端的轻量级高智能实体清除与性能优化模组。它在后台静默运行，依据可自由配置的定时周期，自动清理掉落物、废弃实体及导致卡顿的对象，并提供完善的游戏内命令系统与热重载配置机制，从根源上消除实体堆积带来的服务器卡顿。
# ZzaiClear
**ZzaiClear** 是一款面向 Minecraft Fabric 服务端的轻量级高智能实体清除与性能优化模组。它在后台静默运行，依据可自由配置的定时周期，自动清理掉落物、废弃实体及导致卡顿的对象，并提供完善的游戏内命令系统与热重载配置机制，从根源上消除实体堆积带来的服务器卡顿。
---
## 核心功能
- **定时自动清理：** 自定义清扫周期（精确到分钟），计时结束时自动清除滞留实体。
- **智能白名单与过滤：** 无论是掉落物、特定怪物还是单独的实体类型，均支持通过黑名单/白名单数组进行精确排除或定向清理。
- **骑乘保护：** 正在被玩家骑乘的实体（马、船、矿车等）自动豁免，不会被清除。
- **掉落物保护期：** 新掉落的物品可设置宽限时间，避免刚落地即被清扫。
- **维度过滤：** 支持将特定维度（如末地）完全排除在清扫范围之外。
- **清扫阈值：** 当目标实体数量低于可配置的最小值时跳过本轮清扫，避免空跑。
- **双语配置注释：** 配置文件注释支持中英文切换，由 `language` 字段控制，重载后（`/zzclear reload`）生效。
- **全类型实体管理：**
- 掉落物清理：掉落物品、经验球
- 生物清理：敌对/中立怪物、被动动物
- 载具与装饰：船、画、物品展示框
- 物理与抛射物：已射出的箭、三叉戟、下落方块、已点燃的 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 <Entity ID>` — 将指定实体注册 ID 加入白名单。
- `/zzclear white entity del <Entity ID>` — 将指定实体注册 ID 从白名单移除。
> 以上命令均支持游戏内 Tab 键自动补全。
---
## 权限节点
未安装 LuckPerms 时，管理员命令需要 OP 等级 4。安装 LuckPerms 后，可使用以下权限节点进行精细化授权：
| 权限节点 | 说明 | 默认 |
| :--- | :--- | :--- |
| `zzclear.command.admin` | 重载配置、白名单管理 | 仅 OP |
| `zzclear.command.items` | 手动清除掉落物 | 仅 OP |
| `zzclear.command.monsters` | 手动清除怪物 | 仅 OP |
| `zzclear.command.animals` | 手动清除动物 | 仅 OP |
| `zzclear.command.xps` | 手动清除经验球 | 仅 OP |
| `zzclear.command.others` | 手动清除其他实体 | 仅 OP |
| `zzclear.command.status` | 查看清扫倒计时 | 所有玩家 |
---
## 配置说明
首次启动游戏后，模组会自动在以下路径生成配置文件：
```
<game root>/Zzclear/config/config.json
```
配置文件注释语言由 `language` 字段控制，支持中文与英文切换。
### 通用设置
| 参数 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `language` | `"zh"` | 配置注释语言，`zh` = 中文，`en` = 英文，重载后生效 |
| `sweepIntervalMinutes` | `4` | 清扫间隔（分钟） |
| `warningTimeSeconds` | `20` | 清扫前预警时间（秒） |
| `finalCountdownSeconds` | `5` | 最终倒计时时长（秒） |
| `countdownMessage` | 中文文本 | 倒计时预警消息模板，支持 `{0}` 占位符 |
| `sweepCompleteMessage` | 中文文本 | 清扫完成汇报模板，支持 `{0}`～`{3}` 占位符 |
| `statusMessage` | 中文文本 | `/zzclear status` 消息模板 |
| `ignoreNamedEntities` | `true` | 忽略拥有自定义名称的实体 |
| `ignoreRiddenEntities` | `true` | 保护正在被玩家骑乘的实体 |
| `newItemImmunitySeconds` | `0` | 物品掉落后的保护期（秒），`0` = 禁用 |
| `minEntityCountToSweep` | `0` | 触发清扫所需的最低实体数量，`0` = 不限制 |
| `dimensionBlacklist` | `[]` | 排除在清扫范围外的维度，例如 `["minecraft:the_end"]` |
### 物品设置
| 参数 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `sweepItems` | `true` | 启用掉落物品清除 |
| `useItemWhitelist` | `false` | 白名单模式（保护列表内物品） |
| `useItemBlacklist` | `false` | 黑名单模式（仅清除列表内物品） |
| `itemWhitelist` | `[]` | 物品白名单 |
| `itemBlacklist` | `["minecraft:diamond"]` | 物品黑名单 |
### 生物设置
| 参数 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `sweepLivingEntities` | `true` | 启用生物实体清除 |
| `dropExp` | `false` | 击杀生物时掉落经验 |
| `sweepPassiveAnimals` | `false` | 清除被动动物 |
| `sweepHostileMonsters` | `true` | 清除敌对怪物 |
| `useMobWhitelist` | `true` | 启用生物白名单模式 |
| `useMobBlacklist` | `false` | 启用生物黑名单模式 |
| `mobWhitelist` | 村民、铁傀儡等 | 生物白名单 |
| `mobBlacklist` | 村民、铁傀儡 | 生物黑名单 |
### 其他实体设置
| 参数 | 默认值 | 说明 |
| :--- | :--- | :--- |
| `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` 即可立即生效，无需重启服务端。
---
## 截图
[/MD]