ClearDrops

Cleardrops

A server-side-only Forge 1.20.1 mod that cleans up dropped items into a shared recycle bin. It supports automatic/manual collection, retrieval via the vanilla chest GUI, hot‑reloadable configuration, gradient‑colored messages, an item blacklist, pre‑collection warnings, and void item protection. Works with vanilla clients—no client mod required.

• Minecraft: 1.20.1
• Forge: 47.4.x
• Java: 17
• Mod ID: cleardrops
• Client dependency: None (vanilla clients can join and use the GUI)

Features

• Automatic periodic cleanup of world item entities (configurable interval and toggle)
• Manual cleanup via command
• Recycle Bin (54 slots), opened with the vanilla 6‑row chest container
• Config hot reload: edit and save world/serverconfig/cleardrops-server.toml, or run /cleardrops reload
• Fully configurable messages (Chinese/English or any language), with gradient color support
• Pre‑collection warnings at configurable second marks
• Item blacklist:
• Blacklisted items will not be collected from the world
• Blacklisted items are also skipped when purging the recycle bin (never destroyed by this mod)
• Void item protection: items falling into the void are teleported back up to a safe height

Installation

1. Place the mod jar into your server’s mods/ folder.
2. Launch the server once to generate the config.
3. Edit <WORLD>/serverconfig/cleardrops-server.toml to your needs.
4. Config is hot‑reloaded on save; alternatively, run /cleardrops reload.

Commands

• /cleardrops help — Show help (uses configurable, gradient‑styled text)
• /cleardrops gui — Open the recycle bin (vanilla chest GUI)
• /cleardrops status — Show current inventory, countdowns, and toggles
• /cleardrops collect — Collect dropped items immediately (permission level ≥ 2)
• /cleardrops purge — Purge the recycle bin immediately (permission level ≥ 2; blacklist is skipped)
• /cleardrops reload — Reload config from TOML (permission level ≥ 2)

Permissions follow the server’s standard op levels (hasPermission(2)).

Configuration (with Hot Reload)

Path: <WORLD>/serverconfig/cleardrops-server.toml

Save the file to apply instantly (hot reload), or run /cleardrops reload.

[general]
# Enable periodic automatic collection of dropped items.
enableAutoCollect = true
# Ticks between automatic collections. 20 ticks = 1 second.
ticksPerCollect = 6000
# Ticks to keep items in the recycle bin after a collection before purging.
ticksKeepAfterCollect = 2400
# Broadcast messages (warnings, collected, purged, etc.) to online players.
announceMessages = true

[blacklist]
# Item IDs (e.g., minecraft:nether_star). Blacklisted items will not be collected,
# and will be skipped during purge as well (never destroyed by this mod).
items = ["minecraft:nether_star", "minecraft:totem_of_undying"]

[void_protection]
# Pull items falling into the void back up to the world's min build height area.
enableVoidProtect = true
# Max upward steps (in blocks) to find a safe air position.
raiseMaxSteps = 6
# Reset item velocity when rescued from the void.
resetVelocity = true

[messages]
# Message prefix (supports gradient tags). Example:
prefix = "<gradient:#00E5FF:#00FF7F>[Cleardrops]</gradient>"
# Pre-collection warning seconds.
warnSeconds = [60, 30, 10, 5, 4, 3, 2, 1]

# Warning message template (placeholders: {time})
msgPreCollect = "Collecting dropped items in {time}s. Please pick up valuables!"

# Auto-collection complete (placeholders: {entities}, {keep})
msgCollected = "Collected {entities} item entities. Use /cleardrops gui to retrieve. Purging in {keep}s."

# Purge complete (placeholders: {slots})
msgPurged = "Recycle bin purged. Cleared {slots} slot(s)."

# Status (placeholders: {slotsUsed}, {slotsTotal}, {items}, {keep}, {auto}, {interval}, {keepCfg}, {announce})
msgStatus = "Recycle Bin: {slotsUsed}/{slotsTotal} slots, {items} items; Purge in {keep}; Auto={auto}, Interval={interval}s, Keep={keepCfg}s, Announce={announce}."

# Help (supports gradient and \n newlines)
msgHelp = "<gradient:#7AD7F0:#4FC3F7>Cleardrops Help</gradient>\n<gradient:#A8FF78:#78FFD6>/cleardrops gui</gradient> - Open recycle bin\n<gradient:#A8FF78:#78FFD6>/cleardrops status</gradient> - Show status\n<gradient:#FFD54F:#FF8A00>/cleardrops collect</gradient> - Collect now (perm 2)\n<gradient:#FFD54F:#FF8A00>/cleardrops purge</gradient> - Purge now (perm 2)\n<gradient:#B388FF:#7C4DFF>/cleardrops reload</gradient> - Reload config (perm 2)"

# Manual command feedback
# /cleardrops collect (placeholders: {entities}, {keep})
msgCmdCollect = "Collected {entities} item entities. You have {keep}s to retrieve them from the bin."

# /cleardrops purge (placeholders: {slots})
msgCmdPurge = "Recycle bin purged: {slots} slot(s) cleared. Blacklisted items were skipped."

Message Formatting

• Gradient tag:
• Syntax: <gradient:#RRGGBB:#RRGGBB>text</gradient>
• Colors are applied per character via linear interpolation.
• Works in prefix, msgHelp, and any message template.
• Placeholders:
• Warnings: {time}
• Collected: {entities}, {keep}
• Purged: {slots}
• Status: {slotsUsed}, {slotsTotal}, {items}, {keep}, {auto}, {interval}, {keepCfg}, {announce} (and optionally {blacklistedStacks} if you add it to your template)

Blacklist and Void Protection

• Blacklist:
• Items on the list are NOT collected during cleanup (left in the world).
• Items in the recycle bin that are blacklisted are NOT purged (never destroyed by this mod).
• Void Protection:
• Detects item entities below the min build height and teleports them up to a safe air position.
• Configurable maximum raise steps and whether to zero velocity.

FAQ