Every Paper.yml Setting Explained (2026)

Understanding Paper's Configuration Structure

Paper split its configuration into two files starting in version 1.19: config/paper-global.yml for server-wide settings, and config/paper-world-defaults.yml for per-world settings. Individual worlds can override defaults by placing a paper-world.yml inside their world folder. If you are coming from an older Paper version that used a single paper.yml, all those settings migrated automatically into the new files.

This guide covers every setting that meaningfully affects performance, gameplay, or server behavior. Settings that are purely cosmetic or deprecated are omitted. For a broader performance tuning approach, read the server optimization guide first, it explains the methodology behind these recommendations. For comparisons between server software, see Paper vs Spigot vs Purpur.

paper-global.yml

This file controls server-wide behavior that is not tied to any specific world. Changes here require a server restart to take effect.

async-chunks

async-chunks:
  threads: -1

What it does: Controls how many threads Paper uses for asynchronous chunk loading and saving. The default -1 lets Paper auto-detect based on your CPU core count. Recommended: Leave at -1 unless you are running on a machine with more than 16 cores and want to limit Paper's thread usage to leave headroom for other processes. Setting this to a specific number like 4 forces exactly 4 threads regardless of hardware.

chunk-loading-basic

chunk-loading-basic:
  autoconfig-send-distance: true
  player-max-chunk-generate-rate: -1.0
  player-max-chunk-load-rate: -1.0
  player-max-chunk-send-rate: 75.0

autoconfig-send-distance: When true, Paper automatically adjusts the chunk send distance based on your view distance. Leave this on, it prevents sending more chunks than the client can render, which saves bandwidth.

player-max-chunk-generate-rate: Limits how fast new chunks generate per player per second. The default -1 means unlimited. On servers with 50+ players or older hardware, setting this to 40.0 prevents chunk generation from monopolizing the main thread during exploration sprees.

player-max-chunk-send-rate: How many chunks per second are sent to each player's client. Default 75 is fine for most connections. Players on slow internet benefit from a lower value (40-50) to prevent packet overflow.

chunk-system

chunk-system:
  gen-parallelism: default
  io-threads: -1
  worker-threads: -1

gen-parallelism: Controls parallel chunk generation. default lets Paper decide. On dedicated servers with 8+ cores, true enables full parallelism for faster world generation at the cost of higher CPU usage during exploration. io-threads / worker-threads: Similar to async-chunks threads. Leave at -1 for auto-detection.

packet-limiter

packet-limiter:
  all-packets:
    action: KICK
    interval: 7.0
    max-packet-rate: 500.0

What it does: Kicks players who send more than 500 packets per 7-second interval. This defends against packet spam attacks and misbehaving clients. Recommended: Keep defaults. Only increase max-packet-rate if legitimate players are getting kicked during high-activity moments (mass inventory sorting, rapid clicking). If you see kicks from this, try 800 before going higher.

unsupported-settings

unsupported-settings:
  allow-piston-duplication: false
  allow-permanent-block-break-exploits: false
  allow-headless-pistons: false

allow-piston-duplication: Whether TNT and carpet duplication via pistons works. Vanilla Minecraft has these bugs, and many technical players rely on them for farms. Set to true on SMP/technical servers, false on strict survival or economy servers where duplication undermines the economy.

allow-permanent-block-break-exploits: Allows breaking normally unbreakable blocks (bedrock, end portal frames) using piston exploits. true for technical servers, false for everything else.

paper-world-defaults.yml

These settings apply to every world unless overridden in a world-specific paper-world.yml. Most performance-critical tweaks live here.

entities, spawning

entities:
  spawning:
    per-player-mob-spawns: true
    scan-for-legacy-ender-dragon: true
    despawn-ranges:
      ambient:
        hard: 72
        soft: 30
      axolotls:
        hard: 72
        soft: 30
      creature:
        hard: 72
        soft: 30
      misc:
        hard: 72
        soft: 30
      monster:
        hard: 72
        soft: 30
      underground_water_creature:
        hard: 72
        soft: 30
      water_ambient:
        hard: 72
        soft: 30
      water_creature:
        hard: 72
        soft: 30

per-player-mob-spawns: This is one of the most important settings in Paper. When true, each player gets their own mob cap instead of sharing a global cap. This means one player with a massive mob farm does not prevent mobs from spawning near other players. Always keep this true. See the mob spawning guide for details.

despawn-ranges: Two values per mob category. soft is the distance (in blocks) at which mobs have a chance to despawn each tick. hard is the distance at which mobs are instantly removed. Defaults of 30/72 are good for most servers. On servers with performance issues, lowering hard to 56-64 reduces distant mob counts noticeably. Going below 48 starts affecting gameplay, players will notice mobs vanishing.

entities, behavior

entities:
  behavior:
    pillager-patrols:
      disable: false
      spawn-chance: 0.2
      spawn-delay:
        per-player: true
        ticks: 12000
    zombie-villager-infection-chance: -1.0
    ender-dragons-death-always-places-dragon-egg: false

pillager-patrols.disable: Set to true on skyblock, plot, or creative servers where patrols serve no purpose. On survival, leave them on, they add world flavor.

