This article is a reference: it neutrally explains which configuration files Paper has and what each section does. For concrete recommendations ("what should I set?"), see the companion article Optimize your Paper server: improve TPS & fix lag.

Info
As of Paper 1.21.x. Config keys can move or be renamed between versions. If anything differs, the official Paper reference always wins.

The configuration files at a glance

Since Paper 1.19, the former single paper.yml has been split into several files in the config/ folder:

FileScope
config/paper-global.ymlServer-wide – applies to the whole server
config/paper-world-defaults.ymlDefault values for all worlds
<world>/paper-world.ymlPer world – overrides the defaults for that one world only

Who wins on conflicts?

Besides Paper's files there are other configs. For overlapping settings, this rough order applies – the later/more specific layer wins:

server.properties  →  bukkit.yml  →  spigot.yml  →  paper-world-defaults.yml  →  paper-world.yml
   (vanilla base)      (Bukkit)      (Spigot)        (Paper defaults)            (per world)
  • server.properties = vanilla base values (e.g. view-distance, difficulty)
  • spigot.yml = Spigot settings (e.g. entity-activation-range, merge-radius)
  • Paper = the most fine-grained layer; paper-world.yml beats the defaults
Important
The _version field at the top of each file drives Paper's automatic migration – never change it by hand. Paper manages it itself and updates the files across version jumps.

Ground rules before any change

  • Stop the server – don't edit config files while it's running
  • YAML syntax: indent with spaces only, never tabs
  • Make a backup of the config/ files and the world before changing anything
  • After starting, check the log file for warnings

The inheritance principle (often done wrong)

Out of the box, Paper sets no per-world overrides – there are only the defaults at first. To configure a single world differently, create a paper-world.yml there and copy in only the value you want to change – not the whole file.

  • Standard worlds: <worldfolder>/paper-world.yml
  • Custom dimensions (data packs): world/dimensions/<namespace>/<key>/paper-world.yml

Example – enable lootables.auto-replenish for one world only:

# only in world_the_end/paper-world.yml
lootables:
  auto-replenish: true

Two-world example with different mob limits:

# world/paper-world.yml  (main world: fewer monsters)
entities:
  spawning:
    spawn-limits:
      monster: 50

# world_nether/paper-world.yml  (Nether: more monsters allowed)
entities:
  spawning:
    spawn-limits:
      monster: 100

Every value you don't override still comes from paper-world-defaults.yml.

paper-global.yml – the sections

Server-wide settings. This table neutrally describes what each section is responsible for:

SectionResponsible for
block-updatesDisabling certain block ticks: disable-noteblock-updates, disable-tripwire-updates, disable-chorus-plant-updates, disable-mushroom-block-updates
chunk-loading-basicBase chunk-loading rates per player: player-max-chunk-load-rate, -send-rate, -generate-rate
chunk-loading-advancedFiner chunk behaviour: auto-config-send-distance, player-max-concurrent-chunk-loads/-generates
chunk-systemThreading of the chunk system: io-threads, worker-threads, gen-parallelism
collisionsenable-player-collisions – whether players push each other
packet-limiterProtection against packet floods (anti-crash)
player-auto-saveInterval/rate of player-data saving
proxiesBungeeCord / Velocity; in a proxy setup online-mode lives on the proxy, not the backend
spam-limiterLimiting chat/action spam
timings / consoleDiagnostic timings and console behaviour
unsupported-settingsExperimental/risky switches (use with care)
miscMiscellaneous: max-joins-per-tick, compression-level, region-file-cache-size
anticheat / obfuscationHide item components from other players (anti-cheat protection)

Via unsupported-settings and the world settings you can also, among other things, disable the Nether and toggle certain vanilla bug fixes (e.g. MC-159283, MC-163962).

paper-world-defaults.yml – the sections

Default values for worlds (overridable per world via paper-world.yml):

SectionResponsible for
anticheat.anti-xrayX-ray protection: engine-mode (1 = replace blocks, 2/3 = hide real blocks), hidden-blocks, replacement-blocks
chunksmax-auto-save-chunks-per-tick, delay-chunk-unloads-by, entity-per-chunk-save-limit
entities.spawningspawn-limits, ticks-per-spawn, per-player-mob-spawns, despawn-ranges (soft/hard)
entities.behaviormobs-can-always-pick-up-loot, disable-chest-cat-detection, zombie-villager-infection-chance
entities.armor-stands / markersBehaviour of armour stands and marker entities
collisionsmax-entity-collisions, fix-climbing-bypassing-cramming-rule
hoppercooldown-when-full, disable-move-event
lootablesauto-replenish and refresh intervals for loot chests
redstone-implementationVANILLA, ALTERNATE_CURRENT or EIGENCRAFT
tick-ratesTick intervals: mob-spawner, sensor, behavior (incl. villagers!), container-update
environmentoptimize-explosions, disable-thunder, disable-ice-and-snow, treasure-maps
unsupported-settingse.g. fix-invulnerable-end-crystal-exploit
spawnkeep-spawn-loaded, keep-spawn-loaded-range
scoreboards, maps, fishing-time-rangeScoreboard, map and fishing behaviour
Tip
What these values mean for performance and how to set them is covered in Optimize your Paper server. This reference article deliberately stays neutral.

Verifying & safeguarding changes

  • Some values can be re-read with /paper reload – when in doubt, restart the server
  • After starting, check the log file for YAML errors and warnings
  • Always back up before config changes – a single indentation typo can stop a world from loading
  • Full, version-current reference: docs.papermc.io – Global and World

Where to next