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 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

⚙️ 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)

# 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

</details>

## 📈 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](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!*