Paper World Configuration: Performance Settings in paper-world-defaults.yml
Paper moves many of Vanilla's behaviours into a per-world file, paper-world-defaults.yml, so you can tune a busy server without a plugin. The catch is that there are many options, and most of the defaults are already sensible. This guide lists the ones that relate to performance, with the defaults the Paper documentation gives, and says which are worth changing.
It was checked on 2026-11-15 against the Paper world configuration reference. Version differences are possible, so open the file your server generated and compare. View distance and simulation distance are not in this file. They are in server.properties, covered in the server.properties guide.
- Measure first. Use spark to find what is actually slow before you change anything. See the lag guide.
- The safest options to adjust are mob spawn limits, despawn ranges and
max-entity-collisions. hopper.disable-move-eventimproves performance but breaks protection plugins that rely on the event.unsupported-settingsare at your own risk.- Change one thing at a time, restart, and compare. Back up the file before editing.
On this page
Where the file is and how to edit it
Defaults for every world live in paper-world-defaults.yml. A single world or dimension can override them in its own paper-world.yml. On ChicagoServers, find them on the Files tab: the defaults should be in the server's config folder, and per-world files are inside the world folder. Back up first, edit with spaces and not tabs, then Save and Restart. Check the Console tab for YAML errors.
Chunks: loading, unloading and saving
| Option | Default | What it does |
|---|---|---|
chunks.auto-save-interval | default | Uses the autosave interval from bukkit.yml. |
chunks.max-auto-save-chunks-per-tick | 24 | Limits how many chunks are autosaved per tick. |
chunks.delay-chunk-unloads-by | 10s | How long a chunk stays loaded after players leave. |
chunks.min-chunk-unload-count / min-chunk-unload-fraction | 50 / 0.05 | Thresholds for how many chunks are unloaded at once. |
chunks.flush-regions-on-save | false | Paper notes it may affect performance. |
chunks.prevent-moving-into-unloaded-chunks | false | Stops players moving into chunks that are not loaded. |
These rarely need changes. max-auto-save-chunks-per-tick limits how many chunks are autosaved each tick, so a lower value spreads saving over more ticks. Test it before you keep it. Generating terrain is a bigger cost than saving it, so also see the Chunky pre-generation guide.
Mob spawning and despawning
| Option | Default | What it does |
|---|---|---|
entities.spawning.spawn-limits | all -1 | Per category caps: ambient, axolotls, creature, monster, underground_water_creature, water_ambient and water_creature. -1 uses the bukkit.yml values. |
entities.spawning.ticks-per-spawn | all -1 | Spawn rate for the same seven categories. -1 uses the bukkit.yml rates. |
per-player-mob-spawns | true | Spreads the spawn limit between players. |
count-all-mobs-for-spawning | false | Whether every mob counts toward the cap. |
despawn-range-shape | ELLIPSOID | Shape of the despawn area. CYLINDER is the alternative. |
despawn-ranges | default | Hard and soft despawn distances, horizontal and vertical, for each mob category. |
despawn-time | disabled per entity | Optional despawn time per entity type. |
monster-spawn-max-light-level | default | Maximum light level monsters can spawn in. |
If your mob count is the cost, lower spawn-limits for the categories that dominate, or shorten the despawn-ranges. Both change gameplay a little, so tell players.
Entities, collisions and tick rates
| Option | Default | What it does |
|---|---|---|
collisions.max-entity-collisions | 8 | Caps how many collisions an entity processes. Lowering it reduces collision work where many entities are packed together. |
collisions.only-players-collide | false | Limits collisions to players. |
collisions.allow-player-cramming-damage | false | Whether player cramming damages players. |
entities.tracking-range-y.enabled | false | Turns on a separate vertical tracking range for entity types. |
entities.inactive-mob-goal-selector-throttle-rate | disabled | Throttles inactive mob AI. |
entities.armor-stands.tick / markers.tick | true | Whether armor stands and markers tick. |
tick-rates.mob-spawner | 1 | Spawner tick rate. A value of -1 disables all spawners. |
tick-rates.container-update, dry-farmland, wet-farmland, grass-spread | 1 | How often each is processed. |
Hoppers, redstone and explosions
| Option | Default | What it does |
|---|---|---|
hopper.cooldown-when-full | true | Applies a cooldown when a hopper is full. |
hopper.disable-move-event | false | Disabling improves performance but breaks protection plugins that rely on the event. |
hopper.ignore-occluding-blocks | false | Ignores blocks that would occlude the hopper. |
misc.redstone-implementation | VANILLA | Options are VANILLA, EIGENCRAFT and ALTERNATE_CURRENT. |
misc.update-pathfinding-on-block-update | true | Paper notes that disabling can noticeably improve performance. |
environment.optimize-explosions | false | Optimises explosion calculations. |
environment.max-block-ticks / max-fluid-ticks | 65536 | Caps scheduled block and fluid ticks. |
environment.disable-thunder | false | Disables thunderstorms. |
Redstone engines can change how contraptions behave, so a technical community should be asked before you switch.
Settings to leave alone
Paper groups a few options under unsupported-settings, including disable-world-ticking-when-empty, ticking.chunks and ticking.block-entities. They are labelled use at your own risk, so leave them at their defaults unless you have a specific reason and a backup.
A safe tuning routine
- Run a spark profile while the lag is happening and note the top cost.
- Pick the one option that relates to that cost.
- Back up the file, change that option, save, and restart.
- Profile again at a similar load and compare.
- Keep the change only if it helped, and write down what you changed.
Plugins can also be a cause of lag. See the plugin install guide, and for memory sizing how much RAM a Minecraft server needs. Looking for a host? See Minecraft server hosting.
Frequently asked questions
Where is Paper's world configuration file?
Defaults are in paper-world-defaults.yml in the server's config folder. A world or dimension can override them in its own paper-world.yml.
How do I reduce mob lag on Paper?
Lower the spawn-limits for the categories that dominate and shorten despawn-ranges, after profiling to confirm mobs are the cost.
What does max-entity-collisions do in Paper?
It caps how many collisions an entity processes. The default is 8, and lowering it helps crowded farms.
Is it safe to disable the hopper move event in Paper?
It improves performance but breaks protection plugins that rely on the event, so only do it if you do not use them.
Does Paper's world config include view distance?
No. View distance and simulation distance are in server.properties.