Minecraft Paper optimisation: the configs that fix TPS

Paper's defaults are good. That is the first thing to understand before you paste anyone's "optimised configs" into your server: the out-of-the-box values are chosen by people who profile Minecraft for a living, and most of the config packs circulating online are three versions out of date and trade behaviour you care about for tick time you do not need. The wins that are real and large are few, and they are mostly about distance - how far the server sends chunks, how far it ticks them, and how many mobs it keeps alive inside that radius.

This guide covers the five configuration files a Paper server has, what each one owns, and the settings inside them that move tick time measurably. It also names the ones that will cost you a farm, a redstone contraption or a plugin if you change them without reading the consequence.

The five files, and which one owns what#

A Paper server is Bukkit inside Spigot inside Paper, and each layer kept its own configuration. They load in that order, so the later file wins where they overlap.

Any world can override the Paper defaults with its own <world>/paper-world.yml, and spigot.yml has the same idea as world-settings.<name> under world-settings.default. Use that when the Nether needs different numbers from the Overworld, which it usually does not.

Two warnings about following guides, this one included. Paper moves and renames keys between versions - the single paper.yml became the config/ folder in the 1.19 era, and individual settings have shifted since. Always open the file your own server generated and search for the key rather than pasting a block. And unsupported-settings in paper-global.yml is called that for a reason; nothing in this guide touches it.

If you have not read every server.properties key explained, start there, because two of the three largest levers live in that file and not in Paper's.

View distance and simulation distance#

This is the whole game. Everything else in this guide is worth a few percent; these two are worth a factor.

view-distance=8simulation-distance=6

View distance is how many chunks out from each player the server loads, keeps in memory and sends over the network. The area is quadratic, so the cost is not linear in the number: dropping from 10 to 8 removes about a third of the loaded chunks per player, and 10 to 6 removes nearly two thirds. On a server with twenty people spread across the map, that is the difference between 8,400 chunks loaded and 3,000.

Simulation distance, split out from view distance in 1.18, is how far chunks actually tick - mob AI, crop growth, redstone, hoppers, furnaces, water flow. It is the cheaper of the two to reduce because players cannot see it happening. The cost is farms: anything outside the simulation distance of every online player stops running, so an AFK fish farm at simulation-distance=4 will fail in ways your players will report as a bug.

Sensible pairs, by how busy the server is:

• Quiet server, under ten players: view-distance=10, simulation-distance=8. Leave the defaults alone.
• Normal SMP, ten to twenty-five players: view-distance=8, simulation-distance=6.
• Busy server, thirty or more: view-distance=6, simulation-distance=5. Below this, fog and pop-in start to look broken.
• Minigame or lobby server: view-distance=5 or lower, simulation-distance=4. Nobody is farming in a lobby.

Paper can override both per world in spigot.yml, where view-distance and simulation-distance take the value default out of the box. A lobby world set to 4 and a survival world set to 8 on the same server is a legitimate and effective setup.

One related setting: entity-broadcast-range-percentage in server.properties, default 100. It scales how far entities are sent to clients as a percentage of view distance. Dropping it to 75 cuts entity packet traffic noticeably on a crowded server, at the cost of mobs and dropped items appearing later as you approach. It is a bandwidth and client-side win more than a tick-time win.

Mob spawning, which is most of the rest#

After distance, mobs are where the ticks go. A Minecraft server spends a large share of every tick deciding whether to spawn something, then pathfinding what it spawned.

spawn-limits:  monsters: 70  animals: 10  water-animals: 5  water-ambient: 20  water-underground-creature: 5  axolotls: 5  ambient: 15ticks-per:  animal-spawns: 400  monster-spawns: 1  water-spawns: 1  ambient-spawns: 1  autosave: 6000

Those are the defaults. The important thing to know before changing them is that Paper's per-player-mob-spawns is on by default, and it changes what the numbers mean: the limits become per-player rather than per-world. That is a much better system - one player in a cave no longer starves the rest of the map of spawns - but it means monsters: 70 is not a world cap of 70, it is a budget each player carries. On a thirty-player server that is a lot of zombies.

What is worth changing:

• monsters: 70 down to 40 or 50 on a server with more than twenty players. Mob farms will produce less; the tick time drops in proportion.
• ticks-per.monster-spawns: 1 up to 2. This halves how often the spawn attempt runs. It is one of the cheapest wins available and the difference is hard to notice in play.
• ticks-per.autosave: 6000 is five minutes. Leave it unless you are seeing a periodic spike, in which case see the chunk section below rather than lengthening the interval - a longer interval means a bigger hitch and more lost work on a crash.

In spigot.yml, mob-spawn-range defaults to 8 chunks. It should never be larger than your simulation distance, because mobs spawned outside the ticking radius are pointless. Setting it to one less than simulation-distance concentrates spawning where players actually are.

