Skip to main content
Paper’s world configuration allows you to customize settings on a per-world basis. The default configuration is stored in config/paper-world-defaults.yml, and you can create world-specific overrides.

​
Location

server-root/
└── config/
    ├── paper-world-defaults.yml    # Default settings for all worlds
    └── paper-world.yml              # World-specific overrides (auto-generated)

​
Entity Settings

​
Spawning

​
entities.spawning.spawn-limits.[category]
integer
default:"-1"
Per-world mob spawn limits for each category. -1 uses the server default from bukkit.yml.Categories: monster, creature, ambient, axolotls, underground_water_creature, water_creature, water_ambient
spawn-limits:
  monster: 70
  creature: 10
  ambient: 15
  water_creature: 5
​
entities.spawning.ticks-per-spawn.[category]
integer
default:"-1"
Ticks between spawn attempts for each category. Higher values reduce spawn rates. -1 uses bukkit.yml defaults.
​
entities.spawning.per-player-mob-spawns
boolean
default:"true"
Enable per-player mob spawning for more consistent spawning near players.
This creates a better single-player-like experience in multiplayer!
​
entities.spawning.despawn-ranges.[category].soft
integer
default:"default"
Distance at which mobs begin to have a chance to despawn. Uses vanilla default if not set.
​
entities.spawning.despawn-ranges.[category].hard
integer
default:"default"
Distance at which mobs immediately despawn. Uses vanilla default if not set.
despawn-ranges:
  monster:
    soft: 32
    hard: 128
​
entities.spawning.despawn-range-shape
string
default:"ellipsoid"
Shape used for calculating despawn ranges. Options: ellipsoid or cylinder.
​
entities.spawning.non-player-arrow-despawn-rate
integer
default:"default"
Ticks before arrows shot by non-players despawn. -1 disables despawning.
​
entities.spawning.creative-arrow-despawn-rate
integer
default:"default"
Ticks before arrows shot by creative mode players despawn.
​
entities.spawning.max-arrow-despawn-invulnerability
integer
default:"200"
Maximum invulnerability ticks for arrows before forced despawn. Set to -1 to disable.
​
entities.spawning.all-chunks-are-slime-chunks
boolean
default:"false"
Make all chunks valid for slime spawning.
​
entities.spawning.iron-golems-can-spawn-in-air
boolean
default:"false"
Allow iron golems to spawn without a full solid block beneath them.
​
entities.spawning.count-all-mobs-for-spawning
boolean
default:"false"
Count all mobs (including those from spawners) towards spawn caps.
​
entities.spawning.skeleton-horse-thunder-spawn-chance
double
default:"default"
Chance for skeleton horses to spawn during thunderstorms. Use vanilla default if not set.
​
entities.spawning.monster-spawn-max-light-level
integer
default:"default"
Maximum light level at which monsters can spawn. Vanilla default is 0.
​
entities.spawning.wandering-trader.spawn-minute-length
integer
default:"1200"
Length of a “minute” in ticks for wandering trader spawn timing.
​
entities.spawning.wandering-trader.spawn-day-length
integer
default:"24000"
Length of a “day” in ticks for wandering trader spawn timing.
​
entities.spawning.wandering-trader.spawn-chance-min
integer
default:"25"
Minimum spawn chance percentage for wandering traders.
​
entities.spawning.wandering-trader.spawn-chance-max
integer
default:"75"
Maximum spawn chance percentage for wandering traders.
​
entities.spawning.alt-item-despawn-rate.enabled
boolean
default:"false"
Enable custom despawn rates for specific items.
​
entities.spawning.alt-item-despawn-rate.items
map
default:"cobblestone: 300"
Map of items to their despawn time in ticks.
alt-item-despawn-rate:
  enabled: true
  items:
    minecraft:cobblestone: 300
    minecraft:dirt: 300
    minecraft:gravel: 300
Useful for reducing lag from common items like cobblestone!

​
Behavior

