TurboClean ⚡

Ultra-fast performance optimization plugin for Minecraft Paper servers

🚀 Features

⚡ Lightning-Fast Performance

• Instant cleanup - Operations complete in milliseconds
• Ultra-lightweight - Minimal resource usage
• Async processing - Non-blocking operations with thread safety
• Smart caching - Optimized data access
• 2x Performance Boost - Dramatically improves server speed
• Network optimization - Reduces packet spam and network lag

🧹 Ultra-Smart Cleanup System

• Entity management - Remove lag-causing entities (items, arrows, experience orbs, TNT, fireworks, minecarts, boats, armor stands)
• Memory optimization - Automatic garbage collection and RAM management
• Chunk optimization - Unload unused chunks to save memory
• CPU optimization - Limit AI processing and optimize redstone/hoppers
• Monster cleanup - Remove excessive mobs that cause lag
• Network cleanup - Batched entity removal to reduce network load

⚙️ Flexible Configuration

• Command-based settings - /turboclean settings <setting> <value>
• YAML configuration - Edit config.yml for detailed customization
• Live reload - Update settings without server restart
• Validation - Automatic config validation and correction
• Smart defaults - Optimized for all server sizes (1.20+)

📊 Advanced Monitoring

• Real-time TPS monitoring - Track server performance
• Memory usage alerts - Get notified of high memory usage
• Performance thresholds - Automatic cleanup when needed
• Visual stats dashboard - ASCII graphs showing RAM, CPU, Disk, Network
• Historical data tracking - See performance trends over time

🎯 Smart Automation

• Auto-cleanup intervals - Configurable cleanup schedules
• Emergency cleanup - Automatic cleanup during performance drops
• Player-aware - Keep entities near players, remove distant ones
• Named entity protection - Exclude named entities from cleanup

📋 Requirements

• Minecraft Version: 1.20+ (Paper/Purpur/Folia) - FULLY SUPPORTED
• Java Version: 17 or higher (supports Java 21)
• Server Software: Paper MC (or forks like Purpur, Folia)
• Compatibility: Works on all server types (low-end, medium-end, high-end)

📥 Installation

1. Download the latest TurboClean.jar from Releases
2. Place the jar file in your server's plugins folder
3. Restart your server
4. Configure the plugin in plugins/TurboClean/config.yml
5. Use /turboclean reload to apply changes

🎮 Commands

Command	Description	Permission
/turboclean clean	Perform full cleanup	turboclean.use
/turboclean quick	Quick entity cleanup	turboclean.use
/turboclean network	Network-optimized cleanup	turboclean.use
/turboclean stats	Show performance stats with graphs	turboclean.use
/turboclean reload	Reload configuration	turboclean.admin
/turboclean settings <setting> <value>	Update settings	turboclean.admin

Command Examples

# Perform a full cleanup
/turboclean clean

# Quick cleanup for immediate performance boost
/turboclean quick

# Network-optimized cleanup (reduces lag from packets)
/turboclean network

# Check server performance with cool ASCII graphs
/turboclean stats

# Update cleanup interval to 2 minutes (balanced)
/turboclean settings auto-cleanup.interval 120

# Enable smart entity cleanup
/turboclean settings entities.enabled true
/turboclean settings entities.player-distance 32

🛡️ Permissions

Permission	Description	Default
turboclean.*	All permissions	OP
turboclean.use	Basic usage	OP
turboclean.admin	Admin commands	OP
turboclean.notify	Receive notifications	OP

⚙️ Configuration

Quick Settings via Commands

# Essential settings you can change via commands:
/turboclean settings auto-cleanup.enabled true
/turboclean settings auto-cleanup.interval 60
/turboclean settings entities.enabled true
/turboclean settings memory.enabled true
/turboclean settings monitoring.enabled true

Configuration File (config.yml)

Click to view full configuration

# TurboClean Configuration
general:
  enabled: true
  debug: false

auto-cleanup:
  enabled: true
  interval: 120  # 2 minutes for balanced performance
  cleanup-on-start: true
  cleanup-on-save: true

entities:
  enabled: true
  max-per-chunk: 20  # Smart limit
  cleanup-types:
    - "DROPPED_ITEM"
    - "ARROW"
    - "EXPERIENCE_ORB"
    - "PRIMED_TNT"
    - "FIREWORK"
    - "ITEM_FRAME"
    - "ARMOR_STAND"
    - "MINECART"
    - "BOAT"
    - "FALLING_BLOCK"
  exclude-named: true
  player-distance: 32  # Optimized distance

memory:
  enabled: true
  force-gc: true
  gc-interval: 300
  cleanup-threshold: 70  # Smart threshold
  clear-unused-chunks: true

# Network optimization for reduced lag
advanced:
  network-optimization:
    batch-packets: true
    batch-size: 50
    batch-delay: 1

monitoring:
  enabled: true
  tps-alert-threshold: 18.0
  memory-alert-threshold: 90

📈 Performance Impact

