GroundClear#

GroundClear is a lightweight server utility mod that automatically clears dropped ground items on a configurable timer.

It is designed for server owners who want a simple way to reduce item buildup without installing a large performance or administration mod.

GroundClear is built to be simple, configurable, and server-friendly.

Features#

• Automatically clears dropped ground items
• Configurable clear interval
• Configurable countdown warning messages
• Option to disable announcements
• Manual clear command
• Config reload command
• Status command
• Minimum item age protection
• Ignored item list
• Ignored world list
• Option to protect named items
• Simple JSON config
• Server-side utility mod

Supported Versions#

Current release:

• Minecraft 1.21.1
• NeoForge

Planned support:

• Additional Minecraft versions
• Additional mod loaders

Future loader/version support may be released as separate files. Always download the file that matches your Minecraft version and mod loader.

Default Behavior#

By default, GroundClear:

• Clears dropped ground items every 10 minutes
• Sends warnings at 5 minutes, 2 minutes, 1 minute, and 30 seconds before clearing
• Only automatically clears items that are at least 60 seconds old
• Does not clear named items
• Ignores Nether Stars and Dragon Eggs

Commands#

All commands require OP permission level 2 by default.

/groundclear status#

Shows whether GroundClear is enabled and how long remains until the next automatic clear.

/groundclear now#

Immediately clears dropped ground items.

Manual clearing ignores the minimum item age setting, so recently dropped items can be cleared when this command is used.

/groundclear reload#

Reloads the config file without restarting the server.

Use this after editing groundclear.json.

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 Options#

enabled#

Enables or disables automatic item clearing.

"enabled": true

Set to false to disable automatic clearing.

intervalSeconds#

Controls how often dropped ground items are cleared.

"intervalSeconds": 600

This value is in seconds.

Common values:

• 300 = 5 minutes
• 600 = 10 minutes
• 900 = 15 minutes
• 1800 = 30 minutes
• 3600 = 1 hour

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.

"announcementsEnabled": false

warningSeconds#

Controls when warning messages are sent before a clear.

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

These values are in seconds before the clear.

The default values mean:

• 300 = 5 minutes before clear
• 120 = 2 minutes before clear
• 60 = 1 minute before clear
• 30 = 30 seconds before clear

Example with only a 1-minute warning:

"warningSeconds": [
  60
]

Example with 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 to true if you want named items to be cleared like normal items.

ignoredItems#

Items listed here will never be cleared.

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

Use normal Minecraft item IDs.

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

Installation#

1. Download the GroundClear file that matches your Minecraft version and mod loader.
2. Place the GroundClear .jar file into the server's mods folder.
3. Start the server.
4. Edit config/groundclear.json if desired.
5. Use /groundclear reload after editing the config, or restart the server.

Requirements#

Requirements depend on the file you download.

Current release:

• Minecraft 1.21.1
• NeoForge 21.1.x

Download the correct GroundClear file for your server's Minecraft version and mod loader.

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.

Support#

If you run into an issue, please include:

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