Intelligent item management plugin for Paper Minecraft 1.20+ servers
VoidCleaner automatically and intelligently cleans up dropped items, projectiles, vehicles, and mobs from your server, storing them in a special "void" (storage) where players can retrieve them. The system automatically adjusts cleanup aggression based on server load (TPS).
- Healthy TPS → Normal cleanup (items, projectiles, empty vehicles)
- Low TPS → Aggressive cleanup (+ mobs)
- Critical TPS → Full cleanup (almost everything)
- Separate void for each world group (Overworld, Nether+End, Custom)
- Items automatically route to the correct void
- Flexible world-to-void mapping in config
/void worldclean— Cleans unloaded chunks without lag- Background scanning, main-thread removal
- Safe for all operations
- When player A takes an item, player B sees it instantly
- GUI automatically updates for all viewers
- No duplicate or ghost items
- Automatically merges items of the same type
- Respects max stack size (boats=1, iron=64)
- Reduces void slots needed
- Protects tamed animals (default)
- Protects named entities (default)
- Blacklists for each cleanup mode
- Advanced conditions (+empty, !tamed, +adult, etc.)
- Download
.jarfrom GitHub or Modrinth - Place in
plugins/folder - Restart server
- Edit
plugins/VoidCleaner/config.yml(auto-generated) - Restart server again
See INSTALLATION.md for detailed instructions.
/void
Opens the void GUI to retrieve items (if void is open).
/void open # Manually open void
/void close # Manually close void
/void clean # Normal cleanup
/void fullclean # Aggressive cleanup (removes mobs)
/void worldclean # Async world cleanup (unloaded chunks)
| Permission | Default | Description |
|---|---|---|
voidcleaner.use |
true | Access to /void GUI |
voidcleaner.admin |
op | All admin commands |
voidcleaner.open |
op | /void open |
voidcleaner.close |
op | /void close |
voidcleaner.clean |
op | /void clean |
voidcleaner.fullclean |
op | /void fullclean |
voidcleaner.worldclean |
op | /void worldclean |
/lp user <player> permission set voidcleaner.use true
/lp group admin permission set voidcleaner.admin true
world-voids:
overworld:
- world
nether-end:
- world_nether
- world_the_end
default-void: overworldItems from each world go to their mapped void.
max-void-storage: 10000 # Max items per void (0 = unlimited)cleanup-interval-seconds: 600 # Cleanup every 10 minutes
enable-auto-cleanup: trueRecommendations:
- Small server (2-4 players): 300s (5 min)
- Medium server (5-20 players): 600s (10 min)
- Large server (20+ players): 1200s (20 min)
low-tps-threshold: 12.0 # Trigger aggressive cleanup
critical-tps-threshold: 8.0 # Trigger full cleanup
tps-check-interval-seconds: 30How it works:
- TPS > 12.0 → Normal mode
- TPS 8.0-12.0 → Remove mobs too
- TPS < 8.0 → Full cleanup
void-close-delay-seconds: 120 # Void closes after 2 minutesAfter this time, the void closes and remaining items are deleted forever.
default-clean: # Regular cleanup
- minecraft:item
- minecraft:arrow
- minecraft:oak_boat +empty
high-clean: # Aggressive cleanup
- minecraft:zombie
- minecraft:skeleton
# ... more mobs"minecraft:item" # All items
"minecraft:oak_boat +empty" # Empty boats only
"minecraft:minecart" # All minecarts
"minecraft:wolf !tamed" # Wild wolves only
"minecraft:zombie +adult" # Adult zombies only
| Condition | Meaning |
|---|---|
+empty |
Vehicle without passenger |
!empty |
Vehicle with passenger |
+tamed |
Tamed animal |
!tamed |
Wild animal |
+named |
Has nametag |
!named |
No nametag |
+adult |
Adult |
+baby |
Baby/young |
+hostile |
Hostile mob |
!hostile / +passive |
Peaceful |
+on_ground |
Standing on ground |
default-blacklist: [] # Protected from default cleanup
fullclean-blacklist:
- minecraft:villager # Never removed
- minecraft:iron_golemSee full config.yml for all options.
world-voids:
all:
- world
- world_nether
- world_the_end
max-void-storage: 5000
cleanup-interval-seconds: 300world-voids:
main:
- world
- world_nether
- world_the_end
creative:
- creative_world
max-void-storage: 20000
cleanup-interval-seconds: 600
low-tps-threshold: 12.0enable-auto-cleanup: false
protect-tamed: true
protect-named: trueThen manually run /void worldclean to clean unloaded areas.
Check:
- Are you using Paper 1.20+? (
/version) - Is the JAR in the
plugins/folder? - Do you have Java 17+? (
java -version)
Check:
- Did the plugin load? (Check console for "[VoidCleaner]")
- Do you have
voidcleaner.usepermission? - Restart the server
Check:
- Run
/void fullcleanto force cleanup - Check
void-close-delay-secondsin config - Is
enable-auto-cleanup: true?
Solutions:
- Increase
cleanup-interval-seconds(e.g., 1200) - Increase
tps-check-interval-seconds(e.g., 60) - Reduce rules in
default-clean
See INSTALLATION.md for more solutions.
VoidCleaner is optimized for performance:
- ✅ Async world scanning (no lag)
- ✅ Efficient entity filtering
- ✅ Memory-optimized storage
- ✅ Smart stacking reduces slots
- ✅ Main-thread safe operations
TPS Impact:
- Regular cleanup: < 0.1 TPS drop
- Void open/close: < 0.01 TPS drop
- Player sync: No impact
- Admin GUI for void management
- Particle effects on void open
- Sound effects for notifications
- Bossbar showing void status
- Custom void names per group
- Void statistics and analytics
- Automatic world detection
0.1.0
- Initial release with core functionality.
0.1.1
- Added support for 1.21.x,
- Cleaned code and fixed multi-language comments in code.
- GitHub: https://github.com/Dominos111G/VoidCleaner
- Modrinth: https://modrinth.com/plugin/voidcleaner
- Issues: https://github.com/Dominos111G/VoidCleaner/issues
MIT License - Free to modify and distribute
- INSTALLATION.md - Detailed setup guide
- CONFIGURATION.md - Config options
- CONTRIBUTING.md - Developer guide
- CHANGELOG.md - Version history
Found a bug or want a feature? Open an issue!
Version: 1.0.0
Minecraft: 1.20+
Made with ❤️ for Minecraft Players