🧹 Smart Item Deleter v2

A lightweight, intelligent item cleanup system for NeoForge 1.21.1

---

📘 Overview

Smart Item Deleter v2 is a server-side optimization mod designed to automatically clean up dropped item entities when the item count exceeds a defined threshold.
It tracks items individually to ensure fair, efficient, and safe removal — deleting only excess, old, and unimportant drops without disrupting normal gameplay.

✅ Supports NeoForge 21.1.215, Youer 1.21.1, AsyncYouer-1.21.1
⚙️ Designed for Create-based and heavily modded survival servers
💾 Low overhead, deterministic cleanup cycles

---

⚙️ Configuration (for server owners)

Configuration file:

config/smart_item_deleter_v2-common.toml

Option	Type	Default	Description
entityCountThreshold	int	200	Number of dropped item entities required before cleanup activates.
minItemAgeMs	long	15000	Minimum age (in milliseconds) before an item becomes eligible for deletion. Prevents immediate removal of new drops.
scanIntervalTicks	int	20	How often (in ticks) the system scans the world for items (20 ticks = 1 second).
scanJitterEnabled	boolean	true	Adds small random offset (±scanJitterTicks) to interval to reduce server tick spikes when multiple mods act simultaneously.
scanJitterTicks	int	2	Maximum jitter added/subtracted from each cleanup cycle’s timing.
consoleDebugLogging	boolean	true	When false, suppresses cleanup summary messages in the server console.
deletePercentage	int	90	Percentage of eligible items to delete each cycle (0–100). Protects the newest items even when threshold is exceeded.
whitelistMode	boolean	false	Toggles whitelist (true) or blacklist (false) filtering behavior.
filteredItems	list	[]	Accepts exact item IDs (minecraft:stone), tag references (#forge:ingots), or wildcard globs with */? (e.g., minecraft:*, minecraft:oak*) that define which items are protected (blacklist) or targeted (whitelist).

Example:

entityCountThreshold = 250
minItemAgeMs = 15000
scanIntervalTicks = 20
deletePercentage = 80
whitelistMode = false
filteredItems = ["minecraft:nether_star", "minecraft:diamond"]

Wildcard example

filteredItems = ["minecraft:oak*"]

This configuration means:

• Cleanup runs roughly every second.
• Only starts when >250 dropped items exist.
• Deletes 80% of all items older than 15 seconds (prioritizing the oldest).
• Diamonds and Nether Stars will never be deleted.

---

🧠 Technical Details (for developers and maintainers)

Core Behavior

• Items are tracked in TrackedItemsData, using persistent per-level storage.
• Each item stores:
  • UUID
  • dimension
  • firstSeenMs (time first detected)
  • lastSeenMs (time last confirmed)
• Cleanup only occurs when the total item count exceeds the configured threshold.
• Items are eligible if:
  1. Their age ≥ minItemAgeMs
  2. They pass the current policy filter (blacklist/whitelist mode)
• When protectNamedItems is enabled, items with custom names are ignored entirely — they do not count toward the threshold and are never deleted.

Deletion Logic

• All eligible items are sorted oldest first (ascending by firstSeenMs).
• The number of deletions per cycle is:

  deletions = min(excess_items, eligible_items * (deletePercentage / 100))
  

• This ensures:
  • The server maintains stable tick times.
  • Recent player drops are preserved.
  • Automated machines that constantly spill items are kept clean.

Jitter (scan desynchronization)

• The system uses a randomized interval of:

  nextInterval = scanIntervalTicks ± scanJitterTicks
  

  to avoid simultaneous heavy-tick bursts when multiple mods or systems run periodic updates.

Code Structure

Package	Purpose
core/	Cleanup logic, ticking, filtering, and execution
persist/	Persistent tracking data (SavedData) for per-world storage
config/	Configuration spec and loading
command/	Optional /cleanup admin command for manual triggering

Commands

Command	Description
/cleanup run	Forces a cleanup cycle manually.
/cleanup status	(Planned) Displays tracked item count, eligible items, and current thresholds.
/cleanup config	Changes values in the config on the fly.

---

💡 Future Plans

• Provide in-game feedback via action bar or server console only
• Expose metrics to /cleanup status or a scoreboard-compatible data point

---

📜 License

MIT License — freely usable and modifiable.
Please credit Metl_Play if redistributed.
Would be appreciated if I am mentioned in modpacks, but it's not required.

---

🧩 Credits

• Developer: Metl_Play
• Minecraft: 1.21.1 (NeoForge)
• Mappings: Parchment mappings
• Libraries: NeoForge API, standard Java collections

“It’s not just a cleaner mod — it’s a smarter janitor.” 🧠🧹