WorldListTrashCan

WorldListTrashCan is a cleanup and trash-can plugin for Bukkit, Spigot, Paper, and Folia/Luminol.

It keeps the legacy world trash can, public trash can, personal trash can, item blacklist, entity cleanup, dense entity cleanup, drop protection, and cleanup notifications. The refactored version also addresses the legacy configuration sprawl, Folia lag, forced chunk loading, accidental item loss, and inconsistent cross-version behavior.

Changes administrators will notice

New user-facing features

Feature	Legacy version	Refactored version
Public trash-can layout	Fixed layout	Configurable 1-6 row content area, page buttons, background, and display items
Public trash-can buttons	Fixed material and position	Material fallbacks, CustomModelData, name, Lore, and replacement items
Smaller public trash-can capacity	Items could become inaccessible	A read-only overflow page keeps items visible and retrievable instead of silently losing them
Public trash-can actions	Only fixed button behavior	Supports [console], [command], [message], and PlaceholderAPI variables
Personal trash-can notifications	Incomplete single-item and batch messages	Individual notifications for single items and grouped notifications for cleanup batches, showing up to 3 types by default
Cleanup guards	Cleanup ran when its timer elapsed	Automatic cleanup can be skipped when online-player or entity-count thresholds are not met
Manual cleanup	One fixed execution mode	/wtc clear true/false chooses whether cleanup guards are ignored
Cleanup status	Mainly exposed through countdown variables	/wtc stats shows the latest recovery, deletion, entity, inventory, and remaining-time status
Console details	Mostly showed totals	Shows the top 10 entity categories with display name, type, actual count, and remainder count
Entity protection	Limited protection rules	Protects saddled entities and Bukkit Tameable owners while avoiding shooter/source/drop-owner false positives
Direct deletion by world	No dedicated setting	Selected worlds can delete items directly without routing them to any trash can
Moving-item protection	Not available	Cleanup can skip moving dropped items; disabled by default
Filled shulker-box item protection	Not available	Cleanup can skip dropped item stacks containing filled shulker boxes; disabled by default

This table lists changes directly visible to server administrators and does not count internal implementation details as separate features.

Compatibility and stability improvements

• WorldListTrashCan-universal.jar runs across supported server versions, including Folia/Luminol; lightweight version-specific JARs are also available.
• Compatible implementations are provided across the 1.12.2-1.21.x version line. RGB is supported on 1.16.5 and newer, with automatic downgrade on older versions. Legacy &a and &c color codes remain supported.
• Folia/Luminol uses region-safe, segmented cleanup tasks instead of running ordinary Bukkit repeating tasks in a Folia environment.
• Unloaded chunks are not force-loaded by default for world trash cans, preventing sudden cleanup lag spikes.
• Player-drop ownership is stored on the dropped entity rather than inside the item stack, so normal item stacking is not affected.
• Legacy configurations are detected and isolated in old-version-config instead of being used directly by the new implementation.
• Missing default configuration entries are restored, and default configuration files include Chinese comments.
• bStats is built in and has no plugin-level enable/disable switch; the plugin version is 7.0.0.

Estimated performance improvements

The figures below are estimates based on old and new execution paths, default batch settings, and entity-count models. They are not a Spark benchmark guarantee. Actual results depend on loaded chunks, entity counts, player activity, and the server core.

Scenario	Estimated improvement
Periodic dense-entity checks across 1,000 loaded chunks	About 96% less checking pressure
Periodic dense-entity checks across 4,096 loaded chunks	About 96.6% less checking pressure
5,000 entities with 20 restricted entities generated per second	About 99.98% less repeated traversal pressure
Automatic cleanup with no players online	Skipped directly; near 100% reduction for that cycle
World trash can in an unloaded chunk	Plugin-initiated forced loading reduced by 100%; defaults to skip and fallback routing
Folia peak dispatch for a 4,096-chunk cycle	Theoretical instantaneous dispatch peak reduced by about 98.4%

Overall estimate

• Servers using only ordinary scheduled cleanup: typically about 0%-30% improvement in the related path.
• Large servers with dense-entity limits enabled: estimated related main-thread pressure reduction of 80%-99%.
• Servers previously affected by synchronous world-trash-can chunk loading: estimated single-cleanup lag-spike reduction of 90%+.
• The refactored version adds a bounded entity index and candidate queue; estimated additional memory usage is about 5-10MB, with limits to prevent unbounded growth.

These percentages describe estimated reduction for the specified scenario, not a fixed reduction for the entire plugin. For server-specific numbers, compare the legacy and refactored versions with Spark or server monitoring under the same map, player count, and entity count.

Recommended configuration

The new protections are disabled by default and do not change legacy behavior until enabled:

# cleanup.yml
guards:
  # Skip automatic cleanup when online players are below this value.
  min-online-players: 1
  # Skip automatic cleanup when the target entity count is below this value.
  min-total-entities: 150

# Disabled by default. When enabled, moving dropped items are skipped.
moving-items:
  enabled: false
  minimum-speed: 0.01

# Disabled by default. When enabled, dropped item stacks containing filled
# shulker boxes are skipped.
filled-shulker-boxes:
  enabled: false

“Shulker-box items” means an ItemStack carried by a dropped-item entity, not a shulker-box block placed in the world. When enabled, dropped filled shulker boxes remain on the ground; empty shulker boxes are still cleaned normally.

Common commands

/wtc help                 Show help
/wtc reload               Reload configuration
/wtc stats                Show the latest cleanup status
/wtc clear true           Run manual cleanup and ignore cleanup guards
/wtc clear false          Run manual cleanup while respecting cleanup guards

The formal long command is /worldlisttrashcan, with /wtc as its short alias. Permissions use the WorldListTrashCan.* namespace.

Which JAR should I use?

• For seamless switching between supported server types and versions, use WorldListTrashCan-universal.jar.
• For a smaller package and fewer runtime branches, use the lightweight JAR matching the server version.
• Put only one WorldListTrashCan JAR in a server's plugins directory. Do not install both the universal and lightweight JARs together.