Bukkit.yml Settings Guide, What Each One Actually Does

What Is bukkit.yml?

The bukkit.yml file is the oldest configuration layer in the CraftBukkit/Spigot/Paper stack. It controls fundamental server behavior like mob spawn limits, autosave intervals, chunk garbage collection, and connection throttling. Every Bukkit-based server, whether running Spigot, Paper, or Purpur, reads this file at startup.

Many of bukkit.yml's settings have been superseded or extended by Spigot and Paper. Where that happens, this guide notes which file takes priority. If you run Paper (and you should, see the comparison guide), some bukkit.yml settings are effectively ignored because Paper handles them differently. But they are still worth understanding because not every server runs Paper, and the bukkit.yml values serve as fallback defaults.

spawn-limits

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

What it does: These values set the global mob cap for each category. The number represents the maximum number of naturally spawned mobs of that category that can exist per world. The actual formula is: spawn-limit * chunks-in-range / 289. So the effective per-player cap scales with how many chunks are loaded.

Recommended values for different server sizes:

Category	Default	10-20 Players	50+ Players	100+ Players
monsters	70	50	35	25
animals	10	8	5	3
water-animals	5	3	2	2
water-ambient	20	10	5	3
water-underground-creature	5	3	2	1
axolotls	5	3	2	1
ambient	15	8	3	1

Ambient mobs (bats) are purely cosmetic and expensive relative to their value. On any server with TPS concerns, drop ambient to 1-3. Water-ambient (tropical fish, pufferfish) can also be reduced aggressively, players rarely interact with them, and ocean biomes generate hundreds of them.

Paper override: When Paper's per-player-mob-spawns is set to true (which it should be), the effective behavior changes from a global cap to a per-player cap. The bukkit.yml values still determine the base numbers, but Paper distributes them per player rather than sharing globally. Read the mob spawning configuration guide for the full picture.

chunk-gc

chunk-gc:
  period-in-ticks: 600

What it does: Chunk garbage collection runs every N ticks and unloads chunks that have no players nearby and no active tile entities (hoppers, furnaces, etc.) keeping them loaded. Default 600 (every 30 seconds). Recommended: 400 for servers with many players exploring rapidly. This more aggressive cleanup prevents chunk accumulation during peak hours. On smaller servers, 600 is fine.

Paper override: Paper's chunk system manages unloading more intelligently through its own async chunk system. The bukkit.yml value still works but has less impact because Paper already handles most chunk lifecycle management. The delay-chunk-unloads-by setting in paper-world-defaults.yml is more relevant on Paper servers.

ticks-per

ticks-per:
  animal-spawns: 400
  monster-spawns: 1
  water-spawns: 1
  water-ambient-spawns: 1
  water-underground-creature-spawns: 1
  axolotl-spawns: 1
  ambient-spawns: 1
  autosave: 6000

What it does: Controls how often (in ticks) the server attempts to spawn each mob category and how often it autosaves.

animal-spawns: Default 400 means the server attempts animal spawning every 20 seconds. Animals are passive and do not need frequent spawn attempts, they stick around once spawned. Recommended: 400 is fine. Raising to 600 is safe.

monster-spawns: Default 1 means hostile mob spawning is attempted every single tick. This is necessary for vanilla mob density. Recommended: Keep at 1 for most servers. Setting to 2 halves monster spawn rate, which noticeably reduces mob density and can make survival feel too easy. Only raise this if you have severe TPS problems and have already tried all other optimizations.

water-ambient-spawns: These can be safely raised to 40-80. Fish and other water ambient mobs do not need to spawn every tick, and oceans fill up fast with the default value.

ambient-spawns: Bats. Raise to 40-80 or even higher. Nobody needs bats spawning every tick. Setting this to 200 means a bat spawn attempt every 10 seconds, which still keeps caves populated without wasting cycles.

autosave: Default 6000 ticks (5 minutes). This triggers a world save that can cause a brief lag spike. Recommended: 6000 is a good balance. If you experience noticeable autosave lag, raise to 12000 (10 minutes). On Paper, this setting interacts with max-auto-save-chunks-per-tick which spreads the save across multiple ticks, Paper servers generally do not get autosave lag spikes.

connection-throttle

connection-throttle: 4000

What it does: The minimum time (in milliseconds) between connection attempts from the same IP address. Default 4000 (4 seconds). This prevents rapid reconnect spam that could stress the server. Recommended: 4000 is fine for most setups. If you run a server behind a proxy (BungeeCord, Velocity), set this to -1 to disable it, the proxy handles connection throttling, and this setting can interfere with players being forwarded from the proxy.

aliases

aliases: now-hierarchical

What it does: Controls how Bukkit handles command aliases defined in commands.yml. The now-hierarchical value is the modern default and resolves aliases hierarchically. You generally never need to change this. If you define custom command aliases, they go in commands.yml, not here.

database

database:
  username: bukkit
  isolation: SERIALIZABLE
  driver: org.sqlite.JDBC
  password: walrus
  url: jdbc:sqlite:{DIR}/{NAME}.db

What it does: Configures the default database backend for plugins that use the Bukkit persistence API (ebean/persistence). Almost no modern plugins use this, they bring their own database connections. Recommended: Leave defaults. If a plugin specifically asks you to configure bukkit.yml database settings, switch from SQLite to MySQL for better performance on larger servers:

database:
  username: minecraft
  isolation: SERIALIZABLE
  driver: com.mysql.cj.jdbc.Driver
  password: your_password_here
  url: jdbc:mysql://localhost:3306/minecraft

But again, this is rarely needed. Most plugins (LuckPerms, EssentialsX, etc.) have their own database configuration in their individual config files.

update-folder

update-folder: update

What it does: The folder name inside plugins/ where auto-updated plugin jars are placed. Plugins that support auto-updating download new versions to this folder, and they are applied on the next server restart. Recommended: Keep default. Some server admins change this to a more descriptive name like pending-updates for clarity, but it makes no functional difference.

Settings That Paper Overrides

For clarity, here is a summary of which bukkit.yml settings are partially or fully overridden when running Paper:

bukkit.yml Setting	Paper Override	Notes
spawn-limits	per-player-mob-spawns	Base values still used, but distributed per-player instead of globally
chunk-gc	Paper async chunk system	Still runs, but Paper manages chunk lifecycle more aggressively
ticks-per.autosave	auto-save-interval + max-auto-save-chunks-per-tick	Paper spreads saves across ticks; bukkit value triggers the cycle
connection-throttle	Not overridden	Still fully controlled by bukkit.yml
ticks-per.*-spawns	Not directly overridden	Paper adds its own spawn rate modifiers on top

Even on Paper servers, configuring bukkit.yml correctly matters because the values serve as the foundation that Paper builds upon. Setting spawn-limits too high in bukkit.yml means Paper's per-player distribution starts from an inflated baseline, which still results in more mobs than necessary.

Quick Setup Checklist

If you are setting up a new server and want sensible bukkit.yml defaults without overthinking it, use these values:

• monsters: 50, animals: 8, water-animals: 3, water-ambient: 8, ambient: 3
• chunk-gc.period-in-ticks: 400
• ticks-per.monster-spawns: 1, ambient-spawns: 60, water-ambient-spawns: 40
• ticks-per.autosave: 6000
• connection-throttle: 4000 (or -1 behind a proxy)

Then move on to spigot.yml and paper-world-defaults.yml for the settings that have a bigger performance impact.

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.