🧹 ClearItems - 自动化实体清理 / Automated Entity Cleanup

ClearItems 是一款专为 Fabric 生态构建的生产级清理模组。它在确保极端环境稳定性的同时，提供了更灵活的权限调用机制，是大型整合包与自动化管理服务器的理想选择。

ClearItems is a production-grade cleanup solution for the Fabric ecosystem. Engineered for stability in heavy modpacks, it features a flexible permission mechanism and lightweight feedback, ideal for automated server management.

💎 核心技术优势 / Technical Advantages

🛡️ 全环境兼容性架构 (Permission-Free Logic)

权限等级解耦：重构了指令触发逻辑，移除了底层对 isOp() 的强制判定。允许通过自动化脚本、非 OP 玩家（需配合权限插件）或命令方块直接调用。
Permission Decoupling: Refactored logic to remove isOp() dependencies, allowing invocation via scripts, non-OP players (with permission mods), or command blocks.
极速环境适配：针对重度混淆的服务器环境进行了深度调优，确保在大型模组环境下稳定运行。
Seamless Adaptation: Deeply tuned for complex, heavily obfuscated server environments to ensure maximum uptime.

🟢 高兼容性渲染架构 (ActionBar-First)

零 UI 冲突：采用 ActionBar 文本注入 代替传统的 BossBar，彻底规避屏幕上方 UI 叠加导致的视觉冲突。
Zero UI Conflict: Uses ActionBar text injection to avoid visual clutter and HUD overlaps common with BossBars in large modpacks.
原生感设计：彩色文字随时间动态切换（绿色 > 黄色 > 红色），视觉反馈直观且轻量。
Native-Feel Feedback: Dynamic color transitions (Green > Yellow > Red) provide intuitive, lightweight alerts.

🚀 核心功能 / Core Features

📋 实时查询 (Whitelist Query)：使用 /clearitems list 随时监控受保护物品状态。
🛠️ 极致稳定 (Extreme Stability)：针对高负载环境优化的防御性逻辑，清理周期精准不漂移。
📈 原子级战报 (Atomic Reporting)：精准统计掉落物 实际总堆叠数量，而非仅统计实体个数。
⚙️ 极简开销 (Minimal Overhead)：基于原生 Fabric API，与 Lithium、FerriteCore 等优化模组完美兼容。

🎮 指令参考手册 / Command Reference

指令 (Command)	参数 (Parameters)	描述 (Description)
set	`<seconds>`	设置清理周期 / Set cleanup interval
add	`<item_id>`	添加白名单 / Add item to whitelist
remove	`<item_id>`	移除白名单 / Remove from whitelist
list	—	[New] 查看白名单 / View whitelist
clear	—	立即执行清理 / Trigger immediate cleanup

📦 安装与协议 / Installation & License

Minecraft: 1.21.x
Requirement: Fabric API
License: MIT License

⚠️ 安全提示 / Security Notice：

由于移除了指令的权限等级要求，若您在公网服务器运行，请务必使用权限管理插件（如 LuckPerms）对 /clearitems 指令进行节点控制，以确保服务器安全。

Since mandatory permission level requirements have been removed, please ensure you use a permission management plugin (e.g., LuckPerms) to control access nodes for the /clearitems command on public servers.

❓ 常见问题解答 / FAQ

Q: 为什么我看不到 BossBar 倒计时了？

Why can't I see the BossBar?

为了兼容 200+ 模组的重型整合包，自 v1.1.1 起我们将提示切换到了 ActionBar（快捷栏上方），有效规避了 UI 堆叠冲突。
To ensure compatibility with massive modpacks (200+ mods), we migrated alerts to the ActionBar starting from v1.1.1. This prevents visual clutter from overlapping BossBars.

Q: 为什么非 OP 玩家也能使用指令？

Why can non-OP players use commands?

我们移除了硬性的 OP 权限检查以支持脚本自动化。在公网服务器上，请务必使用 LuckPerms 对权限节点进行控制，防止非法调用。
Hardcoded OP checks were removed to support automation. On public servers, please use LuckPerms to restrict permission nodes for security.

Q: 会清理掉盔甲架或展示框里的装备吗？

Does it clear items on Armor Stands or Item Frames?

不会。 ClearItems 仅针对掉落物实体（Item Entity），不会影响任何已经放置的容器、盔甲架或展示框。
No. ClearItems only targets dropped item entities and will not affect armor stands, item frames, or placed containers.

Q: 如何保护特定物品不被清理？

How to protect specific items?

使用指令 /clearitems add <item_id>（例如 minecraft:diamond）将其加入白名单。白名单内的物品将永远受到保护。
Use /clearitems add <item_id> (e.g., minecraft:diamond) to add specific items to the global whitelist for permanent protection.

Q: 兼容 Lithium、FerriteCore 等优化模组吗？

Is it compatible with Lithium or FerriteCore?

完美兼容。 模组基于原生 Fabric API 编写，不修改核心逻辑，与各类底层优化模组并行无压力。
Fully compatible. Built on native Fabric API without core logic modification, ensuring seamless operation alongside major optimization mods.

👀 即将到来 / Coming Soon (v1.2.0)

我们正在全速开发全新的 显示切换系统 (Flexible HUD Engine)！在即将到来的 v1.2.0 版本中，您将拥有前所未有的自定义体验：

We are working on a new Display Toggle System (Flexible HUD Engine)! In the upcoming v1.2.0, you will have unprecedented customization options:

🚦 双模式渲染 (Dual-Mode Rendering)：您将可以在经典的 BossBar（适合轻量整合包）与高性能的 ActionBar（适合 200+ 模组的重型整合包）之间自由切换。 Switch between classic BossBar (for light packs) and high-performance ActionBar (for heavy packs) freely.
⚙️ 配置文件支持 (Config Support)：引入 config.json，允许永久指定默认的显示模式，并支持动态加载。 Introducing config.json to permanently set the default display mode with hot-reload support.
即时切换指令 (Hot-Swap Command)：新增管理员指令，可在游戏内即时更改 UI 表现形式，无需重启。 New admin command to change UI style in-game instantly without a restart.