WIKI: https://zkaleejoo.github.io/maxking-docs/

MaxClear

MaxClear is a lightweight Minecraft server cleanup plugin focused on reducing entity-related lag while keeping important entities and player-owned items safe. It supports scheduled clears, manual admin clears, per-chunk anti-farm limits, configurable entity filters, update notifications, bStats metrics, and fully customizable messages.

Features

• Scheduled automatic cleanup with configurable interval.
• Optional warning broadcast before each automatic clear.
• Manual cleanup command for administrators.
• Entity target list that controls exactly which entity types can be removed.
• Entity exclusion list that protects important entities from cleanup and chunk-limit checks.
• Protection for dropped items with custom display names.
• Spawn-radius protection to keep entities near each world's spawn safe.
• World filter support, with global cleanup when no worlds are listed.
• Per-chunk entity limit to reduce excessive mob farm buildup.
• Configurable prefix, messages, and color-code support using & formatting.
• Update checks on startup and every 5 hours when enabled.
• Join-time update notifications for administrators.
• Optional anonymous bStats metrics.
• Runtime reload command that refreshes config, scheduled tasks, update checks, and metrics state.
• Bukkit-style command registration with /maxclear and /mc.

Requirements

• Java 21 or newer.
• A modern Minecraft server compatible with Bukkit/Paper APIs.
• Plugin metadata targets api-version: 1.21.

Paper is recommended for modern production servers. Spigot-compatible servers should only be used if they provide the APIs required by your server version.

REMEMBER TO CHECK THE WIKI TO STAY UP-TO-DATE ON PERMISSIONS AND COMMANDS

Commands

Command	Alias	Permission	Sender	Description
/maxclear	/mc	maxclear.admin for players	Player / Console	Shows the command help.
/maxclear reload	/mc reload	maxclear.admin for players	Player / Console	Reloads the configuration and refreshes runtime tasks, update checks, and metrics state.
/maxclear clear	/mc clear	maxclear.admin for players	Player / Console	Runs a manual entity cleanup immediately.
/maxclear get author	/mc get author	maxclear.admin for players	Player / Console	Shows the plugin author.
/maxclear get version	/mc get version	maxclear.admin for players	Player / Console	Shows the running plugin version.

Players without maxclear.admin cannot use the command or receive tab completions. Console execution is allowed for the registered subcommands.

Permissions

Permission	Default	Description
maxclear.admin	op	Allows players to use MaxClear commands, receive command tab completions, and receive update notifications when a new version is available.

How Cleanup Works

MaxClear only removes entities that pass all configured checks:

1. The entity must be in entities.types.
2. The entity must not be in entities.exclude.
3. If entities.settings.ignore-named-items is enabled, dropped items with a custom display name are protected.
4. If entities.settings.min-distance-from-spawn is greater than 0, entities inside that radius from the world's spawn are protected.
5. If entities.settings.worlds is not empty, only listed worlds are processed.

Automatic clears use the completed message list. Manual clears use the manual-clear message and include the command sender name.

Anti-Farm Chunk Limit

When chunk-limit.enabled is enabled, MaxClear listens for creature spawns and limits the number of non-player, non-excluded entities in the target chunk.

• chunk-limit.max controls the maximum allowed entity count per chunk.
• Entities in entities.exclude are ignored by the chunk-limit count.
• Player entities are always ignored by the chunk-limit count.
• Custom spawn reasons are ignored by the limiter.

This system helps reduce extreme entity buildup without blocking excluded entities such as villagers, armor stands, minecarts, boats, or other protected types.

Configuration

The default configuration is stored in config.yml.

General

Path	Type	Default	Description
general.prefix	String	Configured in config.yml	Prefix used before plugin messages.
general.update-check	Boolean	true	Enables startup and scheduled update checks.
general.bstats	Boolean	true	Enables anonymous bStats metrics.

Automatic Clear

Path	Type	Default	Description
auto-clear.enabled	Boolean	true	Enables scheduled automatic cleanup.
auto-clear.interval	Integer	300	Seconds between automatic cleanup runs.

Warning Messages

Path	Type	Default	Description
messages.warning.enabled	Boolean	true	Enables a warning broadcast before automatic cleanup.
messages.warning.seconds-before	Integer	10	Seconds before the clear when the warning is sent. Must be lower than auto-clear.interval.
messages.warning.message	String	Configurable	Warning message. Supports {time}.

Cleanup Messages

Path	Type	Description
messages.completed.message	String list	Broadcast after an automatic clear. Supports {count}.
messages.manual-clear.message	String	Broadcast after a manual clear. Supports {player} and {count}.
messages.no-permission	String	Sent to players without permission.
messages.plugin-reload	String	Sent after a successful reload.
messages.subcommand-invalid	String	Sent when an invalid subcommand argument is used.
messages.subcommand-specified	String	Sent when a required subcommand argument is missing.

Update Messages

Path	Type	Description
messages.update-available	String	Admin join notification line. Supports {version} for the latest version.
messages.update-current	String	Admin join notification line. Supports {version} for the current version.
messages.update-download	String	Admin join notification line shown before the download URL.

Update notifications link to:

/plugins/maxclear

Entity Removal

Path	Type	Default Behavior
entities.types	String list	Entity types that MaxClear is allowed to remove.
entities.exclude	String list	Entity types that are protected from cleanup and ignored by chunk-limit counting.
entities.settings.ignore-named-items	Boolean	Protects dropped items with a custom display name.
entities.settings.min-distance-from-spawn	Integer	Protects entities inside this radius from each world's spawn. 0 disables the radius check.
entities.settings.worlds	String list	Limits cleanup to listed worlds. Empty list means all worlds.

Default removable entity types:

entities:
  types:
    - ITEM
    - ARROW
    - EXPERIENCE_ORB
    - TNT
    - FIREWORK_ROCKET
    - TRIDENT
    - SNOWBALL
    - EGG
    - ENDER_PEARL

Default protected entity types include players, villagers, item frames, armor stands, paintings, minecarts, boats, chest boats, and minecart variants.

Entity Name Aliases

MaxClear supports aliases for compatibility with newer and older entity names:

Alias	Resolves To
BOAT	All regular boat variants, including oak, spruce, birch, jungle, acacia, dark oak, mangrove, cherry, and pale oak boats.
CHEST_BOAT	All chest boat variants, including oak, spruce, birch, jungle, acacia, dark oak, mangrove, cherry, and pale oak chest boats.
MINECART_CHEST	CHEST_MINECART
MINECART_FURNACE	FURNACE_MINECART
MINECART_HOPPER	HOPPER_MINECART
MINECART_TNT	TNT_MINECART
MINECART_MOB_SPAWNER	SPAWNER_MINECART
MINECART_COMMAND	COMMAND_BLOCK_MINECART

Entity names are normalized to uppercase when loaded from the configuration.

Placeholders

Placeholder	Used In	Description
{time}	messages.warning.message	Seconds remaining before the automatic clear.
{count}	messages.completed.message, messages.manual-clear.message	Number of entities removed.
{player}	messages.manual-clear.message	Sender name for a manual clear.
{version}	Update messages	Latest or current plugin version, depending on the message.

Notes for Server Owners

• Keep entities.exclude conservative if your server uses display entities, NPCs, custom mobs, or plugin-managed entities.
• Use entities.settings.worlds when you only want cleanup in specific worlds.
• Set entities.settings.min-distance-from-spawn above 0 if your spawn area contains decorative dropped items or protected entities.
• Keep messages.warning.seconds-before lower than auto-clear.interval; invalid warning timing is disabled safely and logged.
• Reloading with /maxclear reload is enough for normal configuration changes.