Introduction / Background
This Minecraft server optimization guide is written in the style of a walkthrough, designed to expand on the information provided from the official documentation and putting additional emphasis on the gameplay changes and potential side effects that come with optimizations. It aims to provide a deeper understanding on the inner working of a Minecraft server instead of just handing out pre-determined values which often do more harm than good. Hopefully this guide provides some useful insights to you!
Last updated: November 26th, 2024 for Paper Version 1.21.3 Build #65
Recent changelog:
- Added despawn-time - a new Paper feature.
- Added legacy-ender-pearl-behavior option notes.
- Added pause-when-empty-seconds option notes.
- Removed
monster-spawn-max-light-level
reference. - Updated horizontal despawn-ranges recommendations.
Paper Chan Hideout: https://paper-chan.moe/discord
Epic emojis, stickers, and more!
Hangar is here
Hangar is PaperMC's very own plugin repository for Paper, Velocity, Folia, and Waterfall plugins. Here, you can find modern and developer-friendly tools to create, share, and discover plugins for your Minecraft server. Check it out!
Table of Contents
Introduction
Configurations & Optimizations
Pre-generate
View Distance
Entity Counts
Impacts of Alteration
Understand Mobspawn
server.properties
bukkit.yml
spigot.yml
Paper configs
Paper-world-defaults.yml
Paper-global.yml
Addendum
Performance Diagnostic Tool
Common Mistakes
JVM Flags
Backup and Recovery Best Practice
Quality of Life Plugins & Tools
Things to Avoid
Hosting Options
Domain and Server Record
Closing Notes
Configurations & Optimizationsπ
Before we startβ¦
There is no singular setup that will work for every server. You should read and understand each available config option and tweak the numbers accordingly to fit your own unique circumstances. The optimal config for your server will vary based on server hardware, average player count, and the type of game mode running. The values shown below are the defaults and are provided as examples. Please test and experiment, and then come up with your own set of numbers that best suit your community
With Modern Minecraft version, running on default (Vanilla) setting requires decent hardware and it may not be feasible for some small to medium sized servers where server resource are very limited. Aside from picking a reputable host and the right hardware, optimizing the configurations and making compromises to Vanilla gameplay becomes essential. Carefully read through the config options provided below and you will ensure a smooth operation!
Pre-generate Your Mapπ
Generating new chunks consumes a considerable amount of resources and it is recommended to pre-generate your map if you are launching a new map/server.
Even if you do not plan to set a world border, it is still a good idea to pre-generate 5~10k
from your spawn as it will help ease the launch day stress on your server. Not to mention, it will catch any potential uncaught bugs on generation ahead of the actual launch day.
Grab Chunky and ChunkyBorder by pop4959
Chunky
is the simplest pre-gen plugin and combined with ChunkyBorder
, you can customize the border shapes to your liking.
Picking the Optimal View Distance & Simulation Distanceπ
simulation-distance
determines how much environment is active (ticking) around the player.
view-distance
determines how many chunks (terrain) are visible to the player.
simulation-distance has a huge impact on the performance so having a lower value will help maintain a lagging-free environment. The default value for Vanilla Minecraft is 10 and most of the farm designs on YouTube are made based off this value. Lower this value will impact those farms, which we will go over later. Personally, I wouldnβt go lower than 5 so the gameplay experience is somewhat pleasant; however, if you are doing mini games or Skyblock, you can go much lower.
view-distance provides further chunks terrain view and is not as performance heavy as simulation-distance, but does occupies more RAM; increase the value incrementally to find your sweet spot on your server if you do decide to increase it.
Additionally, you can define individual values on a per world basis in spigot.yml
to overwrite server.properties
.
(We will cover how to proper set this up in per-world config section later)
Keeping Entity Count Under Controlπ
Entities are resource-intensive in the Modern Minecraft versions, even the top-of-the-line CPU in the current market would still be brought down to its knees if you do not keep entities under control.
Ideally, you want to maintain your overall entity ticks to be less than 30% (Assuming a reasonable amount of player activity is present and not just an empty server)
spark is a great tool to find the source of lags and to compare the result of optimizations.
Be Aware of the Impacts of your Alterationπ
With each alteration comes a compromise! Most of your players are just copying popular farm designs block by block without knowing how it actually works so it is important as a server owner to understand the impact of your alterations so you can explain them to the player better. In the following walk through, I will attempt to explain the impact of each change and how to combat compromises.
Understand Mob Spawn Mechanicsπ
Below is a demonstration on how mob spawning works around a player. The graph and indicated value is made based on Vanilla/Paper default.
Graph explanation
- The brown cylinders indicate the mob spawn range.
- The red sphere indicates the mob spawning zone (inbetween 24 - 128 blocks).
- The yellow sphere indicates the mob free zone as no mob will spawn that close to a player (24 blocks).
- Any entity that falls under the 32 blocks ring (entity activation range) will be ticked at normal rate.
- Any entity that resides in-between the 32 - 128 blocks ring will be ticked at a reduced rate.
- Any entity that falls outside the 128th block is instantly despawned.
Vanilla / Paper default value
View Distance
: 10 (chunks)
Simulation Distance
: 10 (chunks)
Mob Spawn Range
: 8 (chunks)
Despawn range (soft)
: 32 (blocks)
Despawn Range (hard)
: 128 (blocks)
entity activation range
: 32 (blocks)
The 5 abovementioned config options are closely related to each other and it is crucial to ensure each value is setup correctly.
simulation distance
determines the maximum possible size of a farm as area outside of this range will not be ticked.
- A farm cannot excess the radius of
(simulation distance -1)x16
blocks. - Everything outside of
simulation distance
wonβt tick so any farm bigger than this value wont be functional.
mob spawn range
also determines the maximum size of a farm as no mobs will spawn outside of this defined range.
Mob Spawn Range
should be between(simulation distance -1)
to3
minimum.- If you are running the vanilla default simulation distance of 10, you can keep the mob spawn range at 8 or lower.
- Mobs can only spawn a minimum of
24 blocks
away from players so setting mob spawn range below3
is strongly discouraged unless your simulation distance is extremely low at 3 or lower. - Every mob farm has a designated mob collection platform, the size of the platform is determined solely by this value (in chunks)
Despawn range
, both hard
and soft
, governs the despawn behavior of any non-persistent entities in Minecraft. Any entity within the soft despawn range
has a predetermined chance to despawn, which helps rotate the variety of entities around a player. However, any non-persistent entities will instantly despawn if they are outside the hard despawn range
.
Paper offers server owners the option to adjust the despawn range both horizontally and vertically, which can be very helpful for servers that need to run with a simulation distance
lower than 10
. This will be explained in greater detail in the later despawn range section.
When troubleshooting why a farm is not working, be sure to go through every config mentioned above and make the necessary modifications to the farm design accordingly. Do not copy and paste from YouTube tutorials block by block without ever taking these configs into account.
Take a look at Paper Chanβs Little Guide to fix your Nether farm for a sample walkthrough on common troubleshooting steps.
- Utilize
/paper mobcaps
and/paper playermobcaps
for additional details on mob spawning around a player. It is especially useful for finding errors on the spawnproofing.
The video below provides a detailed explanation of mob spawning, presented by Nico is LOST. It is strongly recommended to watch.
Using Science to MAXIMIZE the Mob Spawning Algorithm
Why is my farm built in older version slower now when nothing has changed?π
Minecraft runs the spawn check between the lowest block and the highest block (ranging from Y0 to Y265 in 1.17) to check and see if the block is eligible for a spawn attempt, it then has a 24% change to successed at spawning at that particular Y position.
Farms are designed based on this rule and their ideal location is chosen accordingly.
Large perimeter β Making a large perimeter around your farm eliminates all other possible spawn locations but the designated spot on the farm platform. (This can be seen on the SciCraft server and in most farm tutorials that use void flat-world for demonstration)
Enderman farm at Y0 β Enderman farms are advised to be built at Y0 as it is the most effective location.
Nether Farm above Netherroof β Nether farm are usually built high above Netherroof as it is generally a pain to make a large perimeter due to the amount of lava present, and by going higher into the Netherroof, you move your despawn sphere high up in the sky to eliminate all possibilities of a mob spawning anywhere outside of your farm platform.
With that being said, your farm may be less effective now due to the world height change. Instead of checking for an eligible spawn attempt from Y0 to Y265, itβs now checking from Y-64 to Y320 to find the lowest & highest block to run spawn attempts. Your farm from 1.17 located on Y0 now has 64 more additional blocks below it, which slows down the mob spawning.
How to mitigate the issuesβ¦
Rebuild your farm at the lowest point of the world which is now Y-64.
(This is the most ideal solution but also the most painful).
Dig out an even larger perimeter & empty out everything below the farm from Y-64 to Y0 (air block only).
Mob spawn attempts are made on all loaded chunks with defined spawn-limits
in bukkit.yml
(or paper-world-defaults
).
Accept & understand that mob spawning is inherently flawed in multiplayer servers and a more detailed explanation is provided in the per-player-mob-spawns section later.
server.propertiesπ
Essential configurations for server.properties
server.properties/view-distanceπ
view-distance=10
This sets the view distance (terrain only) of the server unless stated otherwise in spigot.yml
.
simulation-distance=10
This sets the simulation distance (ticking) of the server unless stated otherwise in spigot.yml
.
Picking a suitable combination of view-distance & simulation-distance is extremely important.
If you decide to lower your view-distance
& simulation-distance
,...
Please refer to How Mob Spawn Works to ensure all other configs are adjusted accordingly.
simulation-distance
should always be equal to or lower than view-distance.
(If simulation distance is set higher than view distance, only an area up to view distance will be applied)- It is strongly discouraged to reduce these value lower than
5
.
If you wish to provide further terrain view to players, please note that each additional increase after 10, the total amount of loaded chunks around a player will increase exponentially.
The formula to calculate the total chunks loaded by a single player is [(View Distance +2)x2+1]^2
- For
view-distance=10
(Vanilla default), a singular player will load625
chunks. - For
view-distance=5
, a singular player will load225
chunks. - For
view-distance=15
, a singular player will load1225
chunks.
Although view-distance
uses significant less resources compare to simulation-distance
, please still be mindful on its performance impact especially on large server where every bit of resource saving helps.
- Additionally, you are given the ability to overwrite/specify view distance & simulation distance for each world in
spigot.yml
. We will go over this in the per-world config section later.
For example, you can opt for a higherview-distance
in the_end dimension, which would make navigating through the void with Elytra a much more pleasant experience for your players.
server.properties/allow-flightπ
allow-flight=true
This prevents players from getting kicked by the server for "flying" while riding a horse or climbing on scaffolding.
Having this option as true doesn't mean everyone can fly, it just means that players would not get kicked if the server thinks they are flying.
server.properties/log-ipsπ
log-ips=true
Vanilla Minecraft provides an option to toggle player IP address logging.
For those who wants to protect player privacy, you can toggle this option to false
.
This is especially useful in times where log files need to be shared with a third party auditor, maintainer, or developer for general troubleshooting.
server.properties/pause-when-empty-secondsπ
pause-when-empty-seconds=-1
Mojang has introduced a new pause feature that puts the server into a sort of sleep mode when no players are online. This is very likely to cause issues with servers that have plugins. The option is set to -1
by default, which means it is disabled.
bukkit.ymlπ
Essential configurations for bukkit.yml
bukkit.yml/spawn-limitsπ
spawn-limits:
monsters: 70
animals: 10
water-animals: 5
water-ambient: 20
water-underground-creature: 5
axolotls: 5
ambient: 15
This section determines the mob cap in your server. Lowering the value here has the most direct impact on server performance, as entities are one of the most resource intensive tasks the server has to tackle.
The global entity cap will scale based on online player counts as long as per-player-mob-spawns
is set to true
in paper-world-defaults.yml
. Given that valid spawn locations exist around a player; the server will attempt to spawn entities until the spawn-limit cap is reached.
The spawn limit can also be set on a per-world basis. Please check out the Per World config section here for additional information.
mob-spawn-range
in spigot.yml accordingly to achieve this illusion.Click here to show a detailed explanation on how the calculation is done..
For example, if I want to set my monster cap to 45 and also keeping the mob density roughly the same as before, I would solve the math equation below
(Default mob Cap) : (Default Spawn Area) = (New Mob Cap) : (New Spawn Area)
where the constants are as followed,
Default Mob Spawn Range = 8 chunks
Minimum distance where a mob can spawn = 24 blocks away from a player
Default Spawn Area = [ (Mob Spawn Range x2 x16) +1]^2 - ( 24 x2 +1 )^2 = (8x2x16+1)^2 - 49^2 = 66049 - 2401 = 63648
70:63648 = 45:b ; where b = New Spawn Area (in blocks)
63648 x 45 = 70b
b= 40916
Let a = New Mob Spawn Range, where b = [ (a x16 x2) +1]^2 - (24 x2 +1)^2, and b = 40916
(32a +1)^2 - 2401 = 40916
(32a +1)^2 = 43317
32a +1 = 208
32a = 207
a = 6.46
I will then set mob-spawn-range to 6
(or 7
) in spigot.yml
Here is a cheat sheet with prefilled suggestions for monster category for those who are too lazy to workout the math, please read carefully and apply the config accordingly.
Overall Entity Count (%) | Suggested spawn-limit in bukkit.yml |
Suggested mob-spawn-range in spigot.yml |
Actual Calculated Number |
---|---|---|---|
100% (Vanilla) | 70 (default) | 8 (default) | 8 (default) |
90% | 63 | 7 or 8 | 7.6 |
80% | 56 | 7 | 7.18 |
70% | 49 | 6 or 7 | 6.74 |
60% | 42 | 6 | 6.26 |
50% | 35 | 5 or 6 | 5.75 |
40% | 28 | 5 | 5.18 |
30% | 21 | 4 or 5 | 4.55 |
20% | 14 | 4 | 3.81 |
10% | 7 | 3 | 2.89 |
3% | 2 | Please upgrade your server hardware | My Samsung smart fridge can handle more entities |
The suggested numbers above are for the purpose of keeping the mob density consistent with Vanilla. Feel free to make up your own numbers that work for your server. As for other categories, there will never be an ideal number, as entities like sheep, cows, and fish have more complicated spawning rules and additional mechanics. Generate a spark report, analyze it, and make proper adjustments as needed.
Please read the Understand Mobspawn section to validate other configs as needed if you do make changes here.
Entity related performanc issue?
Generate a spark report during the busiest period where the most players are online in your server and analyze the report for problematic areas to be addressed.
- Overall, entities should be less than
30%
of your tick and if you are seeing high tick time spent on mob spawning, it means that your entity cap is too high, reduce accordingly.
Ideally, you want to get your mob density as close to Vanilla as possible while maintaining below 50 mspt on average during the peak hour. Continue to lower the value until you can achieve this if you are not able to maintain it with the preset valve above. - As long as mobs are instantly killed in a farm, the yield of the farm should be roughly the same as Vanilla Minecraft given the farm design is adjusted accordingly.
- Please note that, the limits here only apply to naturally spawned entities. Entities being created through special spawning mechanism such as Allay Duplication, Iron Golem from Villager Gossiping, Guardian within Ocean Monuments are not limited by this config. A plugin is required to properly limit them.
See Quality of Life and Must-have Plugins section below for more info.
Every entity in the game falls under 1 of the 7 categories as listed below π
monster
category consists of Husk, Witch, Zombie, Guardian, Giant, Warden, Wither, Magma Cube, Evoker, Skeleton, Shulker, Ravager, Elder Guardian, Pillager, Phantom, Zombified Piglin, Endermite, Ghast, Drowned, Illusioner, Zoglin, Wither Skeleton, Vex, Spider, Piglin Brute, Silverfish, Blaze, Vindicator, Zombie Villager, Creeper, Bogged, Stray, Slime, Hoglin, Breeze, Piglin, Cave Spider, Enderman, Ender Dragon.animals
orcreature
category consists of Allay, Goat, Wolf, Polar Bear, Zombie Horse, Strider, Horse, Trutle, Frog, Bee, Llama, Pig, Panda, Rabbit, Sheep, Cat, Fox, Tadpole, Sniffer, Cow, Ocelot, Parrot, Skeleton Horse, Mule, Camel, Wandering Trader, Chicken, Mooshroom, Armadillo, Donkey, Trader Llama.ambient
category consists of bat. Bat is useless.water-animals
orwater_creature
category consists of squid and dolphins.water-ambient
category consists of cod, pufferfish, salmon, tropical fish.water-underground-creature
orunderground_water_creature
category consists of Glow Squid.axolotl
category consists of Axolotl.Misc
category consists of Boat, Snow Golem, Evoker Fangs, Trident, Minecart with Command Block, Minecart with Hopper, Thrown Egg, Glow Item Frame, Firework Rocket, Item Display, End Crystal, Leash Knot, Eye of Ender, Painting, Minecart with Monster Spawner, Shulker Bullet, Snowball, Boat with Chest, Item Frame, Primed TNT, Wither Skull, Lightning Bolt, Minecart with Chest, Small Fireball, Potion, Falling Block, Llama Spit, Spectral Arrow, Wind Charge, Minecart, Item, Fishing Bobber, Interaction, Ominous Item Spawner, Player, Arrow, Minecart with Furnace, Block Display, Thrown Bottle o' Enchanting. Thrown Ender Pearl, Area Effect Cloud, Armor Stand, Marker, Minecart with TNT, Experience Orb, Text Display, Dragon Fireball, Villager, Iron Golem, Wind Charge, Fireball
Some categories have two different names listed due to Paper using the proper names in related paper configs
while bukkit.yml
still uses the old names.
Villagers are complex entities and very resource intensive π
Villagers are generated with Village structures and breeded by players. They are the entity that cause a great deal of performance issues in most Minecraft servers. Since they are not limited by the config options in bukkit.yml
mentioned above, using the recommended methods below to artificially control their populations and their impact to the server is strongly recommended. It is an alternation to Vanilla gameplay but it is sadly necessary as most players are not resource efficient and would produce a tons of Villagers unnecessarily.
Below are a few different approaches to help address villager problems, please consider them carefully and pick one that works the best for your community.
- Attempts to reduce villager tick-rates to ease the workload on the server.
- Introduce a hard cap with a farm limitor type plugins and then clearly communicate the limit to your players so they can adjust their playstyle.
- Using a plugin to dynamically remove the A.I. from the villagers if they are used as trading hall vendors.
- Introduce different ways for players to gain loots thus greatly reduce the need for player-made trading halls. This may include a community trading hall, a global admin shop with villager loots, or customize your wandering traders loot table with superior items.
bukkit.yml/ticks-perπ
ticks-per:
animal-spawns: 400
monster-spawns: 1
water-spawns: 1
water-ambient-spawns: 1
water-underground-creature-spawns: 1
axolotl-spawns: 1
ambient-spawns: 1
autosave: 6000
This section determines the frequency of each category of entities making an attempt to spawn (value in ticks).
Minecraft will always attempt to spawn entities until it hits the spawn-limits on previous section. Altering the number here should be your secondary choice due to the fact that the mob cap will almost always be reached. All you are doing is just delaying the impending doom, please establish a proper entity cap on the spawn-limits mentioned previously first.
Calculating and validating mobspawn costs resources and it is always a better idea to reduce the overall entity cap on spawn-limits first, then increase ticks-per config here as a secondary buffer. Please utilize /paper mobcaps
and /paper playermobcaps
to monitor and ensure the mob cap is always being reached. If your mobcap cannot be reached in a timely matter, it's probably a sign that your spawn-limits is either too high and/or your mob-spawn-range is too short.
- If you notice a higher than usual amount of ticks spent on mob spawning on your spark report, your spawn-limits may be too high, reduce your mob cap on the section above so mob cap can be reached.
- For Skyblock / Oneblock gamemodes, this is especially crucial, as the server tends to have difficulty reaching the mob cap due to the limited spawnable area (which means the server is constantly making attempts to spawn more mobs). Please adjust the configs accordingly to address this issue.
This option is a direct nerf to all mob farms yield rate, so picking an ideal number here is very important as it is a fine balance when it comes to optimizing and balancing gameplay experience.
paper-world-defaults.yml/entities.spawning.ticks-per-spawnπ
entities:
spawning:
ticks-per-spawn:
ambient: -1
axolotls: -1
creature: -1
monster: -1
underground_water_creature: -1
water_ambient: -1
water_creature: -1
The above settings can be individually defined in [world folder]/paper-world.yml
to serve as overrides to the default configuration. This enables server owners to fine-tune the intervals between each spawn attempt on a per world basis.
spigot.ymlπ
Essential configurations for spigot.yml
spigot.yml/world-settings.default.view-distanceπ
view-distance: default
simulation-distance: default
This serves as an overwrite to the identical config in the server.properties
Putting a value here will overwrite the value inside server.properties
The value default instructs the server to use the value from server.properties
The value can be set per-world if an additional category is created.
spigot.yml/world-settings.default.mob-spawn-rangeπ
mob-spawn-range: 8
Radius in chunks around a player in which server attempts to spawn mobs.
As mentioned previously in the bukkit.yml section, this value can be altered to adjust the perceived mob density.
This value should always be set to a maximum of (Simulation Distance - 1) with a minimum of 3, as any entity falling outside of the simulation distance and the bordering chunk wont be ticked.
(see note below)
If you are running with the Vanilla default simulation-distance of 10, you can adjust the number between 8~3 without following the above rule.
If your mob-spawn-range is higher than the simulation-distance for example, the perceived mob density would be lower due to the fact that monsters would attempt to spawn outside of your simulation-distance. It is crucial to have the correct value.
For example, if you have a simulation-distance of 6, your mob spawn range can be set between 3~5.
Technically, 3 is not the minimum value, but due to the fact that no mobs will spawn within 24 blocks around the player, it makes zero sense to go below 3 as it drastically reduce the spawnable area and mob cap may not be reached in extreme case.
Refer back toUnderstand Mobspawn section for full detail.
spigot.yml/world-settings.default.nerf-spawner-mobsπ
nerf-spawner-mobs: false
This setting removes AI from mobs spawned from a spawner. If your server allows players to relocate spawners, setting this option to true can reduce lag.
Please also toggle spawner-nerfed-mobs-should-jump
to true
in paper-world-defaults.yml
if you do decide to enable this. It will allow mob to jump so certain farms will remind functional.
- Read Things to Avoid section for why allowing your players to silktouch spawner is a bad idea.
spigot.yml/world-settings.default.entity-tracking-rangeπ
entity-tracking-range:
players: 128
animals: 96
monsters: 96
misc: 96
display: 128
other: 64
entity-tracking-range determines how far away in blocks that an entity is tracked and sent to the client in order for players to see them.
Paper provides these options for you to decide how far away an entity should be tracked (display to client) instead of tracking everything up to bordering chunks (simulation-distance -1). This is an optimized solution to combat expensive entity tickings.
You can find related performance merits in your spark report listed under Chunk provider tick.
tracker stage 1
is tracking entities.
tracker stage 2
is broadcast entity tracking changes.
If Chunk provider tick is taking a significant amount of resource, you should first try to reduce overall entity counts, then lower simulation distance; and if all else failed, reduce tracking range as a last resort.
For a server with sufficient hardware to support it, it may be benefitial to increase entity-tracking-range
higher to boost gameplay experience. The Value is in blocks and if you do decide to increase them, please keep it at a maximum of equal or below (simulation distance-1)x16
.
Additionally, Paper allows the server owners to define the vertical Y
value of entity-tracking-range in paper-world-defaults.yml/entities.tracking-range-y
if one wish to have entities to show up or disappear faster.
entity-tracking-range categories
player
consists of players.monster
consists of monster, raider, and flying monster.animal
consists of villager, water-animal, and animal.misc
consists of itemframe, painting, sign, dropped item, experience orb.display
consist of display entity.other
consists of everything not listed above (I.E. armor stand).
The value is in blocks and should always be set to a maximum of (simulation-distance -1)x16
and no lower than 1
.
(BONUS fact: Setting the value to 0
, all entities will be hidden; setting the value to -1
, all entities will essentially become ninja! PLEASE DONT DO THIS)
If you are experiencing invisible Ghast Ambush, it may be a symptom of your entity-tracking-range
for monster
is set too low.
- Additionally, check client side setting
Options
>Video Settings
>Entity Distance
and make sure it is set high enough to show the Ghast.
entity-tracking-range
, please also adjust and match the value in the corresponding category on entity-activation-range
as well, so players do not see frozen entities.spigot.yml/world-settings.default.entity-activation-rangeπ
entity-activation-range:
animals: 32
monsters: 32
raiders: 64
misc: 16
water: 16
villagers: 32
flying-monsters: 32
wake-up-inactive:
animals-max-per-tick: 4
animals-every: 1200
animals-for: 100
monsters-max-per-tick: 8
monsters-every: 400
monsters-for: 100
villagers-max-per-tick: 4
villagers-every: 600
villagers-for: 100
flying-monsters-max-per-tick: 8
flying-monsters-every: 200
flying-monsters-for: 100
villagers-work-immunity-after: 100
villagers-work-immunity-for: 20
villagers-active-for-panic: true
tick-inactive-villagers: true
ignore-spectators: false
entity-activation-range determines how far away (in blocks) an entity should be activated.
Any entity falling outside of this zone will be ticked at a reduced frequency.
Those values should always be set to a maximum of (simulation-distance - 1)x16
and no lower than 16
if you are running extremely low simulation-distance/view-distance on your server.
A value of -1
on the corresponding categories listed within entity-activation-range
will disable this feature for that category and restore the behavior to Vanilla; however, this is a huge performance hit to your server. Do so at your own risk and only when absolutely necessary.
Reducing entity activation range should be the last resort...
You should lower the overall entity count & simulation-distance/view-distance first. Only alter this config if all other measures are proven insufficient to improve performance.
tick-inactive-villager
could be changed to false
if you do not wish to tick all villagers that are loaded but outside of activation range. In other words, only villagers that are within the activation range will be active.
- However, doing so may reduce the yield of Iron Golem farms if a player is not in close proximity.
- The villager trade cooldown timer will not go down if no player is close by.
spigot.yml/world-settings.default.entity-activation-range.wake-up-inactiveπ
work immunity and wake up inactive are implemented by Paper with the goal of bringing more liveness to the world by allowing certain entities to "wake up" and do some work for a set amount of time. It allows villager to restock, find work etc...
Change max-per-tick
to 0
if you do not want this behavior for that particular category.
Click here to read EAR Commit message on Github
To elaborate a bit more, we will use this snippet of wake-up-inactive
below as an example to help you get a better understanding of this mechanic.
wake-up-inactive:
villagers-max-per-tick: 4
villagers-every: 600
villagers-for: 100
villagers-work-immunity-after: 120
villagers-work-immunity-for: 20
The above setting translates into the following behavior...
For every 600
game ticks, there is a chance of up to 4
randomly selected loaded villagers, that has not been active for 120
ticks, to wake up for 100
ticks where they are able to wake up and do stuff for 20
ticks while being immune from the freezing effect of being too far away from players.
To disable work immunity, set villagers-work-immunity-after
to 0
, please note that this will break villagers.
spigot.yml/world-settings.default.merge-radiusπ
merge-radius:
item: -1
exp: -1
Paper by default follows the same merge mechanism as Vanilla Minecraft in 1.21.
As of Paper 1.21 build #38, the merge behavior has been restored to matching Vanilla Minecraft (-1
means default). To fully understand how exp merge works, check out this video by Nico is LOST It has an in-depth explanation of the Vanilla merge mechanic.
If you do decide to use the Craftbukkit/Spigot merge feature, the value is in blocks, adjust accordingly to your needs. Additionally, you can manually define a value in config/paper-world-defaults.yml/entities.behavior.experience-merge-max-value
if you wish to still merge the exp orb but with a set amount of maximum value per orb.
entities:
behavior:
only-merge-items-horizontally: true
Additionally, only-merge-items-horizontally
can also be toggled to true
in config/paper-world-defaults.yml
to further align the experience orb behavior more closely with Vanilla. It has a slight performance hit but is very beneficial to the player's gameplay experience.
Paper configsπ
A config folder now stores the default and global config files for your Paper server, and it is located in your Minecraft root folder.
paper-global.yml
consists of all available global config.
paper-world-defaults.yml
consists of the default config for all worlds.
Additionally, a per-world basis config file called paper-world.yml
is also generated in each world folder.
paper-world.yml
can be edited to overwrite the config on a per-world basis and is located in /[world_name]/paper-world.yml
paper-world-defaults.ymlπ
Essential configurations for paper-world-defaults.yml
paper-world-defaults.yml/entities.tracking-range-yπ
tracking-range-y:
enabled: true
animal: default
display: default
misc: default
monster: default
other: default
player: default
In addition to the entity-tracking-range
in spigot.yml, Paper provides the ability to config the vertical Y level
tracking distances. This is espeically useful for server that wish to make entities appear/disappear earlier or later.
It can be enabled for particular categories per world based on server needs.
paper-world-defaults.yml/entities.spawning.despawn-rangesπ
despawn-ranges:
ambient:
hard: default
soft: default
axolotls:
hard: default
soft: default
creature:
hard: default
soft: default
misc:
hard: default
soft: default
monster:
hard:
horizontal: default
vertical: default
soft: default
underground_water_creature:
hard: default
soft: default
water_ambient:
hard: default
soft: default
water_creature:
hard: default
soft: default
This value defines how far away a mob should have a chance to despawn (soft) or instantly despawn (hard).
Paper also offers the ability to separately define the despawn range both vertically and horizontally. This is extremely helpful for servers that need to run with a simulation distance lower than the default 10, either due to weaker hardware or higher player counts.
paper-world-defaults/entities.spawning.despawn-ranges-notesπ
Rules to follow:
If simulation-distance is below 10
, mob-spawn-range
should be set to either equal to or less than 8
, or to (simulation-distance -1)
, whichever value is lower. While despawn-ranges.hard.horizontal
should be set to (simulation-distance -1)x16
This ensures that all entities have a chance to despawn before hitting the bordering chunk. Thus, it preserves natural mob density and prevents unnecessary mob spawning or despawning attempts.
To individually define the horizontal and vertical despawn ranges, two additional lines should be added under the monster.hard
section, as shown below.
despawn-ranges:
monster:
hard:
horizontal: default
vertical: default
soft: default
The vertical value should always be kept at the default
, which is 128
in Vanilla Minecraft. This is very important to preserve gameplay consistency, as the majority of YouTube farm tutorials instruct players to build their AFK spots accordingly.
If you need to run the simulation with a distance lower than 10
, consult the table below for a better visualization of the suggested values.
simulation-distance | mob-spawn-range | despawn-range.hard.horizontal |
---|---|---|
10 (Vanilla) | 8 (Vanilla) | 128 (Vanilla) |
9 | 8 | 128 |
8 | 7 | 112 |
7 | 6 | 96 |
6 | 5 | 80 |
5 | 4 | 64 |
4 | 3 | 48 |
3 (not ideal) | 3 | 36 (not recommended) |
paper-world-defaults/entities.spawning.despawn-timeπ
Paper provides the ability to set despawn times individually for each entity type, in addition to the existing Vanilla despawn rules. A complete list of entity type can be found here.
despawn-time:
llama_spit: 1200
snowball: 1200
fireball: 1200
dragon_fireball: 1200
small_fireball: 1200
arrow: 3000
shulker_bullet: 3000
wither_skull: 3000
trident: 3000
Using despawn-time
together with entity-per-chunk-save-limit
and alt-item-despawn-rate
in the following sections helps prevent player- or game-generated entities that can sometimes cause performance issues or server crashes.
paper-world-defaults.yml/chunks.entity-per-chunk-save-limitπ
entity-per-chunk-save-limit:
experience_orb: 50
snowball: 20
ender_pearl: 20
arrow: 20
fireball: 10
small_fireball: 10
dragon_fireball: 5
egg: 20
area_effect_cloud: 10
llama_spit: 5
shulker_bullet: 8
spectral_arrow: 5
potion: 5
experience_bottle: 5
trident: 10
wither_skull: 10
The option limits the maximum amount of each specified entity saved in a chunk.
The limit here is essential as it prevents the server from stalling when attempting to load a chunk that contains a large number of these projectile entities.
(Sometimes projectiles are being fired into unloaded chunks intentionally by players to crash a server, or unintentionally by sheer luck. Both of which can be avoided with these limits set in place)
paper-world-defaults.yml/entities.spawning.alt-item-despawn-rateπ
alt-item-despawn-rate:
enabled: true
items:
cobblestone: 600
cobbled_deepslate: 600
netherrack: 600
rotten_flesh: 900
ender_pearl: 900
leather: 900
bone: 1200
bone_meal: 1200
cactus: 900
egg: 900
feather: 900
gunpowder: 1200
arrow: 900
blaze_rod: 1200
cod: 1200
salmon: 1200
string: 1200
ink_sac: 900
slime_ball: 1200
phantom_membrane: 900
Enabling this option will allow you to despawn commonly dropped items/junk items faster
cactus
is added on the list in an effort to reduce the impact of the common cactus farm in which many cactus would be left on the surface until they despawn due to the farm design.
egg
is also listed here in an effort to prevent zombie from picking them up thus preventing them from desapwning. It is a common issue in survival servers where players may be afk for an extensive period of time and results in groups of zombie all holding commonly dropped items around the player bases.
The value is in ticks which means a value of 20
equals to 1
second of server time.
Additional items can be added to the list above and you should find your own reasonable value that suits your needs as every server has their own unique circumstances. For example, if a farm utilizes minecarts in a closed loop to pick up drops, you want to ensure the value isn't set too low, so the minecart is able to pickup items before they despawn.
A complete list of item type can be found here..
Additionally, there is a similar config item-despawn-rate
that controls all dropped-item despawn timer in spigot.yml
; however, that is a very intrusive change that breaks the 5
minute de-spawn time promise that most Minecraft players are familiar with, hence why it is omitted here.
The goal of optimizing the server is to make the game more enjoyable for your players not to make them suffer!
paper-world-defaults.yml/collisions.max-entity-collisionsπ
max-entity-collisions: 8
The value is the maximum amount of entities that should be included in collision lookups. The server will stop processing any additional entity collisions after this threshold.
Lowering this value will help with performance as the animal AI goes haywire trying to path-find away from each other in a small confined space.
Do not set the value lower than 3
as it will have game-breaking effects on things that rely on collisions in order to work properly.
This is not to be confused with gamerule maxEntityCramming
.
- The cramming gamerule sets the maximum amount of entities that can be crammed together before they start taking suffocation damage.
- To lower this value, use
/gamerule maxEntityCramming [number]
(default is 24) - This gamerule has a direct impact on one block animal farms as the maximum number of animals that can be held inside a block space is determined by this value.
paper-world-defaults.yml/collisions.fix-climbing-bypassing-cramming-ruleπ
fix-climbing-bypassing-cramming-rule: true
This fix the issue where climbing mobs bypass the cramming rules
Leave it false
if you have farms that utilize this behavior (very unlikely).
paper-world-defaults.yml/entities.spawning.per-player-mob-spawnsπ
per-player-mob-spawns: true
Paper would attempt to spawn mobs more evenly across all players online.
Ensure this option is set to true. This is beneficial to the majority of servers.
When enabled, the global mob cap will scale based on the number of players online.
To access detailed breakdown of mobcaps, use the following commands...
/paper mobcaps
for global mobcaps and total spawnable chunks.
/paper playermobcaps
for player mobcaps.
Spawnable chunks are based on the number of loaded chunks and the spawn-limits as defined in bukkit.yml
(or paper-world-defaults.yml
). Please make adjustments when necessary, especially if you do not have it enabled prior.
Vanilla mob spawning is not only complicated, but also inherently flawed on multiplayer servers
For example, we have two players in the Nether dimension - Player A is AFKing high up on a Nether ceiling Piglin farm while player B is just chilling on Nether Waste biome.
Even though the spawn attempts are made on all loaded chunks around both players; a vast majority of the successful mob-spawn attempts will end up around the player with the most favorable spawning conditions.
In this case, player B will be getting most of the mobs while player A gets a little simply because there are more spawnable chunks around player B overall.
paper-world-defaults.yml/chunks.prevent-moving-into-unloaded-chunksπ
prevent-moving-into-unloaded-chunks: true
This prevents players from moving into an unloaded chunk which would otherwise cause a sync-chunk load.
When a player moves into an unloaded chunk, the server would make the task of loading the chunk with the highest priority, thus tanking the TPS.
paper-world-defaults.yml/misc.redstone-implementationπ
redstone-implementation: alternate-current
Paper provides options to specify the redstone implementation the server uses.
The available options are vanilla
, eigencraft
, and alternate-current
with Vanilla
being the default.
alternate-current implementation is more efficient and recommended, but come with possible behavioral changes. Please use with caution!
For technical details on alternate-current
, read more here.
paper-world-defaults.yml/environment.treasure-mapsπ
treasure-maps:
enabled: true
find-already-discovered:
loot-tables: default
villager-trade: true
There are several methods to further mitigate the performance issue around treasure maps as listed below.
Method 1 - OkTreasures - A plugin solution brought to you by Kyle
OkTreasures fixes map related crashes by replacing the Vanilla buried treasure search with a custom, faster, and simpler one: it randomly selects a beach within a reasonable distance and places the treasure there. Since this process is mostly asynchronous, it won't cause lag.
Method 2 - TreasureMapsPlus - A plugin solution brought to you by Machine Maker
TreasureMapsPlus is made by Machine Maker, an avid members of PaperMC project, who aims to solve the issue surrounding treasure maps with a slight behavior change. Instead of leading players to an undiscoverd treasure, the plugin simply rewards the player with the loots from the chest loottable upon using the map.
Method 3 - Limit the search radius
By toggling the villager-trade
option under find-already-discovered
to true
, it will reduce the performance impact of treasure maps. (map will no longer try to find undiscovered treasure instead returns the nearest one)
Method 4 - Completely disable treasure maps
Alternatively, you could also opt to completely disable the functionality of treasure mapss by setting enabled
to false
to prevent any issue related to the prolonged feature lookup.
Why are the treasure maps resource intensive?
Due to how Vanilla Minecraft generate/lookup new loottable from treasure map found via cartography villager or dungeon loot chest, the server may stall due to the potentially large amount of lookups done when it attemps to locate a chest that has not yet been discovered by other players.
The issue can be mitigated by using the options provided above, along with modifications to the Vanilla gameplay. However, it is sometimes necessary to prevent significant lag spikes or prolonged server stalls that could result in the server being shut down by the watchdog.
The treasure map searches up to a ~1100 block radius for buried treasures and remains blank if none is within the range.
That's a big radius!
/gamerule spawnChunkRadiusπ
Formerly known as paper-world-defaults.yml/spawn.keep-spawn-loaded
has been removed in favor of the new spawnChunkRadius
gamerule in Minecraft version 1.20.6+.
/gamerule spawnChunkRadius 2
Please be aware that unlike Vanilla Minecraft, the gamerule configuration is set on a per-world basis on a Paper server.
Example command usages:
/execute in minecraft:overworld run gamerule spawnChunkRadius 0
/execute in minecraft:the_nether run gamerule spawnChunkRadius 0
/execute in minecraft:the_end run gamerule spawnChunkRadius 0
Setting the spawnChunkRadius
to 0
would essentially disable this feature.
The range value is in chunks, and the formula for total chunks to be kept loaded is [((spawnChunkRadius+1)x2)+1]^2
With spawnChunkRadius
set to 2
, [(2+1)x2+1]^2=49
, you would constantly have 49
chunks loaded.
paper-world-defaults.yml/chunks.max-auto-save-chunks-per-tickπ
chunks:
auto-save-interval: default
max-auto-save-chunks-per-tick: 24
By default, Paper saves chunks incrementally, up to 24 chunks per tick.
This configuration option is for advanced users only and is provided here for informational purposes. The majority of servers will be fine with the default value, and no change is required. Please be extremely cautious if you decide to change the value here, as setting it incorrectly will likely result in a negative performance hit and an increased risk of data loss.
The basic formula is as follows:
max-auto-save-chunks-per-tick
x auto-save-interval
β₯ total loaded chunks that requires save
If you suspect that chunk saving is causing performance issues, please join Paper Discord with a spark report before altering the configs here.
paper-world-defaults.yml/chunks.delay-chunk-unloads-byπ
chunks:
delay-chunk-unloads-by: 10s
Paper provides finer control over how often chunks are saved and how fast they are unloaded. Lowering delay-chunk-unloads-by
value too low would actually result in additional work on the server to reloading the chunks that are just unloaded if a player happens to be hanging around an area.
The default
value here is most likely going to be the most optimal options for majority of the server owners.
paper-world-defaults.yml/tick-ratesπ
tick-rates:
behavior:
villager:
validatenearbypoi: -1
container-update: 1
dry-farmland: 1
grass-spread: 1
mob-spawner: 1
sensor:
villager:
secondarypoisensor: 40
Paper provides finer control options govorning certain ticking rates
Increase the value here will reduce the resource usage with some cost to their respective behaviors.
dry-farmland
, grass-spread
, and mob-spawner
can be adjusted to increase the interval between each check, thereby reducing their performance impact. The difference is mostly insignificant for the majority of small servers; however, it may be beneficial for servers with a large number of spawners and farmlands."
If your server is experiencing villager related performance issue, first try to play around with this config before moving onto a plugin solution.
For example you can increase secondarypoisensor
to 240
and validatenearbypoi
to 120
to save resources. The negative behavioral change is likely not noticeable.
paper-world-defaults.yml/environment.optimize-explosionsπ
optimize-explosions: false
Setting this to true will reduce the impact of calculating a large amount of explosions.
The actual real world scenario that would benefit from this is minimum; however, if your friends love to blow things up with an unholy amount of TNTs, this setting may be right for you.
In case you do really love to blow things up and noticed that your TNT detonation does not behave like vanilla, increase the max-tnt-per-tick
threshold located in spigot.yml
to remedy the issue.
Please do note that the threshold is there to safeguard your server and increase the value would also increase the risk of your server crashing in the event of large amount of TNT detonation.
paper-world-defaults.yml/entities.armor-standsπ
armor-stands:
do-collision-entity-lookups: true
tick: true
This decides whether armor stand should be ticked & accounted for collisions.
Setting these to false
will...
completely remove any armor stand related lag machines.
break plugins that utilize armor stands.
break farms such as an automatic ice maker .
paper-world-defaults.yml/lootablesπ
lootables:
auto-replenish: false
max-refills: -1
refresh-max: 2d
refresh-min: 12h
reset-seed-on-fill: true
restrict-player-reloot: true
restrict-player-reloot-time: disabled
Toggle auto-replenish
to true
if you plan on running a long-term survival server. It replenishes the chest once looted and would bring some life back to your old worlds.
max-refill
sets the maximum refills, a value of -1
will make it unlimited.
refresh-min/max
defines the amount of time passed before the chest is refilled.
This does not require the chunk to be loaded.
reset-seed-on-fill
will shuffle loot table seeds on each refill so the items inside the chest will always be different.
restrict-player-reloot
will stop the same player from camping and looting the chest multiple times.
restrict-player-reloot-time
(default disabled) can de enabled to stop the same players from looting the same chest again with a definable time.
The units of measurement here are s for seconds
, m for minutes
, h for hours
, d for days
. m is NOT for months!!
Scenario 1: If a player loots a chest once and comes back later, there will not be new loot.
Scenario 2: If player A loots a chest and then player B comes by later, the chest will be refilled and lootable for player A again.
Scenario 3: If restrict-player-reloot time
is set to 3d
, a player cannot reloot the same chest until 3 days
later.
The chest will refill regardless of the remaining items inside unless it is full.
Scenario 4: If player A opens the chest (generated the loot) and leaves the loot inside, player B that comes by later will get a set of newly generated loot plus whatever that was left by player A previously.
Scenario 5: if player A opens the chest and fill it up with diorite, player B who that comes by later will get nothing new (but diorite) because the chest is already, full thus no new loots will be generated.
paper-world-defaults.yml/feature-seeds.generate-random-seeds-for-allπ
generate-random-seeds-for-all: true
Toggling this option to true
will provide you with some level of security against seed-cracking tools, as it randomizes the sub-seed for a Minecraft world, rather than using the world seed to generate features. This is a very useful feature if you aim to prevent unfair advantages that players may gain if they manage to figure out your world seed using tools like SeedcrackerX.
Please note that this config covers features
only, for generated structures
, please manually alter the structure seeds in spigot.yml
.
(Upstream Spigot does not automatically randomize the structure seed it provides, so this part of the process remains manual)
Please note that this configuration does not affect chunks that were generated before enabling this option. For the best results, it is recommended to use this feature in a brand new world. A detailed walkthrough is provided below if you wish to make the most of this feature.
Click here to expand and follow the steps within to enable this feature properly!
- Start the server in order for the paper-world-defaults.yml file to be generated then stop the server.
- Open up paper-world-defaults.yml located inside config folder and set generate-random-seeds-for-all to true.
- Open up spigot.yml and manually input the structure seeds to your liking.
- Remove the
world
,world_nether
, andworld_the_end
folder.
(This step is needed due to/gamerule spawnChunkRadius
is set to 2 by default, so a few chunks were already generated when the server started.)
(Please double check thatlevel-seed
is not already set inserver.properties
otherwise same seed will be generated.) - BONUS: if you want to define individual feature-seeds, you can go back to paper-world-defaults.yml and set them manually.
(by default, feature-seeds are automatically randomized) - Start the server then you are good to go!
To manually define world seed, add level-seed=[seed number] line onto server.properties or edit your level.dat with NBT Editor then perform the steps above.
Once the feature is enabled, you will find a new section with randomly generated feature-seeds
listed in your paper-world-defaults.yml
& paper-world.yml
if you have any other per-world specific configs, be sure to add them under the corresponding categories.
paper-world-defaults.yml/misc.legacy-ender-pearl-behaviorπ
legacy-ender-pearl-behavior: false
Since version 1.21.3, Mojang has made ender pearls able to load chunks on their own. Setting this option to true
will disable ender pearls' ability to load chunks.
paper-global.ymlπ
Essential configurations for paper-global.yml
paper-global.yml/chunk-loading-advancedπ
chunk-loading-advanced:
auto-config-send-distance: true
player-max-concurrent-chunk-generates: 0
player-max-concurrent-chunk-loads: 0
chunk-loading-basic:
player-max-chunk-generate-rate: -1.0
player-max-chunk-load-rate: 100.0
player-max-chunk-send-rate: 75.0
Paper provides control over how chunk data is sent to players. The default values listed above should work for the majority of the server.
If you are troubleshooting chunk loading issues, please consult the #paper-help channel first for advice first, do not alter the values without fully understand what they do. Do not follow any random guide for recommended value, there is a lot of misinformation out there!
In 1.20, the chunk-loading
options have been revised and have had their old global limit configuration completely removed. The default option should now work for the majority of servers, whether big or small.
If you are experiencing slowness while loading chunks on your server, please review the following list to further troubleshoot issues related to chunk-loading. π
-
Is the map pregenerated?
If possible, ensure the entirety of the map is pregenerated. This would help ease any unnecessary strain on the server. -
Is the server overloaded?
Generating chunks is a heavy task. Paper generates chunks asynchronously, and normally, it would not be an issue unless the server hosting machine is overloaded and cannot keep up. -
Is Paper anti-xray enabled?
Anti-xray makes chunks less compressible thus increase network usage, try disabling the feature to see if the loading speed improves. -
Potential plugin related issue?
Check to make sure there are no plugins causing issues that might be holding up Netty threads. Consider Binary Search to isolate the problemic plugin. -
Possible network bottlenecks?
Monitor network usage to ensure you have enough bandwidth to sustain all player activities. -
Possible disk I/O bottleneck?
This could potentially be an issue if you are using older hardware or hosting a server with a shared host that may impose limits on your instance. -
Are players traveling at high speeds and loading a massive number of chunks?
If you have multiple players flying with elytra and rockets, or boat flying in the server, it may potentially flood the chunk system. Aside from anti-cheat, a solution such as TooManyGen may be able to help by imposing certain limits on players who are loading a lot of chunks in a short period of time.
Experience high ping or timeout issue?π
If one or more players experience higher than normal ping when they first log into the server, teleport to a new location, or switch dimensions, please review the following list for possible causes.
-
Paper sends chunks a lot faster than Vanilla Minecraft; as a result, the Minecraft client may not be able to cope and just stop rendering chunks altogether. Reduce view distance on the server may help with this particular area.
-
A lot of information is being sent to the client during the log-in process. Players with less than ideal internet speed or routing issues to your server may experience higher than normal pings during the process.
For players with extremely slow or unstable internet, ask them to reduce the view distance on the client to the minimum as it would help reducing the data sent.
For players getting timeout'd frequently, aside from asking them to get better internet, there is really not much a server owner can do to help.
As for routing issues, tools like WinMTR can help identify potential routing issues if you wish to further seek out solutions. However, keep in mind that ping is just a snapshot of latency, and the root cause of the problem may not always be apparent despite the test done.
player-max-send-rate
isnt always better. Please perform your own testing and come out with a set of value that works for your server.paper-global.yml/chunk-systemπ
chunk-system:
gen-parallelism: default
io-threads: -1
worker-threads: -1
With the introduction of chunk rewrite patch, these options are provided for server owners to fine tune the new chunk system to their needs.
Please note that the default
value is likely to be the most optimal option for the majority of servers. It is crucial not to overallocate workers as it may negatively impact server performance.
The chunk rewrite patch removes many age-old issues related to Vanilla system with an improved pipeline and alocates CPU resources for both chunk load and generations more efficiently. Chunk rewrite patch details can be found here
If you have any question, please visit Paper discord for futher assistance if needed.
just remember that the chunk system is mostly a stepping stone for other certain changes - The Rat King Spottedleaf
paper-global.yml/item-validation.bookπ
book:
author: 8192
page: 16384
title: 8192
book-size:
page-max: 2560
total-multiplier: 0.98
display-name: 8192
lore-line: 8192
resolve-selectors-in-books: false
Paper provides the options to adjust the overall size of a book. This is an useful feature to prevent bookban either on purpose or by accident (unlikely).
The value of page-max
is in bytes. It is safe to reduce the it by half or more to your liking (I.E. 640~1280
)
Additionally, you can utilize a plugin to ban non-ASCII characters in a book which is listed in Quality of Life Plugins & Tools
Per-world Configπ
All default config will now be stored inside config
folder on your Minecraft root folder.
The per-world config can now be defined in paper-world.yml
located in /[world_name]
/paper-world.yml
(The default file is empty)
Paper allows you to enforce a custom set of config in paper-world.yml
to overwrite the default value in the paper-world-defaults.yml
such as mob caps.
paper-world.yml
file is located inside each of your world folders.
The following section serves as an example to help you virtualize the file structures...
/world_the_end/paper-world.yml
entities:
spawning:
spawn-limits:
monster: 35
creature: 10
ambient: 0
axolotls: 0
underground_water_creature: 0
water_creature: 0
water_ambient: 0
/world_nether/paper-world.yml
entities:
spawning:
spawn-limits:
monster: 80
creature: -1
ambient: -1
axolotls: -1
underground_water_creature: -1
water_creature: -1
water_ambient: -1
/resource_world/paper-world.yml
entities:
spawning:
spawn-limits:
monster: 5
creature: 30
ambient: -1
axolotls: 10
underground_water_creature: -1
water_creature: -1
water_ambient: -1
In the above example, by having a lower monster
value in resource_world
, you just made the resource world a bit safer for miners and also reduced the overhead on the server by not keeping the spawn chunks loaded because they are not actively being used.
Click here to expand for additional notes...
Paper uses proper category names here as opposed to old Bukkit names for the categories.
- creature is the same as animals in bukkit.yml
- water_creature is the same as water-animals in bukkit.yml
default are options that apply to every world unless stated otherwise in the world categories.
- world is overworld
- world_nether is Nether dimension
- world_the_end is End dimension
- Additionally, if you have other custom worlds, they can also be added under world-settings.
A value of -1 means it will follow the value as defined by default. (in case of spawn-limits, by mob-cap in bukkit.yml)
YML file uses 2 spaces for indentations. Do not use tab.
Make sure the indentation is correct in tree-like structures. (two spaces for each step of indentation)
A proper yml editor will help ensure formatting isn't borked.
The console will puke up an error on startup if a mistake is made. Correct them accordingly.
Paper's own built-in Anti-Xrayπ
Paper has an efficient built-in anti-xray option to combat basic client-side resoruce pack to see hidden ores.
if you do choice to enable this feature, please follow the below post carefully.
PaperMC Anti-Xray Documentation
engine mode 1
provides the most basic protection while leaving ores exposed to air untouched.
engine mode 2 & 3
works by obscures the views by presenting fake ores to client.
Please note that on server with high concurrent player counts (100+), usage of engine mode 2
may sometimes saturated the network pipelines as more data is being sent to players. Certain players may recieve higher than normal pings on login or dimension-switching, please see the tips below for an alternative.
Can people bypass these anti-xray feature?
Without going into too many technical details, with enough effort, people may still be able to bypass the anti-xray feature due to how the Minecraft client processes the information around a player. It is still possible to bypass the anti-xray measures provided above.
Alternative Methods to prevent xrays
Method 1 - RayTraceAntiXray Plugin
If you have spare CPU threads available on your server, consider stonar96's RayTraceAntiXray addon. It provides unpassable solution with additional resource usage.
Method 2 - Manual staff audit
By combining the usage of OreAnnouncer and the preview feature from CoreProtect, staff members can audit a player's mining tunnel and easily determine if they are cheating or not (by looking for signs of unusual tunnel layouts and checking if the ores were visible to them). This method, although manual, is 100% effective and requires zero additional resources. It is likely the ideal solution for small or friendly servers.
How to Manual Audit
Step 1: Be notified by OreAnnouncer about unusual amount of ores mined.
Step 2: Teleport to the coordinates of player mining tunnel.
Step 3: Run CoreProtect commend such as /co rollback action:-block exclude:stone,deepslate,dirt,gravel,andesite,diorite,granite radius:8 time:24h #preview
If you notice the suspect digging toward ores without a line of sight, it is a strong indication that the player is using x-ray.
Addendumπ
There are many things I left out and that is not without a reason. Those other settings often introduce too much gameplay compromises or only have minimum performance improvements on a majority of small-to-medium size server. For a full list of available configs, check out the official PaperMC Documentation.
Modern Minecraft is resource demanding and there is only so much you can optimize until you gotta ask yourself, is this still worth the effort?
There is only so much you can take out of a car to make it go faster until you are left with nothing but a steering wheel and a bare chassis, the same applies to optimizing your server.
If tweaking the above-mentioned configs is not enough to help maintain a stable TPS (18~20) on your server, I will strongly suggest looking into a direct hardware upgrade as this will be the most direct way to see any further performance improvement. See Hosting Options below for more information.
At the time of writing, even with the latest hardware available, 60-80 players with close to vanilla default configs or 100 player with huge game player compromises is the hard ceiling. At that point, impose a reasonable max player limit on the server and start thinking about network expansions with multiple servers) and congratulation on your achievement!
Performance Diagnostic Toolsπ
spark Profiler
spark profiler can provide insights to potential performance issues within your server. The command usage can be found on here.
If you require help, it is handy to have a spark report that captured the performance issue ready for the helpers in Paper community to assist with your performance issues.
Click me for how to generating a meaningful report...
Avoid generating diagnostic report right after server startup as the data will be skewed.
- Allow spark to be recorded for a set duration
(The minimum recommended is 5 minutes) - The ideal time to generate a report is during the peak player activities or during the period of time when the server is lagging
- Set a proper threshold-tick in milliseconds to capture and isolate only huge lag spikes and reduce data noise.
Common Mistakesπ
Gigahertz Myth
When selecting CPUs for your Minecraft server, do not use the clock speed rating to compare two CPUs unless they are of same model and manufacture. Please refer to Gigahertz Myth for more info.
In short, select the latest cpu architecture and the highest single core thread rating model available.
Allocate more RAM =/= better performance
Server performance is largely dependant on your CPU, not RAM.
A majority of servers will be fine with 10GB
allocated regardless of player/plugin count. Any host who claims more RAM would increase your server performance is trying to upsell you for their own profit gains. Do not fall for this trap.
RAM usage is not an indication of performance issues.
RAM usage reading gathered from panels/htop is very much meaningless on a properly setup JVM. Instead, monitor your GC intervals and durations for potential issues.
High memory usage =/= Memory leak
It may be a symptom of a memory leak but is not necessarily true in most cases.
Generate a heap report during the suspected period when you think the leak is occurring with /paper heap dump
command then feed the report through Eclipse Memory Analyzer or other similar programs to troubleshoot the issue. You can also seek help in the Paper Discord.
TPS is not an accurate measurement of performance.
Instead you should pay attention to MSPT
(milliseconds per tick). Minecraft runs on a fixed rate of 20 ticks per second, so as long as your MSPT is lower than 50, you will maintain 20 TPS.
A server could show a 20 TPS average but with a high percentage of TPS lost, players may still experience lag in this scenario.
The minimum recommended thread/core count for a Minecraft server is FOUR.
While it is true that Main game loop is all done on 1 thread, there are many tasks that can benefit from having multiple threads, such as Netty, plugins, SQL databases etc.
It is recommended to have at least 4 threads/cores
for most servers. If you are shopping for a host, please take this into consideration and select your plan accordingly. A lot of the budget hosting plan is borderline unusable.
JVM Flags (A Must Have)π
Aikar's Flag (G1GC)
For the majority of Minecraft servers, both big and small, Aikar's flags for G1GC should be sufficient.
Generate a startup script with Aikar's flag with Start Script Generator here
Generational ZGC
For those using Java 21 and later, you can try the generational ZGC if G1GC does not yield good results.
The flag is very simple and requires no additional tuning, as it is already highly effective on its own. Simply instructs the JVM to use generational ZGC with two flags, as shown below.
-Xms18432M -Xmx18432M -XX:+UseZGC -XX:+ZGenerational
Ensure that Xms=Xmx. This allows the JVM to claim the entirety of the allocated RAM and minimizes the chance of OOM errors due to a misconfigured environment or incompetent host.
(Finding a good host that hornor this flag would be the most ideal, see hosting suggestions below for more details)
What about Shenandoah?
Shenandoah is designed for highly threaded environments, which do not apply to Minecraft applications. This is why it is generally not recommended. Anyone claiming otherwise should be taken with a grain of salt, especially if they do not have data to back up their claims.
Backup and Recovery Best Practiceπ
Shit happens and you wouldnt wanna be stuck in the bathroom with a shitty pants, would you? It's important to have spare pair of undies with you! Make a backup today!
Having a backup and recovery plan in place is essential.
Unexpected crashes or improper shutdowns can cause world corruption or data loss on your server. Keeping multiple copies of backups both on-site and off-site is not only crucial but also an important aspect of running a long-lasting server.
Backup solutions come in many forms. Research and consider the following options, and choose the one that is most suitable for you. Several backup options listed below provide snapshot
features that make backups incrementally, based only on the files that have changed, thus saving space and allowing multiple copies of the backup to be saved.
BorgBase
borgmatic
Kopia (supports Windows)
rsync.net
Hetzner storage box
restic
At the bare minimum, creating a tarball or zip file of the entire server folder can serve as the most basic backup solution.
On Linux, tar -czvf backup_date.tar.gz /[path]/
.
On Windows, Right Click Minecraft root folder
>Send to
>Compressed (zipped) folder
.
Quality of Life Plugins & Toolsπ
Here is my personally curated list of plugins where it may be beneficial for every server to have them.
Disclaimer: I am not sponsored by any individual or groups on the making of this list. This list is purely made with love with my personal experience with them.
LuckPerms
A must-have modern permission plugin that provides you with finer permission control without the risk of giving out the OP permission to your staff team.
EssentialsX
EssentialsX is a family of plugins that provide you with several essential features for your server.
EssentialsX-Discord
A lightweight bridge plugin that brings your MC drama from in-game chat to Discord.
Chunky
World pre-generation plugin.
ChunkyBorder
Worldborder plugin with more features than vanilla worldborder.
PureTickets
A support ticket system to manage your server drama.
EntityDetection
A simple plugin to display entity locations on the server.
A helpful tool to locate problematic entities and illegal villager orgy parties.
Vanish No Packet
Allows you to vanish with style. It's free and open source.
OpenInv
Allows you to open any player inventory, even if they are not currently online.
MiniMOTD
Customize MOTD and server icons.
TabTPS
The originalβ’ TPS bar integration with pretty RGB color.
AnnouncerPlus
Powerful and fully customizable announcer plugin.
WanderingTrades
Adds the ability to customize the wandering trader loot table.
AntiRaidFarm
A simple plugin to disable RaidFarm.
Maintenance
Enable/disable maintenance mode.
Bolt
Modern protection solution for individual blocks and entities.
VanillaTweaks
Vanillatweaks datapack but as a plugin.
TreeAssist
The only tree faller / fast leaf decay plugin that doesnt take the server down with it.
FastAsyncWorldEdit
The classic world edit plugin.
WorldGuard
The classic Anti-grief plugin.
FancyHolograms
A modern hologram plugin that supports display entity.
FarmControl
The solution to overpopulated farms.
MobLimit
Similar to Farm Control mentioned above. (You will only need one or the other)
Insights
An anti-redstone griefing and block limitor plugin.
An useful tool to locate potential lag machine.
spark
A must-have profiler plugin that provides you with more insights on server performance.
beanstalk
A temporary flight management plugin.
BlueMap
A map plugin that provides a 3D render of your server.
squaremap
A lightweight Vanilla-themed 2D map with fast render speed that is also highly optimized.
ViaVersion (also known as ViaVersion)
A useful plugin during each major Minecraft updates.
You can config this plugin to allow players from newer version of Minecraft to join the server while you wait for the stable Paper version to be published.
UnifiedMetrics
A feature-rich metrics collection plugin for Minecraft server made by a weeb.
DecentHolograms
A hologram plugin that does not put a hole in server performance.
AntiVillagerLag
A simple plugin to reduce villager lag without breaking restocking mechanic.
AntiBookBan
A simple plugin to disallow non-ASCII characters in books, thus preventing bookban exploits.
CoreProtect
A grief management plugin.
OreAnnouncer
An alternative to anti-xray, this plugin notifies you on blocks mined.
Vault
Abstraction Library.
Random Teleport
A random teleport plugin.
ChestShop
Simple chest shop plugin.
Community-made Plugins Designed to Address Particular Issues.
TooManyGen
A community-made plugin to limit players ability to generate chunks.
details
Otherside
A community-made plugin to fix portal-based farms.
details
OkTreasures
A community-made plugin to mitigate performance issue related to treasure maps.
details
TreasureMapsPlus
Another community-made plugin to mitigate performance issue related to treasure maps.
details
harderdespawn
A community solution to the hard despawn range dilemma.
(Make obsolete in 1.21.1)
details
Custom World Generation Tools
Terralith
A feature packed custom world generation datapack that works well with Paper.
Useful Server Administrator Tools
Item Command Converter
In 1.20.5+, Mojang has moved from unstructured NBT to Item Components. This tool provided by PaperMC help you convert old item commands to the new format.
MCA Selector
A tool to view, trim, and alter your chunk data offline.
Please ensure that you have a proper backup before you perform any action with this tool.
Axiom
An all-in-one tool for editing Minecraft world with powerful features.
Minecraft Server Tools
A collection of useful tools for server admins such as server.properties creator, Whlitelist creator, and Votifier tester.
HelpChat Toolbox
A collection of useful tools for server admins such as Yaml validator, and chat format convertor.
Amulet Editor
A modern Minecraft world editor that allows external edits of your world.
Web NBT Editor
A simple tool to view and edit NBT files.
World Size Calculator
A tool to estimate the file size of a given world.
Chunker Bedrock/JAVA world converter
An experimental tool to convert your world between the two version.
Moreover, there are client side mods that aim to improve the Vanilla gameplay experience and are highly recommended for players who may want to have the best gameplay experience possible. However, it does not align with the topic of this blog post, instead, you can check it out here Minecraft Client Optimization mods
Things to Avoidπ
Avoid MobStacker plugin
Mobstacking is an inherently flawed idea. Spawning mob consumes server resources, with mobstacking enabled, the server would never reach mob cap and could potentially be stuck in the endless loop of spawning hell.
Combined with seemingly zero decently coded stacker plugins, stacking mob should be avoided at all cost.
Avoid lag removing or performance enhancing plugins
Fix the root cause of the performance problem instead of masking it.
Plugins such as ClearLagg or EntityTrackerFixer (ETF) introduce gameplay inconsistencies, create unnecessary work for already existing tasks (such as clearing ground items, and untracking entities), and would sometimes cause permanent damages to your world (ETF would remove AI from entities causing them to have permanent brain damage even after the plugin is removed).
Do NOT allow your players to relocate spawners
Being able to silktouch spawner is often requested by players; however, it is not a great idea considering spawners are basically a built-in lag machine when enough of them are gathered together. For the sake of server performance, do not allow your player to relocate spawners.
Do NOT use datapacks with repeat/recurrent functions
Datapack with repeating functions will impose a performance hit and should be avoided at all cost.
Find plugin replacement of the datapack features you wish to have.
Do NOT source your plugin from BlackSpigot, builtbybit, a random individual, or any other unknown sources
You wouldnt get your breakfast sausage from a random stranger on the backside of your local gas station, would you? Same thing applies to sourcing your plugins.
Practice your due diligence to audit the codebase or the developer to ensure the resource you get is clean. Websites mentioned above often contains poorly made resources, tinted (contains backdoors) or outright illegal/stolen codes due to a combination of poor moderations and sometimes outright shady companies.
To take it lightly, your server may take a huge performance hit by poorly-made plugins, or worse be invaded by griefers via built-in backdoors, even worse, your server itself may be taken over for other malicious activities.
Obtain your plugins only from reputable sites such as GitHub or Modrinth.
Do NOT auto-update your Paper.jar
The Paper development cycle does not include a proper release/beta versioning scheme so occasionally a bad build may slip through the cracks on to release. Automation provides convenience but you should not blindly download the latest Paper jar for use in any production environment.
Do NOT use anti-Fabric plugin
A growing number of server owners have the misguided idea that blocking non-Vanilla clients will reduce the amount of cheaters in the server. This is completely false. Majority of Fabric client users are after the optimization mods the eco system provides. By using plugin such as gProtector or Advanced Security, you are not only blocking legitmate players but also allowing the cheaters and dishonest hacked clients to run freely in your server due to the fact that any competent cheat developer will disguise their client as Vanilla. As a result, using anti-Fabric plugin will only harm your own community in the end.
Anti-cheat plugin is NOT a must
The best anti-cheat is a mature community.
Catching the cheaters is a cat and mouse game and an on-going arm race between the anti-cheat and the hack client developers. There is not a singular plugin, paid or not, that would catch them all and never will be due to the sheer amount of things Minecraft just "trust the client." Focus on the community building aspect and create an envioment where cheaters are outed and casted away from the community combined with an active staff audits will always be the most effective way of moderating your server and keeping the game fair for everyone.
Avoid using plugins to disable chat report feature
There had been concerns around the newly implmented chat report features in the recent Minecraft versions. The bogus amount of misinformation and crazy conspiracy theory around it was very concerning; thanksfuly, a few months has passed and there had been no report of any severe issue and most of the concerns around it is either debunked or proven to be outright false infromation. With that being said, there are a few plugins on the market claiming to disable this safety feature; however, some of them are implmented badly and could cause potential issues on your server. If you do choose to go against this advice and still want to disable chat report, the only somewhat decently made chat report disabling plugin is FreedomChat. Please avoid using anything else.
The chat reporting feature is designed to keep your player base safe from the worse offenders of the community. It is important to educate yourself as a server owner and not fall for the misinformation and understand that going out of your way to disalbe chat report feature is a net negative to your community.
The Famous Minecraft List of Shame by the popular Twitch streamer Knenytv
Avoid everything in this list whenever applicable.
Hosting Optionsπ
Here is a general checklist that you can utilize when picking a quality server host
- CPU model is labelled clearly on the plan.
(I personally wouldnt settle for for anything older than AMD Ryzen 3900)
(A generational leap is significant. Generally, looking for a newer CPU that is marketed toward gaming will be the most suitable for Minecraft, as these tend to have higher single-core performance.) - The host honors "Aikar's Flags" by default and allow you to set your
Xmx
equal toXms
.
(Ask your potential host candidates about this, if they don't know what Aikar's Flag is, run and run fast, additional explanation is located below under premium host) - The host has publicly available node status for system resource usage.
If a host matches all above requirements, it will be a decent one!
Disclaimer: I am not sponsored by any individual or groups on the making of this list. This list is purely made with love with my personal experience and community input
There are several available options when it comes to hosting a Minecraft servers.
Please read and understand the limitations of different setup below by clicking each category.
Dedicated Server (Baremetal)
Premium Shared Host
A managed service where you are sharing resources with other Minecraft servers
You are welcome to ask in the Paper Discord for recommendation from the community.
Ideal for medium size communities (5~50 players) on select plans.
Try your best to find hosts that allow you to utilize Aikar's Flag by default and allow your JVM instance to claim the RAM in its entirety. It is by no mean a guarantee for performance, but it serves as an indication that they are probably not overselling their machine.
Oracle Cloud Free Tier
Free and very fast cloud instance with a catch.
ARM based A1 instance may not be available for your region due to the recent popularity spike.
However, it never hurts to try your luck.
Read this blog post carefully for more info
Ideal for small community or proof-of-concept testing servers.
If you do opt for this hosting option, please note that your instance will/may be disabled after 60 days from the beginning of the trial period. MAKE SURE YOU HAVE A BOOT VOLUME BACKUP READY and recreate the instance if it does get deleted.
VPS
Virtual Private Server
It may sound like a good deal on paper but VPS are often not as great of value as the above mentioned Shared Host, as the hardware tends to be dated and the whole VPS industry is more geared toward webhosting and other less CPU intensive workloads.
Ideal for... ugh your mileage varies. If you still prefer this option, find a host that specialized in high-end game server hosting instead of the general purpose one.
Budget Host
A cheaper alternative of shared host with much lower performance.
Similar to shared hosts above, but is a lot cheaper. They turn a profit by staffing as many servers as physically possible into one physical machine (this is called overselling)
Those types of hosts often spend the most on advertising and have extensive teams on social media to promote their service. Huge discounts or coupons are often offered to drive sales.
They often prey on uneducated users and here are a few easy ways to identify them in the wild.
- If the CPU model is not clearly labeled on the plan.
- If they are advertising plans based on maximum player count.
- If they are upselling RAM as a performance booster.
- If they offer unlimited storage.
- If they have a discount deal all year round.
- If Xms=128M is present in your JVM flags
(You can locate this info on the spark report or server panel)
Ideal for 5~20 players.
Due to common overselling practice, the server may perform poorly during the peak hours where the machine may struggle to handle the workload.
Your server may also suffer sudden performance drop due to no fault of your own but simply being located in an overcrowded environment where another Minecraft instance may be overloading the machine.
Please do your due diligence to avoid "Summer Host"
The term "Summer Host" comes from the fresh/new hosting companies that appear during the summer school break where the demand for Minecraft servers peaks. Majority of the summer host will disappear or become inactive once the demand declines, only to be resurrected next year with a brand new name.
Free Host
If you are not paying for the product you are the product
Through clever marketing, some hosting companies are able to offer free servers with very limited resources to everyone.
They profit from the massive amount of user base they hold and outsource the risk of starting a server to those who dare to pay them for premium plans. Some have advertisements on their panels or inside your servers.
Free hosts often impose heavy restrictions to their service such as JVM flags, yml configs, plugins, and offer no ability to transfer the file out. You are buying into their ecosystem and you are the product they are selling.
Ideal for people with no money.
Self hosted
Hosting at home
If you could ignore the potential security implications of exposing your home IP to the public and the risk of being DDOS'd by your friends, this is a workable option. However, it is strongly discouraged.
If you still want to give it a try,
How to self-host a Paper server on Windows.
check out Syscraft's helpful Guide by Larry.
Ideal for a private group of close friends. (heavily dependent on your hardware)
Raspberry pi
A perfect solution for those who prefer pain and suffering. In truth, A Raspberry Pi is just not powerful enough to run on modern Minecraft version without making tons of gameplay compromises.
Ideal for a small community with less than 5 concurrent players online.
Domain and Service Record (SRV)π
If you own a domain, you can set up an A record and a service record (SRV) to have a prettier and easier to remember server address.
Instead of having 192.168.1.1:25555
displayed as your server address, you can get minecraft.yourdomain.com
.
To do this, you will need an A record
and a SRV record
.
In this scenario www.yourdomain.com
is your domain and you want to create mc.yourdomain.com
as your server address instead of 192.168.1.1:25555
.
Step 1: Create an A record
that points the hostname mc.yourdomain.com
to your server's public IP address.
Step 2: Create a SRV record
with the hostname _minecraft._tcp.mc.yourdomain.com
There will be options to set up priority
, weight
, port
, and target
.
You will set them as 0
, 0
, 25555
, mc.yourdomain.com
accordingly.
If you are running Minecraft on the default port
(25565
), only an A record
is needed.
(The above example is provided for server that is on a shared host or is running on non-default ports)
Some ISP DNS do not honor SRV record
, so your mileage may vary if you choose to run on non-standard 25565
port.
Advanced tips: A CNAME record can be used to point to your existing domain A record instead if you do not wish to deal with the protential IP changes later down the road.
Closing Notes
Wow you made it this far, I hope you did not skip anything. The original idea of this guide was to make it as simple as possible for beginners who are just stepping their foot into the Minecraft server hosting. In the writing process, I tried to simplify things, please do let me know if something can be explained better or improved. I would love to keep this guide as accurate and as up-to-date as possible, so if you do find any mistake, please contact me via Discord @EterNity, or by email [email protected]
Additional reading:
Do you own a small-scale community? Do you run a Vanilla-like Minecraft server and worry about the behavioral changes from CraftBukkit/Paper? Check out the post below!
Special Thanks
kennytv to sit through entire guide for grammar errors.
Puremin0rez for structure and grammar corrections.
Aurora for early re-visioning and grammar corrections.
NoahvdAa for materials suggestions.
Helpful Links
GitHub: https://github.com/PaperMC
Discord: https://discord.gg/PaperMC
Forum: https://forums.papermc.io
Wiki: https://docs.papermc.io
JavaDocs: https://jd.papermc.io
Donate: https://papermc.io/sponsors