GroundClear Documentation

Features

• Automatically clears dropped ground items.
• Configurable clear interval and countdown warning messages.
• Option to disable announcements or the final clear message.
• Manual clear, config reload, and status commands.
• Minimum item age protection to avoid clearing fresh drops too quickly.
• Ignored item and ignored world lists.
• Optional protection for items with custom names.
• Simple JSON config file.

Default behavior

With the default config, GroundClear uses a balanced setup that reduces item buildup while protecting common valuable items and recently dropped items.

Installation

1. Download the GroundClear .jar file intended for your server.
2. Place the GroundClear .jar file into the server's mods folder.
3. Start the server.
4. Edit config/groundclear.json if you want to change the default behavior.
5. Run /groundclear reload after editing the config, or restart the server.

Important: Use the GroundClear file intended for your server. Compatibility details should be checked on the download page.

Commands

All GroundClear commands require OP permission level 2 by default.

Configuration

The config file is generated after the server is started with GroundClear installed.

Config location:

config/groundclear.json

After editing the config, run:

/groundclear reload

Or restart the server.

Default config

{
  "enabled": true,
  "intervalSeconds": 600,
  "minimumItemAgeSeconds": 60,
  "announcementsEnabled": true,
  "warningSeconds": [
    300,
    120,
    60,
    30
  ],
  "broadcastClearMessage": true,
  "warningMessage": "Ground items will be cleared in {time}.",
  "clearMessage": "Cleared {count} ground items.",
  "clearNamedItems": false,
  "ignoredItems": [
    "minecraft:nether_star",
    "minecraft:dragon_egg"
  ],
  "ignoredWorlds": []
}

Config reference

enabled

Enables or disables automatic item clearing.

"enabled": true

Set this to false to disable automatic clearing.

intervalSeconds

Controls how often dropped ground items are cleared. This value is in seconds.

"intervalSeconds": 600

minimumItemAgeSeconds

Controls how old an item must be before automatic clearing can remove it.

"minimumItemAgeSeconds": 60

If this is set to 60, an item must be on the ground for at least 60 seconds before automatic cleanup can remove it. This helps prevent newly dropped items from being cleared immediately.

announcementsEnabled

Enables or disables countdown and clear messages.

"announcementsEnabled": true

Set this to false if you want GroundClear to clear items silently.

warningSeconds

Controls when warning messages are sent before a clear. These values are in seconds before the clear.

"warningSeconds": [
  300,
  120,
  60,
  30
]

The default warnings are sent at 5 minutes, 2 minutes, 1 minute, and 30 seconds before the clear.

Only a 1-minute warning:

"warningSeconds": [
  60
]

No countdown warnings:

"warningSeconds": []

broadcastClearMessage

Controls whether a message is sent after items are cleared.

"broadcastClearMessage": true

Set this to false if you want countdown warnings but no final cleared-items message.

warningMessage

The message shown before items are cleared.

"warningMessage": "Ground items will be cleared in {time}."

Available placeholder: {time}

Example custom message:

"warningMessage": "Item cleanup will happen in {time}!"

clearMessage

The message shown after items are cleared.

"clearMessage": "Cleared {count} ground items."

Available placeholder: {count}

Example custom message:

"clearMessage": "Cleanup complete! Removed {count} dropped items."

clearNamedItems

Controls whether named items should be cleared.

"clearNamedItems": false

When set to false, items with custom names are protected. Set this to true if you want named items to be cleared like normal items.

ignoredItems

Items listed here will never be cleared. Use normal Minecraft item IDs.

"ignoredItems": [
  "minecraft:nether_star",
  "minecraft:dragon_egg"
]

Examples:

• minecraft:diamond
• minecraft:elytra
• minecraft:netherite_sword
• minecraft:totem_of_undying

Example config:

"ignoredItems": [
  "minecraft:nether_star",
  "minecraft:dragon_egg",
  "minecraft:elytra",
  "minecraft:totem_of_undying"
]

ignoredWorlds

Worlds listed here will be ignored by GroundClear.

"ignoredWorlds": []

Example excluding The End:

"ignoredWorlds": [
  "minecraft:the_end"
]

Common world IDs:

• minecraft:overworld
• minecraft:the_nether
• minecraft:the_end

Example setups

"announcementsEnabled": false

"warningSeconds": [
  60
]

"ignoredItems": [
  "minecraft:nether_star",
  "minecraft:dragon_egg",
  "minecraft:elytra",
  "minecraft:totem_of_undying"
]

"intervalSeconds": 1800

Client installation

GroundClear is intended as a server-side utility mod.

Players should not need to install GroundClear on their client when joining a server that has the mod installed.

Modpack usage

You may include GroundClear in modpacks.

Requirements

GroundClear requires a compatible Minecraft server and access to the server's mods folder.

• A compatible Minecraft server.
• Access to the server's mods folder.

Tip: This documentation focuses on how GroundClear works. The commands and configuration are the same across supported downloads.

Support

If you run into an issue, include these details when asking for help:

• Minecraft version
• Mod loader and loader version
• GroundClear version
• Your groundclear.json config
• Any relevant server logs

License

GroundClear is licensed under the MIT License.