​
entities.behavior.baby-zombie-movement-modifier
double
default:"0.5"
Speed modifier for baby zombies (0.5 = 50% faster than adults).
​
entities.behavior.spawner-nerfed-mobs-should-jump
boolean
default:"false"
Allow mobs from spawners to jump when nerfed.
​
entities.behavior.zombies-target-turtle-eggs
boolean
default:"true"
Whether zombies should pathfind to and trample turtle eggs.
​
entities.behavior.piglins-guard-chests
boolean
default:"true"
Whether piglins become angry when players open chests.
​
entities.behavior.allow-spider-world-border-climbing
boolean
default:"true"
Allow spiders to climb the world border.
​
entities.behavior.should-remove-dragon
boolean
default:"false"
Remove the ender dragon after it’s been defeated.
​
entities.behavior.ender-dragons-death-always-places-dragon-egg
boolean
default:"false"
Always place a dragon egg when the ender dragon dies (even on respawns).
​
entities.behavior.phantoms-do-not-spawn-on-creative-players
boolean
default:"true"
Prevent phantoms from spawning for creative mode players.
​
entities.behavior.phantoms-only-attack-insomniacs
boolean
default:"true"
Phantoms only attack players who haven’t slept.
​
entities.behavior.player-insomnia-start-ticks
integer
default:"72000"
Ticks before phantoms can start spawning for a player (72000 = 3 days).
​
entities.behavior.phantoms-spawn-attempt-min-seconds
integer
default:"60"
Minimum seconds between phantom spawn attempts.
​
entities.behavior.phantoms-spawn-attempt-max-seconds
integer
default:"119"
Maximum seconds between phantom spawn attempts.
​
entities.behavior.pillager-patrols.disable
boolean
default:"false"
Completely disable pillager patrols.
​
entities.behavior.pillager-patrols.spawn-chance
double
default:"0.2"
Chance (0.0-1.0) for patrols to spawn.
​
entities.behavior.pillager-patrols.start.day
integer
default:"5"
Day number when patrols can start spawning.
​
entities.behavior.pillager-patrols.spawn-delay.ticks
integer
default:"12000"
Ticks between patrol spawn attempts.
​
entities.behavior.zombie-villager-infection-chance
double
default:"default"
Chance for villagers to become zombie villagers when killed by zombies. -1 uses vanilla behavior.
​
entities.behavior.mobs-can-always-pick-up-loot.zombies
boolean
default:"false"
Allow all zombies to pick up loot (not just those that spawn with the ability).
​
entities.behavior.mobs-can-always-pick-up-loot.skeletons
boolean
default:"false"
Allow all skeletons to pick up loot.
​
entities.behavior.disable-player-crits
boolean
default:"false"
Disable critical hits for players.
​
entities.behavior.nerf-pigmen-from-nether-portals
boolean
default:"false"
Prevent zombie pigmen from spawning through nether portals from dropping items.
​
entities.behavior.experience-merge-max-value
integer
default:"-1"
Maximum value for merged experience orbs. -1 disables limit.
​
entities.behavior.only-merge-items-horizontally
boolean
default:"false"
Prevent merging items that are not on the same y level, preventing visual artifacts.
Useful for preventing items from appearing to merge through floors.

​
Armor Stands & Markers

​
entities.armor-stands.tick
boolean
default:"true"
Whether armor stands should tick. Disabling improves performance but breaks some functionality.
​
entities.armor-stands.do-collision-entity-lookups
boolean
default:"true"
Whether armor stands should perform collision lookups.
​
entities.markers.tick
boolean
default:"true"
Whether marker entities should tick.

​
Anticheat

​
Anti-Xray

​
anticheat.anti-xray.enabled
boolean
default:"false"
Enable Paper’s anti-xray system.
This adds CPU overhead. Test performance on your server!
​
anticheat.anti-xray.engine-mode
string
default:"hide"
Anti-xray engine mode:
  • hide: Hide ores by replacing them with stone
  • obfuscate: Mix real and fake ores (more CPU intensive but more effective)
​
anticheat.anti-xray.max-block-height
integer
default:"64"
Maximum Y level where anti-xray is active.
​
anticheat.anti-xray.update-radius
integer
default:"2"
Radius to update when blocks are broken (engine mode 2 only).
​
anticheat.anti-xray.lava-obscures
boolean
default:"false"
Whether lava should obscure blocks like stone does.
​
anticheat.anti-xray.use-permission
boolean
default:"false"
Require paper.antixray.bypass permission to bypass anti-xray.
​
anticheat.anti-xray.hidden-blocks
list
default:"[ores, chests, etc.]"
List of blocks to hide or obfuscate.
hidden-blocks:
  - minecraft:copper_ore
  - minecraft:deepslate_copper_ore
  - minecraft:gold_ore
  - minecraft:iron_ore
  - minecraft:diamond_ore
  - minecraft:emerald_ore
  - minecraft:chest
  - minecraft:ender_chest
