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 language field. 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.json file 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!

ZzaiClear