SerendiClear

SerendiClear is a server-side Fabric mod for Minecraft 26.2+ that keeps your world clean — automatically removing dropped items and limiting mob stacking — all with a BossBar countdown and a convenient trash-bin GUI where items go before they vanish.

---

Features

• 🧹 Auto-cleanup — Configurable interval (default: every 30 minutes) sweeps item drops and excess mobs.
• ⏲️ BossBar Countdown — A visible BossBar warns all players before a cleanup (default: 60 seconds).
• 🗑️ Trash Bin GUI — Removed items are stored in a paginated chest GUI (/垃圾桶) so players can reclaim them.
• 👾 Mob Stack Limiting — Limits the number of the same mob type within a configurable radius (default: ≤24 per 16 blocks).
• 🛡️ Smart Protection — Named entities/items and configurable item IDs are never removed.
• 🌍 Multi-world — Target specific worlds or all worlds at once.
• 🎮 Manual Trigger — /serendiclear clear starts a cleanup on demand.
• ⚙️ Hot-Reloadable Config — /serendiclear reload applies config changes without a restart.
• 🔌 Pure Server-Side — No client-side installation needed.

---

Commands

Command	Permission	Description
/serendiclear clear	commands.gamemaster	Manually start the cleanup countdown
/serendiclear reload	commands.gamemaster	Reload the config file from disk
/垃圾桶	(everyone)	Open the trash bin GUI to retrieve collected items

The command /垃圾桶 is the Chinese word for "trash can." It can be aliased or changed in a future version.

---

Configuration

The config file is located at config/serendiclear.json. It is auto-generated with defaults on first run.

General Options

Option	Type	Default	Description
worlds	string[]	["all"]	Worlds to clean. Set to ["all"] for all dimensions, or list specific ones (e.g. ["minecraft:overworld"]).
intervalMinutes	int	30	Interval between automatic cleanups (minutes). Minimum: 1.
broadcastSeconds	int	60	Countdown duration in seconds. Set to 0 for instant cleanup.
prefix	string	"§9SerendiClear >> "	Message prefix used in chat.
bossbarTitle	string	"§e即将清理！倒计时: §c{time} §e秒"	BossBar title. {time} is replaced with the remaining seconds.

Item & Mob Options

Option	Type	Default	Description
clearDrops	bool	true	Whether to remove loose item entities.
clearMobs	bool	true	Whether to enforce the mob stacking limit.
maxMobStack	int	24	Maximum number of the same mob type allowed within mobStackRadius.
mobStackRadius	int	16	Radius (in blocks) to detect stacked mobs.
protectNamed	bool	true	Whether named entities or renamed item stacks are skipped.
protectedItems	string[]	[]	Item IDs to never remove (e.g. ["minecraft:diamond", "minecraft:netherite_ingot"]).

Trash Bin Options

Option	Type	Default	Description
trashEnabled	bool	true	Enable the trash bin. When off, dropped items are simply deleted.
trashMaxPages	int	5	Maximum number of trash bin pages (each page is a chest-size 54-slot grid).
trashTitle	string	"§9§l垃圾桶 §7(第{page}/{max}页)"	Title of the trash GUI. {page} and {max} are placeholders.
trashOpenButton	string	"§e§l【点我打开垃圾桶】"	Clickable chat message sent after a cleanup.
trashExcludedWorlds	string[]	[]	Worlds where no trash-bin message is sent.

When the trash bin runs out of space (all pages full), it auto-clears and starts fresh. A notification is broadcast when this happens.

---

Installation

1. Install Fabric Loader for Minecraft 26.2+.
2. Place the SerendiClear-<version>.jar into your server's mods/ folder.
3. Start the server — the mod is pure server-side and needs no client-side mod.
4. Configure config/serendiclear.json to your liking (it generates automatically).

Dependencies

• Fabric API (any version compatible with your Minecraft)
• Minecraft 26.2+

How It Works

1. Tick loop — Every server tick, the mod checks if intervalMinutes have elapsed.
2. Countdown — When triggered, a BossBar appears and counts down for broadcastSeconds. Players can use /垃圾桶 in the meantime.
3. Cleanup — The mod iterates all loaded chunks in the target worlds:
   • Drops: Removes unprotected ItemEntity instances and stores them in the trash bin.
   • Mobs: Groups living entities by type, finds clusters within mobStackRadius, and removes the farthest excess members until the cluster meets maxMobStack.
4. Trash notification — After cleanup, a clickable chat button invites players to open the trash bin and reclaim their items.

---

Permission System

The mod uses Fabric API's built-in permission API at the commands.gamemaster level. Players with operator status (or granted this permission via a permission mod) can use the administrative commands.

---

License

This project is licensed under the MIT License.