Описание
# 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 `/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: `/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 = "[Cleardrops]"
# 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 = "Cleardrops Help\n/cleardrops gui - Open recycle bin\n/cleardrops status - Show status\n/cleardrops collect - Collect now (perm 2)\n/cleardrops purge - Purge now (perm 2)\n/cleardrops reload - 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: `text`
- 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.