How to tune Paper and Spigot settings for better performance
Most Minecraft lag comes from the server doing work nobody will notice: simulating mobs far from any player, ticking enormous numbers of items, or loading chunks nobody is near. Paper and Spigot expose settings that cut that waste. Used carefully they give a large improvement for no cost. Used carelessly they break farms and gameplay. This guide covers the settings that matter, what they do, and how to change them safely.
Measure first
Do not tune blind. Install the spark profiler and run /spark profiler start, play normally for a few minutes, then /spark profiler stop and open the link it gives you. It shows where the time goes. Without that, you are guessing, and you may tighten a setting that was never the problem. Understanding TPS and MSPT explains the numbers.
Where the settings live
Different files control different layers, and the layout changes between versions:
| File | Controls |
|---|---|
server.properties | Core vanilla settings, such as view distance |
bukkit.yml | Spawn limits and some world settings |
spigot.yml | Entity activation ranges, merging, view distance overrides |
config/paper-global.yml | Paper settings for the whole server |
config/paper-world-defaults.yml | Paper settings that apply per world |
Older Paper versions used a single paper.yml instead of the two files under config. Look at what your version has, and rely on the comments in the files rather than on setting names copied from an old guide.
Changes that are usually safe and effective
1. Lower view and simulation distance. In server.properties, view distance controls how far players see, and simulation distance controls how far things actually tick. The default for both is 10. Try 8 for view and 6 for simulation on a busy server. This is the biggest single win.
2. Entity activation range. In spigot.yml, entities beyond a certain distance from a player run at reduced rate. The defaults are generous, and lowering them saves CPU. Typical defaults are 32 blocks for animals, monsters and villagers, 48 for raiders, and 16 for water creatures and miscellaneous entities. Dropping them a little helps, but very low values make distant mob farms stop working.
3. Merge items and experience. In spigot.yml, nearby dropped items and experience orbs combine into one. The defaults are around 2.5 blocks for items and 3 for experience. Raising them slightly cuts the number of entities after a big farm or explosion.
4. Per-player mob spawning. Paper can spread mob caps fairly across players, so one player cannot use up the whole cap. This is on by default in recent versions and is worth keeping on.
5. Spawn limits. In bukkit.yml, lower the number of mobs that can exist per category, per player. Monsters at around 50 instead of 70 is a common choice. Do not go so low that spawning feels empty.
6. Chunk saving. Paper limits how many chunks it saves per tick, which smooths out the autosave spikes that cause stutters. The default is sensible, so leave it unless the profiler points at saving.
Things to be careful with
- Hopper and redstone settings. Options that change hopper behaviour can break item sorters and farms. Test with the people who built them.
- Alternative item despawn rates. Faster despawn reduces lag, but can annoy players who leave items on the ground.
- Explosion optimisations. Useful for TNT-heavy servers, but they can change how explosions behave.
- Copying a config from a popular guide. A file tuned for a 200-player minigame server can hurt a small survival server. Change one thing at a time.
How to change a setting safely
- Take a backup, or at least copy the config file.
- Change one setting.
- Restart the server so the change is certain to apply.
- Test it in the situation that was slow, for example the farm or the busy spawn.
- Check the profiler or tick rate again. If it did not help, put it back.
Keep a note of every change and the date. Months later, when something feels wrong, that list is invaluable.
When settings are not enough
If the profiler shows one plugin using most of the time, the fix is that plugin's own configuration, or replacing it. If the server is simply too small for its players, a bigger plan is the honest answer. Compare the symptoms against How to fix server lag and Minecraft server out of memory before you pay for more.
Still stuck? Open a ticket on Discord - run /ticket in any channel, pick a department, and include your Server ID or Invoice ID so we can jump straight in.