Optimizing a Minecraft server

A Minecraft server usually lags for three reasons: generating new chunks, a large number of mobs and other entities, and heavy plugins. This article shows how to find the cause and what to change. The settings from spigot.yml and paper-world-defaults.yml work on the Paper and Purpur engines.

Find the cause

Before you change any settings, check what's putting load on the server. The spark profiler does this. It's built into Paper 1.21 and newer, and on older versions you can install it as a plugin from the spark website (opens in a new tab). The client panel is available in Polish only, so its labels are given in Polish with a translation.

1. Start the profiler

   In the Konsola (Console) tab, type /spark profiler start while players are online and the lag is happening. It collects data in the background and doesn't affect gameplay.

2. Open the live view

   Type /spark profiler open. A link to a report that updates live appears in the console, and the profiler keeps running. The report shows which plugins, mobs or chunks take up the most time.

3. Stop the profiler

   Once you've found the cause, type /spark profiler stop. The profiler saves a final report and gives you a link to it.

Check the current performance with the /tps command. A result of 20 means the server runs smoothly, and anything lower means lag.

Pre-generate the map

Generating new terrain is the heaviest work a server does. Set a world border and generate the world in advance, before players join. Use the Chunky (opens in a new tab) plugin for this:

/worldborder set 10000
/chunky radius 5000
/chunky start

A 10000-block border is a 5000-block radius from the centre of the map. Generation takes anywhere from several minutes to a few hours, and the progress shows in the console. It's best to run it when nobody is playing.

View distance

Two settings in server.properties have the biggest impact on performance:

view-distance=8
simulation-distance=6

• view-distance is the number of chunks a player sees around them.
• simulation-distance is the number of chunks in which mobs, crops and redstone are active.

Both default to 10. Lowering them to 8 and 6 usually goes unnoticed by players and takes a lot of load off the server.

Engine settings

The values below are a proven starting point. Change them gradually and restart the server after each change.

bukkit.yml

spawn-limits caps the number of mobs of each type per player, and ticks-per sets how many ticks pass between spawn attempts.

spawn-limits:
  monsters: 35
  animals: 10
  water-animals: 5
  water-ambient: 10
  water-underground-creature: 3
  axolotls: 5
  ambient: 3
ticks-per:
  animal-spawns: 400
  monster-spawns: 10
  water-spawns: 400
  water-ambient-spawns: 400
  water-underground-creature-spawns: 400
  axolotl-spawns: 400
  ambient-spawns: 400
  autosave: 6000

spigot.yml

You'll find these settings in the world-settings → default section.

entity-activation-range:
  animals: 16
  monsters: 24
  raiders: 48
  misc: 8
  water: 8
  villagers: 16
  flying-monsters: 48
tick-inactive-villagers: false
nerf-spawner-mobs: true
merge-radius:
  item: 4.0
  exp: 6.0
arrow-despawn-rate: 300

In the same file, in the settings section, set save-user-cache-on-stop-only: true. The server then saves its player cache only when it shuts down, not every time someone joins.

paper-world-defaults.yml

This file is in the config folder.

chunks:
  max-auto-save-chunks-per-tick: 8
  prevent-moving-into-unloaded-chunks: true
collisions:
  max-entity-collisions: 2
entities:
  armor-stands:
    tick: false
environment:
  optimize-explosions: true
tick-rates:
  grass-spread: 4

Common problems