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

• Do clients need the mod installed?
  • No. This is server‑only. The UI uses the vanilla chest container.
  • Conflicts with other cleanup mods?
    • Multiple cleanup systems may overlap. Prefer one primary cleaner or stagger schedules.
  • Config changes don’t apply?
    • Make sure you edit the current world’s serverconfig/cleardrops-server.toml. Save to hot reload, or run /cleardrops reload.

Development

• JDK 17, Forge 1.20.1 (47.4.x)
• Build: ./gradlew build (artifacts under build/libs/)
• Key packages:
  • cn.alini.cleardrops.server.ServerScheduler — core scheduling, collection/purge, warnings, void protection, blacklist
  • cn.alini.cleardrops.config.CDConfig — config spec and hot reload
  • cn.alini.cleardrops.command.CleardropsCommands — command registration and handlers
  • cn.alini.cleardrops.util.MessageUtil — gradient rendering and placeholders
  • cn.alini.cleardrops.storage.TrashStorage — recycle bin storage

License

This project is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0). See LICENSE for details.

You may copy, modify, and distribute this project as long as you provide proper attribution.