Paper has dozens of configuration options spread across several files. Most admins never touch them. Here are the ones that matter for performance, with the key names and defaults from the current PaperMC configuration reference, and what each change costs you in gameplay.
config/paper-global.yml
Chunk Loading Limits
chunk-loading-basic:
player-max-chunk-generate-rate: -1.0
player-max-chunk-load-rate: 100.0
player-max-chunk-send-rate: 75.0
chunk-loading-advanced:
auto-config-send-distance: true
player-max-concurrent-chunk-generates: 0
player-max-concurrent-chunk-loads: 0
These are the defaults. player-max-chunk-generate-rate is "the maximum rate at which chunks will generate for any individual player", and -1 means no limit. Setting a limit, for example 10.0, stops a single player on an elytra from keeping the chunk generator busy on their own. The trade-off is that fast travellers see terrain appear more slowly at the edge of their view. Pre-generating your world removes most of this problem at the source.
Packet Limiter
packet-limiter:
kick-message: '<red><lang:disconnect.exceeded_packet_rate>'
all-packets:
action: KICK
interval: 7.0
max-packet-rate: 500.0
This limits how many packets one player may send within the interval, and kicks players who go over. It protects the server against clients that spam packets. Paper's default file also contains an override for the recipe book packet (minecraft:place_recipe) under overrides. Leave the defaults alone unless you have a concrete reason, because a limit that is too tight kicks normal players.
config/paper-world-defaults.yml
Arrow Despawn
entities:
spawning:
creative-arrow-despawn-rate: 60
non-player-arrow-despawn-rate: 60
The default for both is default, which keeps vanilla behaviour. In spigot.yml, the general arrow-despawn-rate is 1200 ticks, one minute. Setting these two to 60 ticks (3 seconds) removes arrows fired by skeletons and by creative players much sooner, which cuts down on entities around skeleton farms and busy PvP arenas. Arrows fired by survival players are not affected.
Mob Caps
entities:
spawning:
spawn-limits:
monster: 50
creature: -1
ambient: -1
axolotls: -1
underground_water_creature: -1
water_creature: -1
water_ambient: -1
In Paper's world config every value defaults to -1, which means "use the value from bukkit.yml". There the monster limit is 70 (bukkit.yml reference). Lowering it to 50 means fewer hostile mobs to run AI for. Players will see slightly fewer mobs at night and mob farms will produce less, so check with your community before you change it.
Hopper Optimization
hopper:
cooldown-when-full: true
disable-move-event: false
ignore-occluding-blocks: false
These are the defaults. cooldown-when-full: true makes Paper "apply a short cooldown when the hopper is full" instead of retrying every tick, so it is already on unless someone turned it off. disable-move-event: true removes the InventoryMoveItemEvent for hoppers entirely. That saves work on servers with huge sorting systems, but plugins that listen to the event, such as chest protection or shop plugins, stop seeing hopper transfers.
spigot.yml
Activation Ranges
world-settings:
default:
entity-activation-range:
animals: 32
monsters: 32
raiders: 64
misc: 16
water: 16
villagers: 32
flying-monsters: 32
tick-inactive-villagers: true
These are the defaults from the spigot.yml reference. Activation ranges control how far from a player entities are fully ticked (pathfinding, targeting and so on). Entities outside their range are only woken up now and then.
Lowering ranges saves CPU, and the price is paid in gameplay:
| Setting | Default | A common lower value | What players notice |
|---|---|---|---|
| animals | 32 | 16 | Animals farther away stand still, animal farms slow down when nobody is near |
| monsters | 32 | 24 | Monsters react later, some mob farms produce less |
| misc | 16 | 8 | Items and other small entities are processed less often at a distance |
How much CPU this saves depends on how many entities your worlds hold. Measure before and after (see below).
Item and XP Merging
world-settings:
default:
merge-radius:
item: 0.5
exp: -1
Paper's docs list item: 0.5 and exp: -1 as the defaults. item is "the range, in blocks, that items will combine within". exp only affects XP orbs as they spawn, and -1 turns that merging off. Raising the item radius to a few blocks means fewer separate item entities on the ground around mob farms, and players may see items jump together from a short distance.
Measuring Your Results
Paper has bundled spark since 1.21 (PaperMC docs). Take a baseline at a normal busy time, change one thing, restart, and measure again at a similar time with a similar number of players.
/spark tps
/spark tickmonitor --threshold-tick 50
/spark profiler start --timeout 600
/spark tps gives you TPS and tick times (MSPT). The tick monitor reports every tick that goes over 50 ms, the full budget for one tick at 20 TPS. The profiler shows what the server spent its time on, so you can see whether the part you changed actually got smaller. Write the median and 95th percentile MSPT down for each run.
Hardware sets the ceiling, configuration decides how close you get to it. On Space-Node the CPU depends on the location and tier you choose, and the plan selector shows it for each location before you order.