Zzclear is a lightweight, highly intelligent entity clearing and server optimization mod for Minecraft Fabric. It silently operates in the background to automatically sweep up dropped items, abandoned entities, and lag-inducing objects based on a highly configurable frequency timer. With a powerful in-game command system and hot-reloadable configuration logic, it eliminates server lag from its absolute source!
✨ Core Features
- 🕐 Automated Scheduled Clearing: Customize the sweeping cycles (down to the exact minute); when the timer strikes, lingering entities are flawlessly eradicated.
- 🛡️ Smart Whitelists & Filters: Say goodbye to "one-size-fits-all" wipes! Whether it's dropped items, specific monsters, or individual entity types, Zzclear supports precise bypassing and explicit targeting via its blacklist/whitelist arrays.
- 🐴 Rider Protection: Entities currently being ridden by players (horses, boats, minecarts, etc.) are automatically protected from clearing.
- ⏱️ Item Drop Immunity: Newly dropped items can be given a grace period to prevent them from being immediately swept up.
- 🌍 Dimension Filtering: Exclude specific dimensions (e.g., The End) from the sweep cycle entirely.
- 📊 Sweep Threshold: Skip the clearing cycle when the number of target entities is below a configurable minimum, avoiding unnecessary empty runs.
- 🌐 Bilingual Config: Config file comments support Chinese and English, controlled by the
languagefield. Takes effect after/zzclear reload. - 🪓 Total Entity Management:
- Standard Clearing: Dropped Items, Experience Orbs
- Mob Clearing: Hostile/Neutral Monsters, Passive Animals
- Vehicles/Decorations: Boats, Paintings, Item Frames
- Physics/Projectiles: Fired Arrows, Thrown Tridents, Falling Blocks, Primed TNT, Shulker Bullets, Firework Rockets, and more.
- 🔄 Hot-Reload Commands: Changing the configuration data file? No need to restart the server! A single built-in command applies the new rules instantly.
⌨️ In-Game Commands
The primary root command is /zzclear:
1. Configuration Reload (Admin)
/zzclear reload
- Function: Re-reads the
config/config.jsonfile from disk and immediately applies all new clearing filters, timer periods, and refreshes config comment language.
2. Check Clear Countdown (All Players)
/zzclear status
- Function: Shows the remaining time (minutes and seconds) until the next automatic sweep.
3. Manual Immediate Sweeping (Admin)
If you do not want to wait for the background timer intervals, use these commands to instantly wipe specific entity categories:
/zzclear items— Instantly clears all dropped items on the ground./zzclear monsters— Instantly clears all hostile and neutral monsters./zzclear animals— Instantly clears all friendly, passive animals./zzclear xps— Instantly clears all floating experience orbs./zzclear others— Instantly clears miscellaneous entities (e.g., Paintings, Boats, Falling Blocks, Projectiles).
4. Item Whitelists (Admin)
Hold an item in your main hand and instantly register it into the whitelist filters to prevent the sweeper from ever consuming it:
/zzclear white item add— Adds the currently held item into the global whitelist./zzclear white item del— Removes the currently held item from the global whitelist.
5. Entity ID Whitelists (Admin)
If you need to meticulously protect or exclude a specific living organism or object (e.g., minecraft:zombie), utilize these endpoints:
/zzclear white entity add <Entity ID>— Adds a specific entity registry ID into the whitelist./zzclear white entity del <Entity ID>— Un-registers a specific entity registry ID from the whitelist.Note: These commands fully support in-game Tab autocompletion suggestions!
🔑 Permission Nodes
Without LuckPerms, admin commands require OP level 4. With LuckPerms installed, use these permission nodes for fine-grained control:
| Permission | Description | Default |
|---|---|---|
zzclear.command.admin | Reload, whitelist management | OP only |
zzclear.command.items | Manual item clearing | OP only |
zzclear.command.monsters | Manual monster clearing | OP only |
zzclear.command.animals | Manual animal clearing | OP only |
zzclear.command.xps | Manual XP orb clearing | OP only |
zzclear.command.others | Manual other entity clearing | OP only |
zzclear.command.status | View clear countdown | All players |
⚙️ Configuration Setup
After launching the game once, the mod automatically generates the config file at:
<game root>/Zzclear/config/config.json
The config file includes comments in Chinese or English (controlled by the language field).
Common Settings
| Parameter | Default | Description |
|---|---|---|
language | "zh" | Config comment language, zh=Chinese, en=English. Takes effect after reload |
sweepIntervalMinutes | 4 | Sweep interval in minutes |
warningTimeSeconds | 20 | Warning time before sweep (seconds) |
finalCountdownSeconds | 5 | Final countdown duration (seconds) |
countdownMessage | Chinese text | Countdown warning message template, supports {0} placeholder |
sweepCompleteMessage | Chinese text | Sweep complete summary template, supports {0}~{3} placeholders |
statusMessage | Chinese text | /zzclear status message template |
ignoreNamedEntities | true | Ignore entities with custom names |
ignoreRiddenEntities | true | Protect entities being ridden by players |
newItemImmunitySeconds | 0 | Item drop immunity (seconds after drop), 0=disabled |
minEntityCountToSweep | 0 | Minimum entity count to trigger sweep, 0=no limit |
dimensionBlacklist | [] | Dimensions excluded from sweep, e.g. ["minecraft:the_end"] |
Item Settings
| Parameter | Default | Description |
|---|---|---|
sweepItems | true | Enable item entity sweeping |
useItemWhitelist | false | Whitelist mode (protect listed items) |
useItemBlacklist | false | Blacklist mode (only sweep listed items) |
itemWhitelist | [] | Item whitelist |
itemBlacklist | ["minecraft:diamond"] | Item blacklist |
Mob Settings
| Parameter | Default | Description |
|---|---|---|
sweepLivingEntities | true | Enable living entity sweeping |
dropExp | false | Drop experience when killing mobs |
sweepPassiveAnimals | false | Sweep passive animals |
sweepHostileMonsters | true | Sweep hostile monsters |
useMobWhitelist | true | Enable mob whitelist mode |
useMobBlacklist | false | Enable mob blacklist mode |
mobWhitelist | Villagers, Iron Golems, etc. | Mob whitelist |
mobBlacklist | Villagers, Iron Golems | Mob blacklist |
Other Entity Settings
| Parameter | Default | Description |
|---|---|---|
sweepExperienceOrbs | false | Sweep experience orbs |
sweepFallingBlocks | false | Sweep falling blocks (e.g. sand) |
sweepArrows | false | Sweep arrows |
sweepTridents | false | Sweep tridents |
sweepProjectiles | false | Sweep projectiles |
sweepShulkerBullets | false | Sweep shulker bullets |
sweepFireworks | false | Sweep firework rockets |
sweepItemFrames | false | Sweep item frames |
sweepPaintings | false | Sweep paintings |
sweepBoats | false | Sweep boats |
sweepPrimedTNT | false | Sweep primed TNT |
Tip: After tweaking the JSON config, jump right back into the game and fire
/zzclear reload. Done instantly, with absolutely zero delays!
