Server optimisation
How to optimise your Minecraft server and boost performance.
The first thing to keep in mind is that there is no best configuration. The best way to use this guide is to tune the values shown to your liking. If a value is not mentioned here, it is recommended to leave it as the default setting. Additionally, you should only reduce the values mentioned in this guide if you are actually having performance issues.
Value reductions here will have an impact on gameplay and may damage the experience for your players. If your server is not lagging, then you should not reduce any values. It is also recommended to follow this guide incrementally, making only a few changes at a time until the lag problem disappears. If the lag problem resurfaces, you can always further adjust the values later.
Server software
One of the easiest ways you can improve your server's performance is by using the most optimized server software. We recommend the popular fork of PaperMC called Pufferfish, which can be downloaded here. This guide also applies if you're using other forks such as Paper or Purpur.
Configuration files
Networking
server.properties - network-compression-threshold: 256
This allows you to set the cap for the size of a packet before the server attempts to compress it. Setting it higher can save some CPU resources at the cost of bandwidth, and setting it to -1 disables it. Setting this higher may also hurt clients with slower network connections. If your server is in a network with a proxy or on the same machine (with less than 2 ms ping), disabling this (-1) will be beneficial, since internal network speeds can usually handle the additional uncompressed traffic.
purpur-yml - use-alternate-keepalive: true
You can enable Purpur's alternate keepalive system so players with bad connection don't get timed out as often. Has known incompatibility with TCPShield.
Chunks
server.properties - simulation-distance: 4
Simulation distance is distance in chunks around the player that the server will tick. Essentially the distance from the player that things will happen. This includes furnaces smelting, crops and saplings growing, etc. This is an option you want to purposefully set low, somewhere around 3 or 4, because of the existence of view-distance. This allows to load more chunks without ticking them. This effectively allows players to see further without the same performance impact.
server.properties - view-distance: 7
This is the distance in chunks that will be sent to players, similar to no-tick-view-distance from paper. The total view distance will be equal to the greatest value between simulation-distance and view-distance. For example, if the simulation distance is set to 4, and the view distance is 12, the total distance sent to the client will be 12 chunks.
spigot.yml - view-distance: default
This value overwrites server.properties one if not set to default. You should keep it default to have both simulation and view distance in one place for easier management.
paper-world-defaults.yml - delay-chunk-unloads: 10s
This option allows you to configure how long chunks will stay loaded after a player leaves. This helps to not constantly load and unload the same chunks when a player moves back and forth. Too high values can result in way too many chunks being loaded at once. In areas that are frequently teleported to and loaded, consider keeping the area permanently loaded. This will be lighter for your server than constantly loading and unloading chunks.
paper-world-defaults.yml - max-auto-save-chunks-per-tick: 8
Lets you slow down incremental world saving by spreading the task over time even more for better average performance. You might want to set this higher than 8 with more than 20-30 players. If incremental save can't finish in time then bukkit will automatically save leftover chunks at once and begin the process again.
paper-world-defaults.yml - prevent-moving-into-unloaded-chunks: true
When enabled, prevents players from moving into unloaded chunks and causing sync loads that bog down the main thread causing lag. The probability of a player stumbling into an unloaded chunk is higher the lower your view-distance is.
paper-world-defaults.yml - entity-per-chunk-save-limit
With the help of this entry you can set limits to how many entities of specified type can be saved. You should provide a limit for each projectile at least to avoid issues with massive amounts of projectiles being saved and your server crashing on loading that. You can put any entity id here, see the minecraft wiki to find IDs of entities. Please adjust the limit to your liking. Suggested value for all projectiles is around 10. You can also add other entities by their type names to that list. This config option is not designed to prevent players from making large mob farms.
pufferfish.yml - max-loads-per-projectile: 8
Specifies the maximum amount of chunks a projectile can load in its lifetime. Decreasing will reduce chunk loads caused by entity projectiles, but could cause issues with tridents, enderpearls, etc.
Mobs
bukkit.yml - spawn-limits
The math of limiting mobs is [playercount] * [limit], where "playercount" is current amount of players on the server. Logically, the smaller the numbers are, the less mobs you're gonna see. per-player-mob-spawn applies an additional limit to this, ensuring mobs are equally distributed between players. Reducing this is a double-edged sword; yes, your server has less work to do, but in some gamemodes natural-spawning mobs are a big part of a gameplay. You can go as low as 20 or less if you adjust mob-spawn-range properly. Setting mob-spawn-range lower will make it feel as if there are more mobs around each player.
bukkit-yml - ticks-per
This option sets how often (in ticks) the server attempts to spawn certain living entities. Water/ambient mobs do not need to spawn each tick as they don't usually get killed that quickly. As for monsters: Slightly increasing the time between spawns should not impact spawn rates even in mob farms. In most cases all of the values under this option should be higher than 1. Setting this higher also allows your server to better cope with areas where mob spawning is disabled.
spigot-yml - mob-spawn-range: 3
Allows you to reduce the range (in chunks) of where mobs will spawn around the player. Depending on your server's gamemode and its playercount you might want to reduce this value along with bukkit.yml's spawn-limits. Setting this lower will make it feel as if there are more mobs around you. This should be lower than or equal to your simulation distance, and never larger than your hard despawn range / 16.
spigot.yml - entity-activation-range
You can set what distance from the player an entity should be for it to tick (do stuff). Reducing those values helps performance, but may result in irresponsive mobs until the player gets really close to them. Lowering this too far can break certain mob farms; iron farms being the most common victim.
spigot-yml - entity-tracking-range
This is distance in blocks from which entities will be visible. They just won't be sent to players. If set too low this can cause mobs to seem to appear out of nowhere near a player. In the majority of cases this should be higher than your entity-activation-range.
spigot-yml - tick-inactive-villagers: false
This allows you to control whether villagers should be ticked outside of the activation range. This will make villagers proceed as normal and ignore the activation range. Disabling this will help performance, but might be confusing for players in certain situations. This may cause issues with iron farms and trade restocking.
spigot.yml - nerf-spawner-mobs: true
You can make mobs spawned by a monster spawner have no AI. Nerfed mobs will do nothing. You can make them jump while in water by changing spawner-nerfed-mobs-should-jump to true in paper-world.yml.
paper-world-defaults.yml - despawn-ranges
Lets you adjust entity despawn ranges (in blocks). Lower those values to clear the mobs that are far away from the player faster. You should keep soft range around 30 and adjust hard range to a bit more than your actual simulation-distance, so mobs don't immediately despawn when the player goes just beyond the point of a chunk being loaded (this works well because of delay-chunk-unloads-by in paper-world.yml). When a mob is out of the hard range, it will be instantly despawned. When between the soft and hard range, it will have a random chance of despawning. Your hard range should be larger than your soft range. You should adjust this according to your view distance using (simulation-distance * 16) + 8. This partially accounts for chunks that haven't been unloaded yet after player visited them.
paper-world-defaults.yml - per-player-mob-spawns: true
This option decides if mob spawns should account for how many mobs are around target player already. You can bypass a lot of issues regarding mob spawns being inconsistent due to players creating farms that take up the entire mobcap. This will enable a more singleplayer-like spawning experience, allowing you to set lower spawn-limits. Enabling this does come with a very slight performance impact, however it's impact is overshadowed by the improvements in spawn-limits it allows.
paper-world-defaults.yml - max-entity-collisions: 2
Overwrites option with the same name in spigot.yml. It lets you decide how many collisions one entity can process at once. Value of 0 will cause inability to push other entities, including players. Value of 2 should be enough in most cases. It's worth noting that this will render maxEntityCramming gamerule useless if its value is over the value of this config option.
paper-world-defaults.yml - update-pathfinding-on-block-update: false
Disabling this will result in less pathfinding being done, increasing performance. In some cases this will cause mobs to appear more laggy; They will just passively update their path every 5 ticks (0.25 sec).
paper-world-defaults.yml - fix-climbing-bypassing-cramming-rule: true
Enabling this will fix entities not being affected by cramming while climbing. This will prevent absurd amounts of mobs being stacked in small spaces even if they're climbing (spiders).
paper-world-defaults.yml - armor-stands.tick: false
In most cases you can safely set this to false. If you're using armor stands or any plugins that modify their behavior and you experience issues, re-enable it. This will prevent armor stands from being pushed by water or being affected by gravity.
paper-world-defaults.yml - armor-stands.do-collision-entity-lookups: false
Here you can disable armor stand collisions. This will help if you have a lot of armor stands and don't need them colliding with anything.
paper-world-defaults.yml - tick-rates
This decides how often specified behaviors and sensors are being fired in ticks. acquirepoi for villagers seems to be the heaviest behavior, so it's been greately increased. Decrease it in case of issues with villagers finding their way around.
It is not recommended to change these values from their defaults while Pufferfish's DAB is enabled!
pufferfish.yml - dab.enabled: true
DAB (dynamic activation of brain) reduces the amount an entity is ticked the further away it is from players. DAB works on a gradient instead of a hard cutoff like EAR. Instead of fully ticking close entities and barely ticking far entities, DAB will reduce the amount an entity is ticked based on the result of a calculation influenced by dab.activation-dist-mod.
pufferfish.yml - dab.max-tick-freq: 20
Defines the slowest amount entities farthest from players will be ticked. Increasing this value may improve the performance of entities far from view but may break farms or greatly nerf mob behavior. If enabling DAB breaks mob farms, try decreasing this value.
pufferfish.yml - dab.activation-dist-mod: 7
Controls the gradient in which mobs are ticked. Decreasing this will activate DAB closer to players, improving DAB's performance gains, but will affect how entities interact with their surroundings and may break mob farms. If enabling DAB breaks mob farms, try increasing this value.
pufferfish.yml - enable-async-mob-spawning: true
If asynchronous mob spawning should be enabled. For this to work, the Paper's per-player-mob-spawns setting must be enabled. This option does not actually spawn mobs asynchronous, but does offload much of the computational effort involved with spawning new mobs to a different thread. Enabling this option should not be noticeable on vanilla gameplay.
pufferfish.yml - enable-suffocation-optimization: true
This option optimises a suffocation check (the check to see if a mob is inside a block and if they should take suffocation damage), by rate limiting the check to the damage timeout. This optimisation should be impossible to notice unless you're an extremely technical player who's using tick-precise timing to kill an entity at exactly the right time by suffocation.
pufferfish.yml - inactive-goal-selector-throttle: true
Throttles the AI goal selector in entity inactive ticks, causing the inactive entities to update their goal selector every 20 ticks instead of every tick. Can improve performance by a few percent, and has minor gameplay implications.
purpur.yml - zombie.aggressive-towards-villager-when-lagging: false
Enabling this will cause zombies to stop targeting villagers if the server is below the tps threshold set with lagging-threshold in purpur.yml.
purpur.yml - entities-can-use-portals: false
This option can disable portal usage of all entities besides the player. This prevents entities from loading chunks by changing worlds which is handled on the main thread. This has the side effect of entities not being able to go through portals.
purpur.yml - villager.lobotomize.enabled: true
Lobotomized villagers are stripped from their AI and only restock their offers every so often. Enabling this will lobotomize villagers that are unable to pathfind to their destination. Freeing them should unlobotomize them.
This should only be used when villagers are causing lag, otherwise performance may decrease.
Miscellaneous
spigot.yml - merge-radius
This decides the distance between the items and exp orbs to be merged, reducing the amount of items ticking on the ground. Setting this too high will lead to the illusion of items or exp orbs disappearing as they merge together. Setting this too high will break some farms, as well as allow items to teleport through blocks. There are no checks done to prevent items from merging through walls (unless Paper's fix-items-merging-through-walls setting is activated). Exp is only merged on creation.
spigot.yml - hopper-transfer: 8
Time in ticks that hoppers will wait to move an item. Increasing this will help improve performance if there are a lot of hoppers on your server, but will break hopper-based clocks and possibly item sorting systems if set too high.
spigot.yml - hopper-check: 8
Time in ticks between hoppers checking for an item above them or in the inventory above them. Increasing this will help performance if there are a lot of hoppers on your server, but will break hopper-based clocks and item sorting systems relying on water streams.
paper-world-defaults.yml - alt-item-despawn-rate
This list lets you set alternative time (in ticks) to despawn certain types of dropped items faster or slower than default. This option can be used instead of item clearing plugins along with merge-radius to improve performance.
paper-world-defaults.yml - redstone-implementation: ALTERNATE_CURRENT
Replaces the redstone system with faster and alternative versions that reduce redundant block updates, lowering the amount of logic your server has to calculate. Using a non-vanilla implementation may introduce minor inconsistencies with very technical redstone, but the performance gains far outweigh the possible niche issues. A non-vanilla implementation option may additionally fix other redstone inconsistencies caused by CraftBukkit. The ALTERNATE_CURRENT implementation is based off the Alternate Current mod. More information on this algorithm can be found on their page.
paper-world-defaults.yml - hopper.disable-move-event: false
InventoryMoveItemEvent doesn't fire unless there is a plugin actively listening to that event. This means that you only should set this to true if you have such plugin(s) and don't care about them not being able to act on this event.
Do not set to true if you wish to use plugins which listen to this event (e.g. protection plugins).
paper-world-defaults.yml - hopper.ignore-occluding-blocks: true
Determines if hoppers will ignore containers inside full blocks, for example hopper minecart inside sand or gravel block. Keeping this enabled will break some contraptions depending on that behavior.
paper-world-defaults.yml - tick-rates.mob-spawner: 2
This option lets you configure how often spawners should be ticked. Higher values mean less lag if you have a lot of spawners, although if set too high (relative to your spawners delay) mob spawn rates will decrease.
paper-world-defaults.yml - optimize-explosions: true
Setting this to true replaces the vanilla explosion algorithm with a faster one, at a cost of slight inaccuracy when calculating explosion damage. This is usually not noticeable.
paper-world-defaults.yml - treasure-maps.enabled: false
Generating treasure maps is extremely expensive and can hang a server if the structure it's trying to locate is in an ungenerated chunk. It's only safe to enable this if you pregenerated your world and set a vanilla world border.
paper-world-defaults.yml - treasure-maps.find-already-discovered
Default value of this option forces the newly generated maps to look for unexplored structure, which are usually in not yet generated chunks. Setting this to true makes it so maps can lead to the structures that were discovered earlier. If you don't change this to true you may experience the server hanging or crashing when generating new treasure maps. villager-trade is for maps traded by villagers and loot-tables refers to anything that generates loot dynamically like treasure chests, dungeon chests, etc.
paper-world-defaults.yml - tick-rates.grass-spread: 4
Time in ticks between the server trying to spread grass or mycelium. This will make it so large areas of dirt will take a little longer to turn to grass or mycelium. Setting this to around 4 should work nicely if you want to decrease it without the decreased spread rate being noticeable.
paper-world-defaults.yml - tick-rates.container-update: 1
Time in ticks between container updates. Increasing this might help if container updates cause issues for you (it rarely happens), but makes it easier for players to experience desync when interacting with inventories (ghost items).
paper-world-defaults.yml - non-player-arrow-despawn-rate: 20
Time in ticks after which arrows shot by mobs should disappear after hitting something. Players can't pick these up anyway, so you may as well set this to something like 20 (1 second).
paper-world-defaults.yml - creative-arrow-despawn-rate: 20
Time in ticks after which arrows shot by players in creative mode should disappear after hitting something. Players can't pick these up anyway, so you may as well set this to something like 20 (1 second).
pufferfish.yml - disable-method-profiler: true
This option will disable some additional profiling done by the game. This profiling is not necessary to run in production and can cause additional lag.
purpur.yml - dolphin.disable-treasure-searching: true
Prevents dolphins from performing structure search similar to treasure maps.
purpur.yml - teleport-if-outside-border: true
Allows you to teleport the player to the world spawn if they happen to be outside of the world border. Helpful since the vanilla world border is bypassable and the damage it does to the player can be mitigated.
Helpers
paper-world-defaults.yml - anti-xray.enabled: true
Enable this to hide ores from x-rayers. For detailed configuration of this feature check out Configuring Anti-Xray. Enabling this will actually decrease performance, however it is much more efficient than any anti-xray plugin. In most cases the performance impact will be negligible.
paper-world-defaults.yml - nether-ceiling-void-damage-height: 127
If this option is greater that 0, players above the set y level will be damaged as if they were in the void. This will prevent players from using the nether roof. Vanilla nether is 128 blocks tall, so you should probably set it to 127. If you modify the height of the nether in any way you should set this to [your_nether_height] - 1.
Misconceptions
Mob stackers
While it is true that using mob stacker plugins on naturally spawned mobs is a very bad idea, using these plugins on mobs originating from spawners is generally a good idea. If you are using this strategy to control spawner mob population, look for a stacker plugin that disables spawners when there are large mob stacks nearby.
Lag clearing plugins
Avoid plugins such as Lagassist and Clearlagg. Globally clearing items off the ground is a bad idea. Not only is it rare for items on the ground to cause performance issues, but the server will clear them all by itself without intervention. If you'd like this to happen faster, you can consult the alt-item-despawn-rate option in paper.yml. Using these plugins to delete mobs is also a bad idea, as it only forces the server to do extra work. Immediately after the mobs are cleared, the server will have to do a ton of expensive calculations to determine where to spawn the new mobs.
JVMs
While JVMs (such as GraalVM, Zulu and Corretto) can improve performance for some types of workloads, for the most part they do not improve Minecraft performance whatsoever. GraalVM, for example, will only improve performance if you're relying on running Javascript inside of your server. For the vast majority of servers that aren't doing this, you're going to have a more stable and consistent experience if you stick to Oracle or Adoptium implementations of the JVM.
Final tips
Disable timings! The timings feature built in to paper is a good diagnostic tool, but it causes a very large performance impact. This is due to timings having to constantly start and stop a virtual "stopwatch". This operation can happen north of 100,000 times per tick. This requires a context switch, which is extremely expensive. Most moderately-sized servers can expect to see a 20% performance improvement simply by disabling timings, and large servers can see as much as 40% or more improvement. This feature can be disabled by setting the timings.enabled option in paper.yml. If it is disabled, it can be re-enabled in-game if required by using the command /timings on.
Use Spark to debug performance issues. Spark is an alternative to timings which doesn't have the downside of causing large amounts of lag. It also provides far more detailed and accurate information which can be more accurately used to assess the impact of performance.
Avoid "exotic" forks. Forks downstream of Pufferfish/Purpur/Paper are often plagued by stability issues, while providing no real performance improvement. These forks are also rarely benchmarked for their performance impact (if ever) and can even decrease performance in some cases.
Last updated