Paper ships with dozens of configuration files, and most server owners either leave them untouched or change ten values at once because a forum post told them to. This guide exists to make the second option unnecessary. It maps every file to the folder it actually lives in, ranks the settings that still matter on modern Paper builds, and shows the measurement loop that tells you whether a change helped or just felt like it did.

It is written for owners and administrators who already know what TPS means and now want to stop guessing. The numbers below come from our own Paper 26.2 lab server, where we loaded thousands of hoppers and hopper minecarts and sampled tick times once per second, and every recommendation was checked against the official Paper configuration reference. Nothing here is copied from a 2019 flag list.

The File Map: Where Each Config Actually Lives

The first reason config advice fails is that it points at the wrong file. Paper still reads the old Bukkit and Spigot files for backward compatibility, but the interesting settings moved, and a value in the wrong place is silently ignored. Here is the layout after a first start on a current Paper build, with the split introduced in 1.19 and kept through the 26.x line.

• server.properties in the server root. Vanilla settings: view distance, simulation distance, online mode, difficulty, max players.
• bukkit.yml and spigot.yml in the server root. Legacy Spigot settings that Paper still honors: spawn limits per world, merge radius, entity collisions, tick catch-up.
• config/paper-global.yml. Paper only, server wide: hopper behavior, chunk loading threads, packet limits, proxy forwarding, console filters.
• config/paper-world-defaults.yml. Paper only, applies to every world that does not override it: spawning, anti-xray, entity activation ranges, despawn behavior.
• config/paper-world.yml inside a <world name>/ folder. A per-world override that wins over the defaults file for that world only.

On first boot Paper writes all of these for you, including the config/ folder. It also refuses to start when it finds an unknown key in a Paper file, and the console error names the file and the key, which is the fastest way to find a typo or a setting that no longer exists in your version.

What Each File Controls and What It Costs You

Use the table as a triage sheet. The risk column is not about crashing the server, it is about how likely a change is to produce behavior players notice and complain about before you notice the tick time.

File	Controls	Top settings worth touching	Typical risk
server.properties	Vanilla world and network behavior	view-distance, simulation-distance, max-players	Low, but directly rewrites player experience
bukkit.yml	Per-world spawn limits, chunk GC	spawn-limits, chunk-gc.period-in-ticks	Medium: mob farms stop working as designed
spigot.yml	Entity merging, collisions, spawn range	merge-radius, max-entity-collisions, mob-spawn-range	Medium: visual glitches and laggy-looking mobs
config/paper-global.yml	Paper server-wide behavior	hopper.cooldown-when-full, hopper.disable-move-event	High for hopper flags: plugins listen to move events
config/paper-world-defaults.yml	Per-world Paper defaults	entities.spawning.spawn-limits, entity-per-chunk-save-limit	Medium: interacts with datapack spawn caps
<world>/paper-world.yml	One world, overrides defaults	Anti-xray, spawning, despawn ranges	Low, but confuses anyone reading only the defaults file

Two of those rows deserve emphasis. server.properties is where the biggest wins hide, and we covered the tradeoff between view distance and simulation distance in detail because reducing simulation distance cuts tick work without changing what players can see. The Paper files come second: they tune the cost of mechanics you have already chosen to run.

Measured: What Hoppers Really Cost on Paper 26.2

Hopper advice is usually folklore, so we tested it. On our Paper 26.2 lab (Java 25.0.4.1, -Xms2G -Xmx4G, G1GC, no plugins), we loaded 4,489 block hoppers and hopper minecarts on dedicated sky decks and sampled /tick query once per second for ten minutes per scenario. Sky decks mean nothing else was loaded, so the delta is the hoppers and almost nothing else.

Scenario	Added tick time	Reading
Idle server, no hoppers	~0.5 ms	Baseline
4,489 idle block hoppers	+4.3 ms	Roughly 0.001 ms each
1,000 empty hopper minecarts	+12.3 ms	Expensive per entity
3,000 empty hopper minecarts	+19.2 ms	Close to half the 50 ms tick
Same carts, 5 stacks of 32 vs 64	+1.6 ms extra	Inventory size is second order

The pattern is clear enough to plan around. Block hoppers idling above air are cheap because Paper skips their transfer attempt when there is nothing to push into. Hopper minecarts are not: each engine cart re-attempts one transfer per tick whether or not anything changed, so cost scales with entity count, not with throughput.

That is the whole argument for capping minecart-adjacent farms rather than banning hoppers. A storage hall with thousands of idle block hoppers is not your problem. Three thousand carts shuttling between decks is, and filling them fuller barely changes the number.

