Minecraft Server Optimization: Tuning Configuration Files for Maximum TPS

Every Minecraft server administrator eventually reaches the same roadblock: lag. You rent a high-end server node, install your favorite plugins, and start inviting players. But as soon as the player count grows past 20 or 30, the server TPS begins to crawl.

While many admins immediately blame hardware, the real culprit is usually **un-optimized configuration files**. In this guide, we'll walk through the most important performance configurations in Spigot, Paper, and CircuitBreaker to lock your server at a solid 20 TPS.

1. The Foundation: spigot.yml Tweaks

The standard Spigot settings are configured for single-player style vanilla mechanics, which is highly inefficient for multiplayer networks. Open your `spigot.yml` and modify these keys:

• `entity-activation-range`: This governs how close players must be to an entity for its AI to tick. Reduce `animals` to `16`, `monsters` to `24`, and `misc` to `4`. This saves massive CPU ticks on idle entities.
• `merge-radius`: Increase the merge radius for items (`item: 3.5`) and exp (`exp: 4.0`). This forces items lying on the ground to merge into a single item entity, reducing the server's render task load.
• `max-tick-time`: Set both `tile` and `entity` to `1000`. This prevents the server from locking up or freezing if an entity lag spike occurs.

2. The Engine: paper.yml Performance Configurations

PaperMC introduces highly effective settings to mitigate lag. Make these modifications in `config/paper-world-defaults.yml`:

• `despawn-ranges`: Adjust monster despawn ranges. Set `soft` to `28` and `hard` to `96` to quickly clean up mobs in unloaded chunks.
• `max-auto-save-chunks-per-tick`: Set this to `6`. This distributes chunk auto-saving tasks evenly across server ticks, removing the "autosave lag spike" every 5 minutes.
• `chunks.prevent-moving-into-unloaded-chunks`: Set this to `true`. This prevents players (especially those flying with elytra) from generating huge loads by loading new chunks faster than the server can process.

3. The Shield: CircuitBreaker Anti-Lag Tuning

Tuning your core server configs reduces general resource usage, but it won't stop malicious or accidental lag machines. That is where **CircuitBreaker** comes in. In your `CircuitBreaker/config.yml`:

# Physics lag protection threshold
lag-threshold: 25000       # Trigger warning at 25,000 physics updates/sec
strike-limit: 3            # Allow 3 soft resets before freezing
freeze-duration-ticks: 6000 # Freeze chunk for 5 minutes (6000 ticks)

# Entity Culling (Optional)
entity-culling:
  enabled: true
  scan-interval-seconds: 15
  threshold: 400           # Cull chunk if it exceeds 400 entities
                

By keeping the physics threshold at `25,000` events per second, you ensure that normal player redstone clocks function perfectly, while automatically capturing and freezing massive repeating observer or piston chains within seconds.

Summary

Optimization is not a one-time step. Keep your entity activation ranges narrow, pre-generate your world map using tools like **Chunky**, and run **CircuitBreaker** to protect your physics threads from sudden griefing attacks. Together, these settings ensure a lag-free environment that keeps your players online.