ServerOptimizer

🧩 What is ServerOptimizer?

ServerOptimizer is a lightweight, high-performance Paper/Spigot plugin built for Minecraft 1.20.4+ that surgically targets the three most common causes of server lag:

All heavy computation runs asynchronously — the main thread stays at a clean 20 TPS.

✨ Features

⚙️ Entity Optimizer

• 🔍 Periodic async entity scans across all loaded chunks
• ✂️ Culls excess entities when a chunk exceeds your configured cap
• 🧲 Item merging — stacks nearby dropped items instead of deleting them
• 🏷️ Named entity protection — entities with name tags are never removed
• 🚫 Spawn-time gating — cancels spawns before the entity is created (cheaper than culling)
• 🌍 Per-world enable/disable support

🗺️ Chunk Optimizer

• ⏱️ Idle chunk unloading — automatically requests unload after configurable inactivity
• 📡 Player-radius tracking — keeps only chunks near active players loaded
• 📊 Async load rate limiting — prevents chunk-generation spam from overwhelming the server
• 🪶 Uses WeakHashMap so unloaded chunk references are garbage-collected automatically

🪣 Hopper Optimizer

• 🐌 Configurable hopper tick rate — slow down hoppers from vanilla 8-tick to your preference
• 😴 Lazy mode — skips hoppers with empty source inventories entirely
• 📦 Per-hopper transfer rate tracked with ConcurrentHashMap
• 🗑️ Auto-purges stale hopper entries every 5 minutes — zero memory leaks

🛡️ Plugin Compatibility

• ✅ WorldGuard — entity listener uses HIGH priority, after WorldGuard's region checks
• ✅ EssentialsX — softdepend declared, no hard conflicts
• ✅ All listeners use ignoreCancelled = true to skip already-processed events

🔧 Developer Quality

• 🔁 Hot-reload via /sopt reload — no server restart needed
• 🧵 Thread-safe throughout (ConcurrentHashMap, WeakHashMap, AtomicInteger)
• 📝 Full config.yml with comments on every setting
• 📋 Tab-completion on all commands

📋 Commands

🔑 Permissions

⚙️ Configuration

# ─── Entity Optimization ───────────────────────────
entity-optimizer:
  enabled: true
  scan-interval-ticks: 100        # How often to scan (20 ticks = 1 second)
  max-entities-per-chunk: 50      # Cull threshold per chunk
  tracked-types:
    - ZOMBIE
    - SKELETON
    - CREEPER
    - SPIDER
    - ENDERMAN
    - VILLAGER
    - DROPPED_ITEM
  cull-strategy: REMOVE           # REMOVE or MERGE (items only)
  protect-named-entities: true    # Never cull named/tagged entities
  disabled-worlds:
    - creative_world

# ─── Chunk Loading Optimization ────────────────────
chunk-optimizer:
  enabled: true
  idle-chunk-unload-seconds: 300  # Unload after 5 min of inactivity
  keep-loaded-radius: 4           # Chunks to keep around each player
  max-async-loads-per-second: 10  # Rate-limit chunk generation

# ─── Hopper Optimization ───────────────────────────
hopper-optimizer:
  enabled: true
  hopper-tick-rate: 16            # 8 = vanilla, 16 = recommended, 40 = aggressive
  lazy-hoppers: true              # Skip hoppers with empty sources
  max-transfer-per-tick: 1

# ─── General ───────────────────────────────────────
general:
  debug-logging: false
  message-prefix: '&8[&bServerOptimizer&8]&r '
  metrics: true

🚀 Installation

1. Download ServerOptimizer-1.0.0.jar
2. Drop it into your /plugins/ folder
3. Start or restart your server
4. Edit plugins/ServerOptimizer/config.yml
5. Run /sopt reload to apply changes

⚠️ Requires Paper 1.20.4+ — Spigot is supported but Paper unlocks async chunk APIs and better scheduling.

🧠 Performance Architecture

Main Thread (20 TPS — never blocked)
│
├── EntityListener        → Cancels over-limit spawns instantly (O(1) map lookup)
├── HopperListener        → Throttles transfers via timestamp gate (O(1))
└── ChunkListener         → Records load times into WeakHashMap (O(1))

Async Thread Pool (Paper Scheduler)
│
├── Entity Scan Task      → Iterates chunks, builds removal list
├── Chunk Cleanup Task    → Finds idle chunks, requests unload on main thread
└── Hopper Cleanup Task   → Purges stale ConcurrentHashMap entries

Main Thread (dispatched back)
│
├── entity.remove()       → Thread-safe mutation
└── world.unloadChunkRequest() → Thread-safe mutation

Rule: Read async. Write sync. Never mutate Bukkit world state off the main thread.

📊 Benchmark Impact

Tested on a Paper 1.20.4 server with 20 players, 800+ entities, and 200 active hoppers.

🤝 Compatibility

💬 Support & Contact

📜 License

This project is licensed under the MIT License — free to use, modify, and distribute with attribution.