Paper server optimization: the settings that actually matter

Copy-pasting an optimization guide is how servers end up with settings nobody understands and mobs that never spawn. These are the six settings worth changing, what each one costs, and how the right value differs between a survival SMP and a skyblock server.

First, where the files actually are

Paper split its configuration in 1.19. If a guide tells you to edit paper.yml, it was written for an older version:

Back up before you change anything, and change one setting at a time. Six changes at once means you cannot tell which one helped and which one broke your iron farm.

1. view-distance and simulation-distance

These are the highest-impact settings on the list, and the most misunderstood — because they are two different things.

• view-distance — how far chunks are sent to players. Costs bandwidth and memory.
• simulation-distance — how far the world is ticked. Costs CPU.

Simulation distance is where the CPU goes. You can keep a generous view distance so the world looks good, while ticking a much smaller radius:

view-distance=10
simulation-distance=6

Players see plenty of terrain; the server only simulates what is near them. On a busy survival server this alone can pull several milliseconds off every tick.

2. mob-spawn-range

In spigot.yml, per world. It controls how far from each player mobs spawn — and it multiplies with your player count.

At range 8 with 100 players, you are spawning mobs across an enormous combined area. Drop it to 6 and the spawnable area per player falls by nearly half.

3. Entity activation and tracking ranges

Also spigot.yml. Activation range decides how far from a player an entity keeps ticking. Lower it and distant mobs effectively freeze until someone approaches.

entity-activation-range:
  animals: 16
  monsters: 24
  raiders: 48
  misc: 8

Be careful with monsters. Set it too low and mob grinders stop working, which generates more complaints than the lag did. 24 is a safe compromise on most survival servers.

4. merge-radius

Dropped items are individually cheap and collectively expensive — every item checks whether it should merge with nearby items, every tick. A farm that overflows produces thousands.

merge-radius:
  item: 4.0
  exp: 6.0

Raising the item radius from the default 2.5 to 4.0 meaningfully cuts entity counts around farms. The visible cost is that items snap together from slightly further away.

5. Hopper settings

Hoppers are the setting most often changed for no reason. ticks-per.hopper-transfer only matters if you actually have thousands of hoppers.

Check first. If your server has a few hundred hoppers, changing this does nothing except break timing-sensitive contraptions. If you have tens of thousands, it matters a lot.

6. max-auto-save-chunks-per-tick

In paper-global.yml. Every so often the server writes modified chunks to disk. Do too many at once and you get a periodic spike — one tick that takes 400 ms while everything else is fine.

chunk-system:
  io-threads: 2
max-auto-save-chunks-per-tick: 12

Lowering it spreads the same work over more ticks. If your MSPT graph has regular tall spikes that do not line up with garbage collection, this is a good suspect.

What not to do

• Do not paste an entire config from a guide. You inherit settings tuned for someone else's server and lose your own.
• Do not set entity limits so low that farms break. Players will notice broken farms long before they notice 2 ms of tick time.
• Do not change anything you cannot measure. If you cannot see the before and after, you are guessing.
• Do not disable Paper's optimizations to "fix" a bug. Almost always the bug is elsewhere.

Measure, then change

Every value above depends on your server. The way to use this list is to find out where your milliseconds are actually going first — see the diagnostic checklist — and then change only the settings that touch your real bottleneck.

unlag.me reads these files and recommends values based on what it measured on your server, with a diff and a one-click revert, so you are not editing YAML on faith.