Settings That Actually Pay Off

Short list, one line of reasoning each. None of these require a plugin, and all of them are reversible in one restart.

• hopper.cooldown-when-full in config/paper-global.yml (keep it true). A full hopper stops polling until its contents change, which removes the most common silent tick cost on survival servers.
• hopper.disable-move-event: only set this to true if you have confirmed nothing listens to InventoryMoveItemEvent. It breaks shop signs, sorting plugins, and any addon that watches item movement.
• entities.spawning.spawn-limits in paper-world-defaults.yml: lowers monsters and creatures per player. This is the cleanest lever on mob-driven tick time, and it is per world.
• mob-spawn-range in spigot.yml: pulling it from 8 toward 6 keeps mobs relevant to players while shrinking the loaded spawn area you pay for.
• merge-radius.item in spigot.yml: raising it slightly merges dropped stacks sooner, cutting entity count after big farms and explosions.
• max-entity-collisions in spigot.yml: capping push calculations stops mob crowds from turning into a physics bill.

Skip anything you cannot explain. Settings advertised as free performance that change game mechanics, such as aggressive tick-rate reductions on block entities, usually trade correctness for a number you could have gotten by fixing the farm instead.

A Reproducible Tuning Workflow

Config work fails when it is not measured. Ten changes in one restart give you one number and zero causal information, and the next restart gives you a different number for reasons you will never isolate. The loop below takes about twenty minutes per change.

1. Copy the whole server directory, or at minimum server.properties, bukkit.yml, spigot.yml, and config/, to a dated backup folder.
2. Change exactly one value, then restart. Reloading is not equivalent for most of these files.
3. Replay the same ten-minute route with the same players online, starting from the same spawn point at the same in-game time.
4. Sample /tick query once per second, which reports TPS and MSPT and is documented on the Minecraft Wiki tick command page.
5. When a change looks wrong rather than slow, take a spark profile with spark profiler start during the same route and compare the call tree.

Compare averages, not peaks, and write down what you expected before you restart. Our primer on MSPT and tick rate explains why a 40 ms average and a 40 ms spike are completely different diagnoses, and that distinction is what keeps this workflow honest.

Pros and Cons: Config, Hardware, or Plugins

Config tuning is the cheapest of the three levers and the easiest to overrate.

• Pros: free, instant, reversible with a backup, and it documents itself in version control. It also forces you to learn where your tick time actually goes.
• Pros: it fixes structural waste, such as three thousand hopper minecarts, that no amount of RAM will absorb.
• Cons: it cannot beat a CPU that is already saturated, and a badly chosen value creates bugs that look like plugin bugs.
• Cons: it stops paying off fast. Once hoppers and spawn limits are sane, the next win is usually a misbehaving plugin.

Hardware is a one-time cost that raises your ceiling; config tuning decides how much of that ceiling you waste. Plugin cleanup is the third option and often the biggest, which is why we wrote a separate method for auditing and trimming plugins. Do config first because it is free, hardware last because it is not.

Common Mistakes to Avoid

Four failures account for most of the bad config advice circulating in Discord servers.

• Editing spigot.yml for Paper-only keys. Hopper flags and spawn limits that belong in config/paper-global.yml or paper-world-defaults.yml do nothing in the Spigot file, and Paper’s startup check will flag unknown keys if you invent one.
• Missing the precedence rule. A value in <world>/paper-world.yml overrides paper-world-defaults.yml for that world. Editing the defaults and seeing no change almost always means a per-world file is winning.
• Changing five values per restart. You lose causal attribution and end up keeping changes that did nothing while blaming the one that worked.
• Ignoring datapack spawn caps. Lowering spawn limits in config does nothing if a datapack enforces its own caps, and the two together can produce empty-looking worlds.

Expert tip: keep a CHANGELOG-configs.md in the server repository. One line per change with date, file, key, old value, new value, and the measured before/after. When a change turns out badly two weeks later, you roll back one line instead of rebuilding a config from memory.

Frequently Asked Questions

Start With the File Map, Then Measure

Paper config files reward patience. Know which file owns a setting, change one value at a time, and keep the measurement loop short enough that you actually run it. Most servers do not need exotic flags; they need a hopper policy, sane spawn limits, and a changelog that lets them undo a bad afternoon.

If you want a system rather than a pile of values, read the Paper reference top to bottom once, then open your own config/ folder and compare. The build is open source, so when a setting is unclear you can read the source on GitHub and see exactly what the flag gates. Start with one backup and one change today, and write down the number before you touch anything.