nerf-spawner-mobs: false in spigot.yml turns mobs from spawners into entities with no AI - they exist, they can be damaged and killed, and they do not path or think. On a server full of grinders it is a real saving and it visibly changes how the grinders work, so decide with your players rather than for them.

Finally, entities.spawning.despawn-ranges in paper-world-defaults.yml controls the vanilla soft and hard despawn distances, default 32 and 128 blocks. Lowering the hard range to around 96 removes mobs that no player is near. This one interacts with farm designs that rely on mobs persisting, so test it.

Entity activation and tracking ranges#

These two live in spigot.yml and are constantly confused with each other.

entity-activation-range:  animals: 32  monsters: 32  raiders: 48  misc: 16  water: 16  villagers: 32  flying-monsters: 32entity-tracking-range:  players: 48  animals: 48  monsters: 48  misc: 32  other: 64  display: 128

Activation range is how close a player must be for an entity to tick at all. Outside it, the entity exists but does not move, path or think. Tracking range is how close a player must be to be sent the entity at all - a client-side and bandwidth concern.

Activation range is the one that saves CPU. Dropping animals and monsters to 24, and misc to 12, is a common and safe tune on a busy server. The visible consequence is that mobs "wake up" as you approach rather than being already in motion, which is mostly invisible during play and very obvious if you are watching a mob farm from a distance. Do not lower raiders - raids are supposed to path towards you from a distance, and a low value breaks them.

Tracking range mostly costs bandwidth, not tick time. If your server is fine on CPU but players complain about stutter when a lot of entities are on screen, lowering animals and monsters to 32 helps them more than it helps you.

Two related items in the same file: merge-radius (default item: 2.5, exp: 3.0) controls how aggressively dropped items and experience orbs combine into single entities. Raising item to 4.0 on a server with big farms reduces entity counts meaningfully, and the side effect is that items scattered over a few blocks snap together, which looks slightly odd. And item-despawn-rate: 6000 is five minutes in ticks; alt-item-despawn-rate in paper-world-defaults.yml lets you despawn cobblestone and other junk faster than everything else, which is exactly the right tool for a mining server.

Hoppers, redstone and chunk work#

Hoppers are the single most over-represented lag source in plugin profiles, because every hopper checks for items on a schedule whether or not anything is there.

ticks-per:  hopper-transfer: 8  hopper-check: 1

hopper-check: 1 means every hopper looks for items to pull from the container above it every tick. Setting it to 8, matching the transfer rate, cuts that work by a factor of eight and makes hoppers pull slightly less eagerly. On a server with item-sorting systems this is one of the largest single changes you can make.

In paper-world-defaults.yml, hopper.disable-move-event: true stops Paper firing the Bukkit inventory move event for hopper transfers. It is a large win on a server with many hoppers, and it breaks any plugin that listens for that event - which includes some shop, logging and anti-dupe plugins. Check your plugin list before switching it on.

Redstone has its own implementation setting, misc.redstone-implementation in paper-world-defaults.yml, default vanilla. The alternate-current option is a rewritten dust update algorithm that is dramatically faster on large redstone builds and behaves identically in effectively all real circuits. eigencraft is the older alternative. On a technical server, alternate-current is close to a free win; on a vanilla-purist server, leave it.

Chunk work is the other periodic cost. In paper-world-defaults.yml:

• chunks.max-auto-save-chunks-per-tick defaults to 24. Lowering it to 8 spreads the autosave over more ticks, turning one visible hitch into a smaller, longer background cost. This is the correct fix for "the server stutters every five minutes".
• chunks.entity-per-chunk-save-limit caps how many of a given entity type are saved per chunk. Setting experience_orb, arrow and snowball to something like 50 stops a chunk that accumulated ten thousand orbs from freezing the server when it loads.
• chunks.delay-chunk-unloads-by defaults to 10s and stops chunks being unloaded and reloaded as a player walks back and forth across a boundary. Leave it.

In paper-global.yml, chunk-loading-basic.player-max-chunk-generate-rate is unlimited by default. Setting it to something like 10 chunks per second stops one player in an elytra over fresh terrain from consuming the entire chunk generation budget while everyone else's world stops loading. If new-terrain exploration is a regular complaint, this is the setting. Better still, generate the terrain in advance - world borders and pre-generation covers doing it once with a tool instead of continuously with players.

Anti-xray, and what it costs#

anticheat.anti-xray in paper-world-defaults.yml is off by default. It hides ores from clients so that an x-ray texture pack or mod sees nothing useful.

anticheat:  anti-xray:    enabled: true    engine-mode: 1    max-block-height: 64    update-radius: 2

Engine mode 1 replaces hidden blocks with stone in the packets sent to clients, which is cheap. Engine mode 2 sends fake ores as well, which defeats more sophisticated cheats and costs noticeably more CPU and bandwidth, because chunk packets become much less compressible. max-block-height: 64 limits the obfuscation to below y-level 64, where the ores are, and is what keeps the cost reasonable.