​
anticheat.anti-xray.replacement-blocks
list
default:"[stone, oak_planks, deepslate]"
Blocks used to replace hidden blocks (engine mode 1) or fake ores (engine mode 2).

​
Environment

​
environment.disable-thunder
boolean
default:"false"
Disable thunder and lightning in this world.
​
environment.disable-ice-and-snow
boolean
default:"false"
Prevent ice and snow from forming.
​
environment.fire-tick-delay
integer
default:"30"
Ticks between fire spread attempts. Higher values slow fire spread.
​
environment.optimize-explosions
boolean
default:"false"
Use optimized explosion algorithm (faster but may change behavior slightly).
​
environment.disable-explosion-knockback
boolean
default:"false"
Disable knockback from explosions.
​
environment.portal-search-radius
integer
default:"128"
Radius to search for existing nether portals.
​
environment.portal-create-radius
integer
default:"16"
Radius within which to create a new nether portal.
​
environment.portal-search-vanilla-dimension-scaling
boolean
default:"true"
Use vanilla dimension scaling when searching for portals (1:8 for nether).
​
environment.treasure-maps.enabled
boolean
default:"true"
Enable treasure map generation.
​
environment.treasure-maps.find-already-discovered-villager
boolean
default:"false"
Allow villager trades to give maps to already-discovered structures.
​
environment.treasure-maps.find-already-discovered-loot-table
boolean
default:"default"
Allow loot table maps to point to already-discovered structures.

​
Chunks

​
chunks.auto-save-interval
integer
default:"default"
Ticks between automatic chunk saves. -1 or default uses bukkit.yml value.
​
chunks.max-auto-save-chunks-per-tick
integer
default:"24"
Maximum chunks to save per tick during auto-save.
​
chunks.delay-chunk-unloads-by
string
default:"10s"
Delay before unloading chunks (supports time units: s, m, h, d).
Keeping chunks loaded longer reduces repeated loading for players moving back and forth.
​
chunks.prevent-moving-into-unloaded-chunks
boolean
default:"false"
Prevent players from moving into unloaded chunks.
​
chunks.entity-per-chunk-save-limit
map
default:"see source"
Limit entities saved per chunk by type. Prevents lag from entity overflow.
entity-per-chunk-save-limit:
  experience_orb: 16
  snowball: 16
  ender_pearl: 16
  arrow: 16

​
Performance Options

​
hopper.cooldown-when-full
boolean
default:"true"
Add cooldown to hoppers when the container is full, reducing checks.
​
hopper.disable-move-event
boolean
default:"false"
Disable InventoryMoveItemEvent for hoppers (breaks plugins that use it).
Only enable this if you know what you’re doing!
​
hopper.ignore-occluding-blocks
boolean
default:"false"
Skip checks for blocks above hoppers.
​
tick-rates.grass-spread
integer
default:"1"
Ticks between grass spread attempts. Higher = slower spread but better performance.
​
tick-rates.container-update
integer
default:"1"
Ticks between container updates.
​
tick-rates.mob-spawner
integer
default:"1"
Ticks between mob spawner attempts.
​
misc.redstone-implementation
string
default:"vanilla"
Redstone implementation to use:
  • vanilla: Standard Minecraft redstone
  • eigencraft: Eigencraft redstone implementation
  • alternate_current: Modern alternate current redstone
Changing this affects redstone behavior and contraption functionality!

​
Example Configuration

entities:
  spawning:
    spawn-limits:
      monster: 70
      creature: 10
    per-player-mob-spawns: true
    alt-item-despawn-rate:
      enabled: true
      items:
        minecraft:cobblestone: 300

anticheat:
  anti-xray:
    enabled: true
    engine-mode: hide
    max-block-height: 64

chunks:
  auto-save-interval: -1
  delay-chunk-unloads-by: 10s

hopper:
  cooldown-when-full: true
  disable-move-event: false

​
Per-World Overrides

To create world-specific settings, the server automatically generates config/paper-world.yml with sections for each world: 
world_list:
  world:  # Overworld
    entities:
      spawning:
        spawn-limits:
          monster: 50
  world_nether:  # Nether
    anticheat:
      anti-xray:
        enabled: false

Global Configuration

Server-wide settings

Performance Tuning

Optimize these settings for performance

Build docs developers (and LLMs) love

Get started for freeTalk to us