SerendiClear

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.

1. 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.