ClearDropss

# 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`.

“`toml
[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](LICENSE) for details.

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