configurationpaperspigotoptimizationserver-admin

Minecraft Server Configuration Guide: paper-world.yml, spigot.yml, and bukkit.yml Settings Explained

Published on July 28, 2026

# Minecraft Server Configuration Guide: paper-world.yml, spigot.yml, and bukkit.yml Settings Explained

If you've ever stared at your Minecraft server config files wondering what half the settings actually do — you're not alone. Paper, Spigot, and Bukkit each ship with configuration files packed with dozens of options, and choosing the wrong values can silently tank your server's performance.

This guide cuts through the noise. We'll walk through the most impactful settings across paper-world.yml, spigot.yml, and bukkit.yml, explain what each one does under the hood, and give you sane recommended values for a performance-focused server.

---

bukkit.yml — The Foundation

bukkit.yml is the oldest of the three config files and controls some fundamental server behaviors.

spawn-limits

spawn-limits: monsters: 70 animals: 10 water-animals: 5 water-ambient: 20 water-underground-creature: 5

ambient: 15

These values cap how many entities of each type can exist per world at once. The defaults are often too high for servers with many players. Reducing monsters to 40–50 and ambient to 10 is safe for most gamemodes and can significantly cut entity processing overhead.

chunk-gc.period-in-ticks

chunk-gc:

period-in-ticks: 600

This controls how often Bukkit checks for and unloads unused chunks. The default of 600 ticks (30 seconds) is reasonable, but on memory-constrained servers you can lower it to 400. Don't go too low — frequent GC passes create their own overhead.

ticks-per

ticks-per: animal-spawns: 400 monster-spawns: 1 water-spawns: 1 water-ambient-spawns: 1 ambient-spawns: 1

autosave: 6000

animal-spawns at 400 (20 seconds) is a huge win — animals don't need to attempt spawning every tick. monster-spawns: 1 keeps mob mechanics vanilla-accurate. The autosave value of 6000 (5 minutes) is a safe balance between data safety and disk I/O pressure.

---

spigot.yml — The Middle Layer

Spigot's config adds more granular control over entities, hopper behavior, and merge radii.

mob-spawn-range

mob-spawn-range: 6

This defines how far from players mobs can spawn (in chunks). The vanilla default is 8. Reducing it to 6 shrinks the active spawn area, cutting entity count without players noticing a difference during normal gameplay.

entity-activation-range

entity-activation-range: animals: 16 monsters: 24 raiders: 48 misc: 8 water: 8 villagers: 16

flying-monsters: 32

Entities outside their activation range tick at a reduced rate. This is one of the single biggest performance levers in spigot.yml. Lowering animals to 16 and misc to 8 can dramatically reduce CPU time spent on passive entities far from any player.

merge-radius

merge-radius: item: 2.5

exp: 3.0

Items and XP orbs within these radii get merged into single entities. Increasing item to 3.5 and exp to 4.0 reduces entity counts in high-drop areas like mob farms and auto-sorters.

hopper-amount and hopper-check

hoppers: disable-move-event: false

ignore-occluding-blocks: true

In spigot.yml you won't find hopper tick rates directly — those live in paper-world.yml — but setting ignore-occluding-blocks: true provides a minor performance boost for servers with many hoppers.

---

paper-world.yml — The Performance Powerhouse

Paper's world configuration (formerly paper.yml, now split per-world in newer versions) contains the most impactful modern performance settings.

hopper settings

hopper: cooldown-when-full: true

disable-move-event: false

Enabling cooldown-when-full: true prevents hoppers from repeatedly checking for items when they're already full — a meaningful gain on servers with large item-sorting systems.

alt-item-despawn-rate

alt-item-despawn-rate: enabled: true items: COBBLESTONE: 300 NETHERRACK: 300

DIRT: 300

This lets you make low-value items despawn faster (in ticks) than the standard 6000-tick (5 minute) timer. Cobblestone farms and bulk mining sessions often flood servers with junk drops. Setting common materials to despawn in 300 ticks (15 seconds) keeps entity counts sane without impacting gameplay.

prevent-moving-into-unloaded-chunks

prevent-moving-into-unloaded-chunks: true

This prevents players from being teleported or pushed into chunks that haven't loaded yet, avoiding the cascading chunk-load spikes that cause sudden TPS drops.

max-auto-save-chunks-per-tick

max-auto-save-chunks-per-tick: 8

Limits how many chunks Paper saves per tick during autosave. The default is 24, which can cause noticeable lag spikes on slower disks. Reducing it to 8 spreads the I/O load across more ticks at the cost of slightly longer total save times.

redstone-implementation

redstone-implementation: ALTERNATE_CURRENT

Paper supports the ALTERNATE_CURRENT redstone algorithm, which is significantly more efficient than vanilla for complex circuits. If you're running a technical or redstone-heavy server, this single change can eliminate entire categories of redstone lag.

entity-per-chunk-save-limit

entity-per-chunk-save-limit: experience_orb: 50 snowball: 20 ender_pearl: 20

arrow: 50

Caps how many of certain entity types get saved per chunk. This prevents extreme item/projectile buildup from bloating chunk data files and causing slow loads.

---

Applying Changes Without Restarting

Many Paper and Spigot settings require a full server restart to take effect. However, you can reload bukkit.yml and spigot.yml with /reload confirm — though this is generally not recommended on production servers due to plugin state issues. For config testing, maintain a staging server or use scheduled restart windows.

Monitoring the actual impact of your config changes is just as important as making them. Tools like [PulseNode](https://pulsenode.tech) give you real-time TPS, entity counts, and memory graphs so you can see whether a config change improved things or introduced new problems — without having to dig through logs manually.

---

Quick Reference: Recommended Values

|---|---|---|---|

| bukkit.yml | spawn-limits.monsters | 70 | 40–50 |

| bukkit.yml | ticks-per.animal-spawns | 400 | 400 |

| spigot.yml | mob-spawn-range | 8 | 6 |

| spigot.yml | entity-activation-range.animals | 32 | 16 |

| spigot.yml | merge-radius.item | 2.5 | 3.5 |

| paper-world.yml | max-auto-save-chunks-per-tick | 24 | 8 |

---

Final Thoughts

Configuration tuning is not a one-size-fits-all process. A survival server with 50 players has very different needs from a minigame network or a technical Minecraft world. Start with the high-impact changes — entity activation ranges, spawn limits, hopper cooldowns — measure the effect, and iterate.

The most important habit you can build as a server admin is testing one change at a time and watching your metrics. PulseNode makes this easy with automated performance tracking and alerts, so you always know if a config change is helping or hurting before your players notice.

Good configuration is the foundation of a smooth, lag-free Minecraft server. Take the time to understand each setting, and your players will thank you for it.