World Configuration

Per-world Paper configuration options in config/paper-world-defaults.yml

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

Spawn Limits

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!

Despawn Ranges

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.

Arrow Despawn

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.

Special Spawning

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.

Wandering Trader

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.

Alt Item Despawn Rate

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

Mob AI & Movement

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.

Ender Dragon

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).

Phantoms

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.

Pillager Patrols

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.

Villagers & Trading

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.

Player Mechanics

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.

Experience & 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

Entity Ticking

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

Anti-Xray Configuration

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

Weather & Natural Events

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.

Explosions

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.

Portals

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).

Treasure Maps

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

Chunk Management

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 Optimization

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

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.

Redstone

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