Bukkit.yml Generator

What is bukkit.yml?

This bukkit.yml generator writes the Bukkit configuration file for Spigot and Paper servers. Choose a preset or set the values above, check the file on the right, and download it. The sections below explain what each setting changes, which values are worth touching, and the mistakes that leave a server with empty caves or a proxy that kicks everyone.

bukkit.yml is the oldest of the plugin-server config files. It came with CraftBukkit, the server that introduced the Bukkit plugin API, and every server built on it still reads it: Spigot, Paper, Purpur and their forks. The server creates it in the main folder on the first start, next to server.properties, spigot.yml and commands.yml.

The file is short. Most of it controls natural mob spawning: how many mobs of each kind can exist and how often the server tries to spawn more. The rest covers a few server-wide switches, auto-save timing and the connection throttle. Vanilla, Fabric and Forge servers do not use it.

How bukkit.yml fits with the other config files

A Paper server reads several files, and settings for the same subject can live in more than one of them. This is the order that matters for bukkit.yml:

Paper's world config has its own spawn-limits and ticks-per-spawn keys. Both default to -1, which means "use the value from bukkit.yml". So on a Paper server, bukkit.yml still decides the mob caps unless you change them in Paper's file too. Set the caps in one place only, or you will edit one file and wonder why nothing changed. The Paper config generator writes the Paper files, and the spigot.yml generator covers the Spigot layer.

Spawn limits

spawn-limits sets the mob cap for each mob category. These are the same caps vanilla Minecraft uses, and the defaults match vanilla:

How the mob cap works

The cap is not a hard count for the whole server. Minecraft scales it with the number of chunks around players that are eligible for spawning. On Spigot, the server counts every mob of a category in those chunks and stops spawning that category when the count reaches the scaled cap. Players who stand close together share one cap. Players far apart each add chunks, so the cap grows with them.

Paper changes this with per-player mob spawning, which is on by default. Each player gets their own cap, and a mob only counts against the players it is near. The practical effect is that one player's mob farm or a cave full of zombies near one player no longer stops mobs from spawning for everyone else.

Either way, a lower number in bukkit.yml means fewer mobs per player. Fewer mobs means less pathfinding and collision work each tick, which is why spawn limits are one of the first settings people lower on a laggy server.

Recommended spawn limits

• Survival server with a few players: the defaults are fine. Players notice fewer mobs quickly, especially at night
• Busy survival server: monsters around 50, animals around 8, and ambient (bats) at 5 or lower. The Balanced SMP preset uses these
• Low-memory or very busy server: monsters 30 or lower and ambient at 1. The Performance preset goes this far, and players will see fewer mobs

Bats are the easiest win. They serve no gameplay purpose on most servers, spawn in every cave, and fly around constantly. Setting ambient to 1 or 2 is rarely noticed.

Spawn timing with ticks-per

The ticks-per section sets how many ticks pass between spawn attempts for each category. There are 20 ticks in a second. The defaults:

• animal-spawns: 400: passive mobs are tried every 20 seconds, which matches vanilla
• monster-spawns: 1: hostile mobs are tried every tick
• water-spawns, water-ambient-spawns, water-underground-creature-spawns, axolotl-spawns, ambient-spawns: every tick

Raising a value makes the server try less often. Each attempt costs CPU, because the server picks random positions around players and checks light level, block type and space for every candidate. With monsters at 1, that work runs 20 times a second.

A value of 10 for monsters cuts spawn attempts by 90 percent. The mob cap still refills, just more slowly after mobs die. Most players cannot tell the difference, because the cap near them is usually already full. The exception is a mob farm: a farm kills mobs as fast as they spawn, so its output depends directly on how often the server tries. A mob farm on a server with monster-spawns: 10 produces noticeably less.

Setting a category to 0 stops natural spawning for it entirely. That is useful for creative or minigame servers and a mistake anywhere else.

The Performance preset sets the water, axolotl and ambient timings to 400. Those mobs matter little to gameplay, so trying for them once every 20 seconds is enough.

Auto-save

ticks-per.autosave is how often the server saves the world and player data, in ticks. The default of 6000 is every five minutes. -1 turns auto-save off.

Leave it on. Turning it off means a crash loses everything since the last manual save-all, and a crash is exactly when you do not want to find that out. On Paper, chunk saving is spread out over several ticks (see max-auto-save-chunks-per-tick in the Paper world config), so auto-save lag spikes are rare. If you see a spike every five minutes on a Spigot server, raising the interval to 12000 (ten minutes) is a reasonable trade.