zombie-villager-infection-chance: Default -1.0 means vanilla behavior (0% on Easy, 50% on Normal, 100% on Hard). Set to a specific decimal (0.0 to 1.0) if you want to override this regardless of difficulty.

environment

environment:
  fire-tick-delay: 30
  disable-ice-and-snow: false
  disable-thunder: false
  optimize-explosions: false
  treasure-maps:
    enabled: true
    find-already-discovered:
      loot-tables: default
      villager-trade: false

optimize-explosions: When true, Paper uses a faster algorithm for explosion block damage calculation. This helps servers with lots of TNT or creeper explosions. The visual result is identical. Recommended: true on all servers.

treasure-maps.find-already-discovered.villager-trade: When false, villager-sold treasure maps always point to undiscovered structures. Set to true if your world is well-explored and players are complaining about maps leading to already-looted structures, but be aware this can cause lag as the server searches for unexplored chunks.

chunks

chunks:
  auto-save-interval: 6000
  delay-chunk-unloads-by: 10s
  max-auto-save-chunks-per-tick: 24
  prevent-moving-into-unloaded-chunks: true

auto-save-interval: How often (in ticks) chunks are saved. Default 6000 (5 minutes). Lower values mean less data loss on crashes but more disk I/O. On NVMe storage, 6000 is fine. On HDD, consider raising to 12000.

delay-chunk-unloads-by: Keeps chunks loaded for 10 seconds after the last player leaves them. This prevents constant load/unload cycles when players are near chunk borders. 10 seconds is a good default. Raise to 20-30 seconds on servers where players frequently backtrack (faction raids, PvP arenas near borders).

max-auto-save-chunks-per-tick: Spreads chunk saving across ticks. Default 24 means up to 24 chunks saved per tick during autosave. On slow storage, lower to 8-12 to reduce autosave lag spikes. On fast NVMe, 24 is fine.

prevent-moving-into-unloaded-chunks: Prevents players from entering chunks that have not finished loading. Keeps true, this prevents glitching through terrain during lag spikes.

collisions

collisions:
  allow-vehicle-collisions: false
  fix-climbing-bypassing-cramming-rule: false
  max-entity-collisions: 8
  only-players-collide: false

max-entity-collisions: Limits how many collision calculations a single entity processes per tick. Default 8 is fine. On servers with animal farms or villager trading halls, lowering to 2-4 reduces lag from cramming. Setting to 0 disables entity pushing entirely, which some servers prefer.

tick-rates

tick-rates:
  behavior:
    villager:
      validatenearbypoi: -1
  container-update: 1
  grass-spread: 1
  mob-spawner: 1
  sensor:
    villager:
      secondarypoisensor: 40

grass-spread: How often grass tries to spread to adjacent dirt blocks, in ticks. Default 1 (every tick) is vanilla behavior. Setting to 4 reduces the CPU cost of large grassy areas with zero visible difference to players.

mob-spawner: Tick rate for spawner blocks. Default 1 means spawners check every tick. Setting to 2 halves spawner efficiency but reduces their CPU cost. Use this on servers where spawner farms cause lag.

villager sensors: How often villagers check for nearby points of interest and beds. Default values cause villagers to constantly pathfind, which is expensive in trading halls with dozens of villagers. Raise validatenearbypoi to 60 and secondarypoisensor to 80 to cut villager AI costs significantly.

misc

misc:
  fix-curing-zombie-villager-discount-exploit: true
  update-pathfinding-on-block-update: true
  redstone-implementation: ALTERNATE_CURRENT

fix-curing-zombie-villager-discount-exploit: When true, villagers cannot be infinitely cured for ever-cheaper trades. Keep true on economy servers to preserve trade balance.

redstone-implementation: Paper offers VANILLA, EIGENCRAFT, and ALTERNATE_CURRENT. Alternate Current is the most performant redstone engine, often 10-20x faster than vanilla. However, it can break some complex contraptions that rely on specific vanilla update order quirks. Recommended: ALTERNATE_CURRENT for most servers. Switch to VANILLA only if players report redstone machines breaking.

update-pathfinding-on-block-update: When true, mobs recalculate their path when nearby blocks change. This is expensive in areas with lots of redstone or block changes. Set to false for a meaningful performance improvement, mobs will occasionally walk into newly placed blocks for a tick before rerouting, but it is rarely noticeable.

Quick Reference: Performance Settings Summary

Setting	Default	Performance Value	Impact
per-player-mob-spawns	true	true	High, fair mob distribution
optimize-explosions	false	true	Medium, faster TNT/creepers
redstone-implementation	VANILLA	ALTERNATE_CURRENT	High, massive redstone gains
update-pathfinding-on-block-update	true	false	Medium, less pathfinding CPU
max-entity-collisions	8	2	Medium, less collision math
grass-spread	1	4	Low, minor savings
despawn-ranges.hard	72	56-64	Medium, fewer distant mobs
villager validatenearbypoi	-1	60	Medium, less villager lag

Apply these settings incrementally and monitor your TPS after each change using /spark tps or /tps. Every server is different, a setting that helps on a 100-player network might be unnecessary on a 10-player SMP. Start with the high-impact changes and work down.

Need a server for this? Astroworld Hosting runs NVMe SSD, Pterodactyl panel, and DDoS protection on every plan. See features , plans from €6.39/mo.