On this page
- Measure the lag before changing settings
- Use the file and console controls for your server
- Lower view distance and simulation distance separately
- Target entity activity before cutting every mob limit
- Test Paper's hopper, explosion and redstone settings
- Keep hopper event compatibility in view
- Test explosion caching where explosions matter
- Evaluate the redstone implementation on a test copy
- Leave default chunk threads alone until you have evidence
- Keep only changes that improve the measured problem
Key takeaways
5- Profile during actual lag and save a baseline before changing settings.
- View distance controls terrain sent to players; simulation distance controls nearby living entity updates.
- Check spigot.yml for world distance overrides before editing server.properties.
- Disabling hopper movement events can improve performance but affects plugins that listen for those events.
- Test one change at a time and retain it only when measurements and gameplay checks support it.
This guide is for Paper server owners who want to reduce lag without changing gameplay blindly. You will establish a performance baseline, test lower chunk distances and make targeted configuration changes, then use measurements to decide what to keep.
Measure the lag before changing settings
Paper uses several configuration files, including server.properties, spigot.yml and its own world and global settings. If you are still preparing your first installation, follow our Paper server setup guide before tuning it.
Start with spark, a free profiler with CPU profiling, memory inspection and server health reporting. Paper bundles it from Minecraft 1.21 onward, and its documentation recommends spark for profiling.
Take the first recording while players are experiencing the problem. A quiet test with nobody online is a poor comparison for a crowded evening.
- Record the player count, what players are doing and when the lag occurs.
- Use
spark tpsandspark healthto capture the server's condition. - Start a ten-minute profile with
spark profiler start --timeout 600. - Keep the report link and repeat the measurement after each change under similar conditions.
Use the file and console controls for your server
Use the workflow below for the configuration tests in this guide. Keep a copy of each original file so that you can reverse an unsuccessful change.
- Open your server console and run the baseline commands below.
- Stop the server through its console before applying a file change. From the server directory, copy the affected files to a separate backup location.
- Edit
server.properties,spigot.ymlor the relevant file underconfig/with your text editor. - Start the server using your normal startup method. Repeat the measurements in the server console while the problem is occurring.
spark tps
spark health
spark profiler start --timeout 600- Open the Console and run the baseline commands below.
- Stop the server, then use the File Manager to download copies of the files you will change.
- Edit the relevant file in the File Manager and save it. If the host restricts access to that file, ask the host to apply the change.
- Start the server and repeat the measurements in the Console under comparable player activity.
spark tps
spark health
spark profiler start --timeout 600- Open the console and run the baseline commands below.
- Stop the server. Use the Files / FTP page to download copies of the files you will edit.
- Update the relevant configuration file through Files / FTP. Ask the host if its panel prevents access to a setting.
- Start the server and repeat the measurements in the console during comparable player activity.
spark tps
spark health
spark profiler start --timeout 600The profiler provides a shareable report link. Save the before and after links alongside a short record of the setting you changed.
Lower view distance and simulation distance separately
These settings control different work. The server.properties reference lists a default of 10 and a range of 3 to 32 for both.
| Setting | What it controls | What to assess during testing |
|---|---|---|
view-distance | The radius in chunks of world data sent to each player. | How much surrounding terrain players can see. |
simulation-distance | The radius in chunks within which living entities are updated. | Whether the server's farms and other entity-dependent activities still behave acceptably. |
For an initial experiment, you could test these values in server.properties:
view-distance=8
simulation-distance=6These are example test values, not an official recommendation or a target every server should use. For clearer results, change simulation distance first, measure it, then test view distance separately.
Paper also reads the per-world distance settings in spigot.yml. According to its Spigot configuration referenceSource site, default or -1 inherits the corresponding value from server.properties. Check for an explicit world override before assuming the properties file controls that world.
- Record the current properties values and any explicit world overrides.
- Apply one lower distance using the workflow above.
- Ask players to test the activities that matter to your server.
- Compare the measurements and keep the lower value only if the tradeoff suits your gameplay.
Target entity activity before cutting every mob limit
In spigot.yml, entity-activation-range controls how close entities must be to players to receive their normal ticking frequency. Outside that range, entities tick less often.
The documented defaults include 32 blocks for animals, monsters and villagers, 64 for raiders, and 16 for water and miscellaneous entities. Treat those categories separately rather than applying one number to everything.
- If you test a lower villager activation range, include trading areas and villager-dependent farms in the gameplay checks.
- If you change monster activation ranges, test the combat and farm areas your players actually use.
- Keep the original values available and reverse the change if the gameplay cost outweighs the measured improvement.
Activation range is different from tracking range. The latter controls entity visibility distances, and Paper's reference says those distances are also scaled by entity-broadcast-range-percentage in server.properties. Do not treat a visibility adjustment as the same experiment as reducing entity activity.
Paper's per-player-mob-spawns setting defaults to true, counting the mob cap per player rather than across the whole server. Keep that behavior in mind when assessing mob changes with different numbers of players online.
Test Paper's hopper, explosion and redstone settings
The settings below belong to config/paper-world-defaults.yml. Use the Paper world configuration referenceSource site for their placement, and edit the existing entries rather than adding a second copy elsewhere.
Keep hopper event compatibility in view
hopper.cooldown-when-full defaults to true and gives full hoppers a short cooldown. Check its current value before looking for more aggressive changes.
hopper.disable-move-event defaults to false. Enabling it skips InventoryMoveItemEvent, which the documentation identifies as a substantial hopper performance improvement.
Test explosion caching where explosions matter
environment.optimize-explosions defaults to false. When enabled, it caches entity lookups during an explosion instead of recalculating them. If explosions are part of the workload you are investigating, test this setting with that activity represented in the profile.
Evaluate the redstone implementation on a test copy
misc.redstone-implementation defaults to VANILLA. Paper documents ALTERNATE_CURRENT as an option that can greatly reduce lag from redstone dust.
Make this a separate experiment. Have players test their important redstone builds before deciding whether to retain it.
Leave default chunk threads alone until you have evidence
Paper's global settings are in config/paper-global.yml. Its global configuration referenceSource site lists chunk-system.io-threads and chunk-system.worker-threads as -1 by default. A negative io-threads value uses a single thread, while a negative worker-threads value selects the thread count automatically based on available physical CPU cores.
Leave those default settings in place for the first round of testing. Increasing thread counts without a specific reason adds another variable to the investigation.
There are separate controls for chunk loading, generation and sending. Their documented defaults include player-max-chunk-load-rate: 100, player-max-chunk-generate-rate: -1.0 and player-max-chunk-send-rate: 75. The generation value means no limit.
Record these values if you investigate chunk work, but avoid replacing them all with a copied preset. For a separate walkthrough of pregeneration and profiling, follow our Chunky and spark guide.
Keep only changes that improve the measured problem
Run another profile while the original lag is happening. Compare TPS, tick time and the health report with your baseline, alongside player feedback about visibility, farms and redstone.
- Keep: a change that improves the measurements and preserves the gameplay you need.
- Reverse: a change that causes unacceptable behavior or provides no useful improvement.
- Investigate further: a result collected under substantially different activity or player counts.
Keep a short change log with the original value, test value, report links and decision. That gives our team and your other administrators a concrete starting point when the next performance problem appears.
Frequently asked questions
What is the difference between view distance and simulation distance?
View distance sets the radius in chunks of world data sent to each player. Simulation distance sets the radius within which living entities are updated. Both default to 10 in server.properties, but they control different work.
What view distance and simulation distance should a Paper server use?
Choose values through testing rather than treating a preset as a requirement. View distance 8 and simulation distance 6 are example test values, not official recommendations. Change them separately and compare performance and gameplay under similar player activity.
Why did changing server.properties not change my world's distance?
Check the world's distance settings in spigot.yml for an explicit override. Paper's reference says default or -1 uses the corresponding server.properties value. Record both locations before making another adjustment.
How do I find what is causing lag on Paper?
Paper bundles spark from Minecraft 1.21 onward. During the problem, use /spark health and start a recording with /spark profiler start --timeout 600. Save the report link and compare it with a recording after your change under similar activity.
Do Aikar's flags fix low TPS?
Aikar's flags tune G1 garbage collection and are intended to reduce lag spikes. They should not be treated as a fix for every tick performance problem. Profile the workload first and consult Paper's flags documentation before planning a separate startup configuration change.