Chunk GC

chunk-gc.period-in-ticks controls chunk garbage collection. On Spigot, it is how often the server looks for loaded chunks that no player is near and unloads them. The default of 600 is every 30 seconds.

On Paper, the chunk system was rewritten and unloads unused chunks on its own. There the setting only affects chunks that plugins load, and Paper caps it at 20 ticks. The Balanced SMP and Performance presets lower it to 400, which helps on Spigot and does no harm on Paper.

Server settings

connection-throttle

connection-throttle is the number of milliseconds a player's IP address has to wait between login attempts. The default is 4000, four seconds. It stops a single IP from flooding the server with connection attempts.

Behind a proxy, every player connects from the same IP address: the proxy's. With the throttle on, two players joining within four seconds of each other get the second one kicked with "Connection throttled". Set it to -1 on every backend server behind Velocity, BungeeCord or Waterfall. The Behind a Proxy preset does this. The proxy has its own throttle, so the network stays protected. The Velocity config builder sets that one.

allow-end

allow-end: false stops the End from loading. Players who enter an End portal go nowhere. Some lobby and minigame servers turn it off. The Nether has its own switch in server.properties (allow-nether), and recent Paper builds move it to misc.enable-nether in paper-global.yml.

warn-on-overload

Controls the "Can't keep up! Is the server overloaded?" console warning. Leave it on. It is the simplest signal that the server is falling behind, and turning it off only hides the problem. Understanding Minecraft TPS explains what the warning means and how to measure tick time properly.

shutdown-message

The kick message players see when the server stops. It accepts legacy § formatting. Something like "Server restarting, back in a minute" saves you a few questions in Discord.

minimum-api

The lowest plugin api-version the server loads. none loads every plugin. Setting it to 1.20 makes the server refuse plugins that declare an older API version or none at all, which blocks very old plugins that are likely to break. Leave it at none unless you know you want that.

permissions-file and update-folder

permissions-file is where Bukkit reads permission definitions from. Nobody edits it by hand anymore: a permission plugin such as LuckPerms handles permissions instead (LuckPerms setup guide). update-folder is a folder inside plugins/ where you can drop new plugin jars while the server runs. On the next start, the server replaces the old jars with them.

query-plugins

With enable-query=true in server.properties, server list sites and tools can ask the server for its status. query-plugins decides whether the reply includes your plugin list. Turn it off if you do not want to advertise which plugins, and which versions, you run.

Recommended values by server type

Change one thing at a time and watch the server for a day. Spawn settings are easy to overdo, and players notice empty caves before they notice better TPS. If the server lags with low spawn limits already, the cause is somewhere else. How to fix Minecraft server lag walks through finding it with a profiler.

Common mistakes

• Leaving the connection throttle on behind a proxy. Players get kicked at random when two join close together
• Setting a spawn limit to 0 by accident. That category stops spawning completely. Use a small number instead if you only want fewer
• Editing bukkit.yml and Paper's spawn-limits both. Paper's values win when they are not -1, so the bukkit.yml change seems to do nothing
• Turning off auto-save to stop lag spikes. A crash then loses every change since the last save
• Very high monster ticks-per on a farm server. Mob farms lose most of their output
• Tabs in the file. YAML only accepts spaces. A tab makes the server fail to read the file and fall back to defaults. The generated file uses two spaces

How to install the generated bukkit.yml

1. Stop the server.
2. Back up the existing bukkit.yml in the server folder.
3. Upload the downloaded bukkit.yml in its place. If the old file has a worlds: section for a custom world generator, copy that section into the new file first.
4. Start the server and read the first lines of the console for YAML errors.
5. Open bukkit.yml again. The server adds any keys the generated file left out, such as aliases: now-in-commands.yml, with their defaults.

For the rest of the setup, the server.properties generator writes the vanilla settings, and the JVM arguments generator gives you start flags with a sensible amount of memory. For managed hosting, check out ChunkPod.

❓Frequently Asked Questions

Where is bukkit.yml located?

Does Paper still use bukkit.yml?

What are good bukkit.yml spawn limits for performance?

Why do players get kicked with 'Connection throttled'?

Do I need to restart after editing bukkit.yml?

What does ticks-per monster-spawns do?