Whether it is worth it depends on the server. On a private whitelisted SMP, no. On a public survival server where the economy depends on diamonds being scarce, yes, at engine mode 1. It is one part of a larger question covered in grief protection and anti-cheat.

Measure, change one thing, measure again#

Tuning without measurement is guessing, and every setting above has a cost as well as a benefit.

• /tps gives you ticks per second over one, five and fifteen minutes. Twenty is the maximum, and a server can never exceed it, so 20.0 means healthy and nothing more.
• /mspt is the better number: milliseconds per tick, with the median and the 95th percentile over the last five seconds, ten seconds and one minute. The tick budget is 50 ms. A server averaging 30 ms with a 95th percentile of 48 ms is at its limit even though /tps says 20.0. What tick rate actually means unpacks why.
• spark is the profiler. /spark profiler start, play for a few minutes of real load, /spark profiler stop, and you get a link to a call tree that names the plugin, the entity type or the chunk doing the work. Recent Paper builds ship it; if /spark is not a command on your server, drop the plugin jar in plugins/. Paper's old Timings system has been retired in favour of it. Reading a spark report is the how-to.

Change one setting, restart, and watch /mspt under the same load. If you change six things at once you will never know which one helped, and one of them will have broken a farm.

On RE:NODE the panel console gives you unfiltered output with command history and tab completion, so /mspt and /spark are one keystroke away, and the memory, CPU and disk graphs run against the plan's actual limits rather than the host's. A server pinned at 100% CPU is slow, not broken, and is never suspended for it - but it is also the clearest possible signal that the tick is the problem and not the memory. Reading a server load graph explains what the shapes mean.

What not to do#

Do not paste a config pack. The ones circulating are usually built for an older Paper, and keys that no longer exist are silently ignored while keys that changed meaning quietly break something. Copy individual settings, with the reason.

Do not install an entity-clearing plugin as a fix. A plugin that deletes all dropped items every five minutes hides the problem and deletes players' belongings. If entity counts are the issue, fix the cause: merge radius, despawn rates, per-chunk save limits, and the farm design that is producing ten thousand items a minute.

Do not raise view distance because you have memory spare. Memory is not the constraint; the per-tick cost of chunk and entity work is. A 12 GB server at view-distance=16 ticks worse than the same server at 8.

Do not disable the watchdog permanently. max-tick-time=-1 in server.properties means a hung server hangs forever instead of dumping the thread trace that tells you why.

Do not tune before you have sized correctly. If the plan has one core and thirty players, no configuration file will save it. How much RAM a Minecraft server needs and CPU vs RAM for game servers between them tell you whether you are tuning or rationing. And if the answer is that you need more than one machine's worth of players, the shape is a proxy network, not a bigger box - see a Velocity proxy network.

The last thing worth saying: Paper is not the only fork. Pufferfish and Purpur build further optimisations and behaviour toggles on top of it, at the cost of drifting further from vanilla. Running one is a matter of uploading the jar and pointing the server at it, and everything in this guide still applies because they inherit Paper's configuration files and add their own. Whether the extra few percent is worth another layer of divergence is a judgement call; for most servers, correctly configured Paper with the right heap is already faster than the hardware they run it on.

FAQ#

What is the single most effective Paper setting?

view-distance, in server.properties. Nothing else comes close, because it multiplies the cost of chunks, entities and network traffic all at once. simulation-distance is second.

Why is my TPS 20 when the server clearly lags?

TPS caps at 20 and hides everything below the limit. Use /mspt instead. If the median is close to 50 ms the server is finishing ticks just barely on time, and any spike pushes it over. Players feel that as stutter long before TPS moves.

Does lowering simulation distance break farms?

Yes, if the farm is further from a player than the new value. Mob farms, crop farms and anything on a redstone clock only run inside the simulation radius of an online player. Tell people the number you set so they can build accordingly.

Should I use Paper's anti-xray?

On a public survival server, engine mode 1 is usually worth it. Engine mode 2 costs real CPU and bandwidth and is only worth it if x-raying is actively damaging your economy. On a whitelisted server, neither.

My server hitches every five minutes. What is it?

The autosave. Lower chunks.max-auto-save-chunks-per-tick in paper-world-defaults.yml from 24 to around 8 so the work spreads over more ticks. Do not lengthen the autosave interval instead - that makes the hitch bigger and risks more lost progress.

Is Paper faster than Fabric with optimisation mods?

They are not comparable in the way the question assumes. Paper optimises the server and keeps the plugin ecosystem; Fabric with performance mods optimises a modded server and requires clients to match. If your players join with an unmodified launcher, the choice is already made. Paper, Fabric or vanilla covers the trade properly.