Before TurboClean

• ❌ 200+ entities causing lag
• ❌ 90%+ memory usage
• ❌ 15-17 TPS during peak hours
• ❌ Frequent lag spikes

After TurboClean

• ✅ Entities kept under control
• ✅ 60-70% memory usage
• ✅ Stable 19-20 TPS
• ✅ Smooth gameplay experience

🔧 Advanced Features

Smart Entity Management

• Distance-based cleanup - Only removes entities far from players
• Type-specific filtering - Choose exactly which entities to clean
• NBT preservation - Keeps entities with custom data
• Chunk-based limits - Prevent entity overload per chunk

Memory Optimization

• Intelligent GC - Smart garbage collection timing
• Chunk management - Automatic unused chunk unloading
• Memory monitoring - Real-time usage tracking
• Emergency cleanup - Automatic cleanup at high memory usage

CPU Optimization

• AI limiting - Reduce entity AI processing load
• Redstone optimization - Optimize redstone calculations
• Hopper optimization - Improve hopper performance
• Async processing - Non-blocking operations

📊 Monitoring & Alerts

TurboClean provides comprehensive monitoring:

• TPS Monitoring - Real-time server tick rate tracking
• Memory Alerts - Notifications when memory usage is high
• Performance Thresholds - Automatic actions based on performance
• Visual Dashboard - Cool ASCII graphs and charts
• Historical Trends - Sparkline graphs showing performance over time

🎨 Cool Visual Stats Dashboard

Run /turboclean stats to see a beautiful ASCII dashboard with:

╭─────────────────────────────────────────╮
│           TURBOCLEAN STATS              │
├─────────────────────────────────────────┤
│ RAM Usage:                              │
│ ████████████████████░ 85% (3.2GB/4GB)  │
│ Trend: ▁▂▃▄▅▆▇█▇▆▅▄▃▂▁ (15min history) │
├─────────────────────────────────────────┤
│ CPU & Performance:                      │
│ ██████████████░░░░░░ 70% CPU Usage      │
│ 19.8 TPS (1,247 entities)              │
│ TPS Trend: ▇▇▆▅▄▅▆▇▇█                   │
├─────────────────────────────────────────┤
│ Disk Storage:                           │
│ ████████████░░░░░░░░ 60% (120GB/200GB)  │
├─────────────────────────────────────────┤
│ Network Status:                         │
│ ████████████████████ 100% Optimal      │
│ Packets: Optimized • Lag: Minimal      │
├─────────────────────────────────────────┤
│ Overall Status: EXCELLENT               │
╰─────────────────────────────────────────╯

• Colorized bars - Green/Yellow/Orange/Red based on usage
• Real-time data - Live RAM, CPU, Disk, and Network status
• Mini graphs - Sparkline charts showing trends
• Performance tips - Automatic suggestions when needed

🎯 Use Cases

Low-End Servers (Limited RAM/CPU)

• Set cleanup interval to 60-90 seconds
• Enable network-optimized cleanup
• Use memory threshold of 60-70%
• Enable all optimizations
• Use /turboclean network command regularly

High-End Servers (Dedicated Hardware)

• Set cleanup interval to 120-180 seconds
• Enable standard cleanup with monitoring
• Use memory threshold of 75-85%
• Focus on entity management
• Use /turboclean clean for comprehensive cleanup

Medium-End Servers (VPS/Shared)

• Set cleanup interval to 90-120 seconds
• Balance between network and quick cleanup
• Use memory threshold of 70-80%
• Enable smart monitoring
• Use /turboclean quick for regular maintenance

🔧 Troubleshooting

High Memory Usage

1. Lower memory.cleanup-threshold to 70-80
2. Reduce auto-cleanup.interval to 180 seconds
3. Enable memory.clear-unused-chunks
4. Check entities.max-per-chunk setting

Low TPS

1. Enable turboclean quick command regularly
2. Lower entities.player-distance to 32-48
3. Increase cleanup frequency
4. Enable CPU optimizations

Plugin Not Working

1. Check console for errors
2. Verify Paper/Purpur server (not Spigot)
3. Ensure Java 17+ is installed
4. Check permissions are set correctly

Commands Not Responding

1. Use /turboclean settings instead of /turboclean:settings
2. Make sure you have proper permissions
3. Check if plugin loaded correctly with /plugins
4. Restart server if needed

Thread Safety Errors

1. Plugin now runs all cleanup on main thread
2. No more "Chunk getEntities call" async errors
3. All operations are thread-safe
4. Improved stability and performance

🤝 Support

• Discord: Join our Discord
• Issues: GitHub Issues
• Wiki: Documentation Wiki

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💖 Support the Project

If TurboClean helps your server run smoothly, consider:

• ⭐ Starring the project on GitHub
• 💬 Leaving a review on Modrinth
• 🔄 Sharing with other server owners
• 💝 Supporting development

---

Made with ❤️ for the Minecraft community

TurboClean - Because performance matters!