Spigot.yml Generator

What is spigot.yml?

This spigot.yml generator writes the main configuration file that Spigot adds on top of the vanilla server. Pick a preset or change the settings above, check the output on the right, and download the file. The rest of this page explains what each section does, which values to change first, and the mistakes that most often break farms or open a server to the wrong players.

Spigot creates spigot.yml in the server folder, next to server.properties and bukkit.yml, the first time it starts. server.properties holds the settings the vanilla game knows about, bukkit.yml holds the Bukkit API settings such as spawn limits, and spigot.yml holds the performance and behavior settings Spigot added itself: how far away entities are ticked and shown, how dropped items merge, how often hoppers work, and the kick messages players see.

Paper and Purpur are built on Spigot, so they read spigot.yml as well. On those servers the file sits next to Paper's own config files, and every setting on this page still applies. If you are still choosing a server jar, Paper vs Spigot vs Fabric vs Forge compares them.

How the file is laid out

spigot.yml is a YAML file with a few top-level sections. This tool writes the ones that matter for most servers:

You do not need to write every key. When Spigot starts, it reads the file, fills in any key that is missing with its default value, and saves the file again. That is why a short generated file turns into a long one after the first start, and why the comments you add by hand disappear.

Per-world overrides

Everything under world-settings.default applies to all worlds. To give one world different values, add a section with the world's folder name next to default and list only the keys you want to change:

world-settings:
  default:
    view-distance: default
    mob-spawn-range: 8
  world_nether:
    view-distance: 6

The Nether and the End are separate worlds (world_nether and world_the_end on a standard Spigot server), so this is how you lower the view distance in the Nether without touching the Overworld.

Entity activation range

Entity activation range is the setting Spigot is best known for. Every entity on a vanilla server runs its full logic every tick, 20 times a second, whether a player is nearby or not. Spigot splits entities into active and inactive ones. An entity farther than its activation range from every player becomes inactive and only ticks now and then, which cuts the CPU time spent on mobs nobody can see.

The ranges are in blocks, and each entity group has its own:

• animals: cows, sheep, pigs, chickens and other passive mobs. Default 32
• monsters: zombies, skeletons, creepers, spiders. Default 32
• raiders: pillagers, vindicators and other raid mobs. Default 64, so raids still work at a distance
• misc: items, experience orbs, minecarts and other non-mob entities. Default 16
• water: squid, fish, dolphins and other water mobs. Default 16
• villagers: villagers and wandering traders. Default 32
• flying-monsters: phantoms, ghasts and other flying hostile mobs. Default 32

Lowering these ranges is one of the cheapest ways to get tick time back on a busy server. The Performance preset uses 16 for animals, 24 for monsters and 8 for misc and water, which is a common starting point. Going lower than that starts to show: mobs a short walk away freeze in place, and players notice.

Farms and activation range

Inactive entities are the reason some farms work in single player and slow down on Spigot. A mob farm that relies on mobs walking into a kill chamber works less well when the mobs are outside the monster range of the AFK spot. Villager breeders and iron farms depend on villagers ticking, which is what tick-inactive-villagers is for. It is on by default and keeps villagers ticking even outside their range. Turn it off only if you know your players do not run villager farms, since that is the setting that breaks them.

If players report that a farm is slow, check how far the farm is from where they stand. Moving the AFK spot closer often fixes it without raising the range for the whole server.

Entity tracking range

Tracking range is a different setting that sounds similar. It controls how far away, in blocks, an entity is sent to players' clients. An entity beyond the range still exists and still ticks (subject to activation range), but players do not see it. Lower tracking ranges mean less network traffic and less work building entity updates.

The defaults are 128 for players, 96 for animals, monsters and misc, 128 for display entities and 64 for everything else. Two rules help here:

1. Tracking range is capped by the view distance. An entity in a chunk the player has not loaded is never sent, so a range of 128 blocks does nothing on a server with a view distance of 6 chunks (96 blocks).
2. Player tracking affects PvP. On a PvP server, players expect to see each other at a distance. Keep the player range high and lower the ranges for mobs and misc entities instead.

Item frames and paintings count as misc. On a server with large map walls, a low misc range makes the walls pop in as players walk up to them.

View distance and simulation distance

view-distance and simulation-distance in spigot.yml are set to default, which means "use the value from server.properties". The reason to set them here instead is per-world control: you can keep a view distance of 10 in the Overworld and use 6 in the Nether, where players see less anyway.

• view-distance is how many chunks the server sends to each player in every direction. It drives memory use and network traffic.
• simulation-distance is how many chunks around each player are ticked: mobs move, crops grow, redstone runs. It drives CPU use.

A simulation distance lower than the view distance is the usual trade: players still see far, but the server only runs the area close to them. The optimal server.properties settings post goes through recommended values by server size, and the server.properties generator writes the global values if you leave these on default.

mob-spawn-range sets how many chunks around a player mobs can spawn in. Keep it at or below the simulation distance. Mobs that spawn outside the simulated area never move and only count against the mob cap.

Item merging and despawn rates

Dropped items of the same type within merge-radius.item blocks of each other merge into one entity with a larger stack. Experience orbs do the same within merge-radius.exp. Fewer entities means less to tick and track, which helps most around mob farms and big explosions.

The defaults are 2.5 blocks for items and 3 for experience. Values up to about 4 are safe. Much larger values cause items to jump visibly across the ground, merge through walls, and confuse item sorters that expect items to stay in their water stream.

item-despawn-rate is how long a dropped item lasts, in ticks (20 ticks is one second). The default of 6000 matches vanilla: five minutes. Lowering it clears drops sooner but costs players items when they die far from their base. arrow-despawn-rate covers arrows stuck in blocks. It defaults to 1200 (one minute), and lowering it to 300 or 600 is harmless on most servers.

nerf-spawner-mobs

With nerf-spawner-mobs on, mobs from spawners have no AI. They do not walk, attack or look around, but they still drop loot when killed. This saves a lot of CPU on servers where players build spawner grinders. It changes how some grinders behave, so test your players' farm designs before turning it on for an existing world.

Hopper settings

Hoppers are one of the most common sources of lag on survival servers, because each one checks for items to pull every tick. Spigot gives you three settings:

• ticks-per.hopper-transfer: ticks a hopper waits after moving an item. The default of 8 matches vanilla hopper speed
• ticks-per.hopper-check: ticks between checks for items to pull in when the hopper is idle. The default is 1, every tick
• hopper-amount: items moved per transfer. The default is 1

Setting hopper-check to 8, the same as hopper-transfer, is the standard hopper optimization. A hopper can only move one item every 8 ticks anyway, so checking on every tick in between does not make it faster. All the presets except Spigot Defaults do this.

Raising hopper-transfer together with hopper-amount keeps throughput the same with fewer, larger moves (for example 16 ticks and 2 items). That breaks redstone that counts items or relies on hopper timing, such as hopper clocks and comparator sorters, so most servers leave it alone.

hopper-can-load-chunks lets a hopper load the chunk it points into. Leave it off unless a specific build needs it. With it on, a hopper chain along a chunk border can keep extra chunks loaded.

Server settings

The settings section covers the whole server.

bungeecord

Set bungeecord: true when the server runs behind a BungeeCord or Waterfall proxy with ip_forward enabled. It makes the server accept the player's real IP address and UUID from the proxy. Without it, every player shows up with the proxy's IP and an offline-mode UUID.

This setting has a security side. A backend server in BungeeCord mode trusts whatever the proxy sends, and it runs with online-mode=false in server.properties. If players can reach the backend port directly, they can join with any name and UUID, including an operator's. Firewall the backend port so that only the proxy can connect, or use a plugin such as BungeeGuard.

For a Velocity proxy, bungeecord: true pairs with Velocity's legacy forwarding mode. The recommended modern forwarding mode is configured in Paper's own config instead, and the Velocity config builder explains both.

Restart and watchdog

restart-script is the script Spigot runs for the /restart command. restart-on-crash runs the same script when the watchdog decides the server has crashed. The watchdog does that when a single tick takes longer than timeout-time seconds (60 by default), and it prints a thread dump to the console first. That dump is the most useful thing to look at when a server freezes.

If your host or a process manager already restarts the server when it stops, set restart-on-crash to false so the two do not fight over it.

Other settings

netty-threads is the number of threads that handle network traffic. The default of 4 is enough for servers with a few hundred players. user-cache-size is how many player names and UUIDs are kept in usercache.json, and save-user-cache-on-stop-only writes that file at shutdown instead of on every login, which saves a small amount of disk work. log-villager-deaths and log-named-deaths write a console line when a villager or a name-tagged mob dies, which helps when players ask what happened to their pets.

Messages

The messages section sets the text players see when they are kicked or type an unknown command. {0} in the outdated client and server messages is replaced with the server's version. The messages accept & color codes, so &cYou are not whitelisted! shows in red. The MOTD generator has a full table of the codes.

YAML treats a value that starts with & as special syntax, so any message that starts with a color code has to be quoted. The generated file quotes those values for you.

Recommended values by server type

• Small SMP (under 20 players): the Balanced SMP preset. Default ranges, hopper-check: 8, slightly larger merge radius. Players rarely notice any change
• Busy survival or low memory: the Performance preset. Lower activation and tracking ranges, view distance 8 and simulation distance 6, spawner mobs nerfed
• Backend behind a proxy: the Behind BungeeCord preset, then lock down the backend port
• Technical or redstone-heavy servers: start from Spigot Defaults and change only the tracking ranges. Activation range and hopper changes are what technical players notice first

Measure before and after. The understanding Minecraft TPS post explains how to read TPS and MSPT, and how to fix Minecraft server lag covers the causes that config changes do not fix. Pre-generating the world with Chunky, covered in pre-generating chunks with Chunky, removes much of the lag from players exploring new terrain.

Common mistakes

• Tabs in the file. YAML only allows spaces for indentation. A single tab makes Spigot fail to load the file, print an error, and fall back to defaults. Use the downloaded file as it is, or an editor that inserts spaces
• Editing while the server runs. Spigot saves the file when it starts, and your changes only apply after a restart. Stop the server, edit the file, then start it
• Setting ranges too low. An activation range of 8 for monsters saves CPU and breaks every mob farm on the server. Lower in small steps
• Tracking ranges above the view distance. They have no effect beyond the chunks a player has loaded, so they only make the file harder to read
• BungeeCord mode with an open backend port. Anyone who finds the port can join as any player. Firewall it
• Changing hopper timing on a technical server. Item sorters and hopper clocks depend on vanilla timing

How to install the generated spigot.yml

1. Stop the server.
2. Back up the current spigot.yml in the server folder, next to server.properties.
3. Upload the downloaded spigot.yml in its place, or copy only the sections you changed into the existing file.
4. Start the server and check the console for YAML errors near the top of the log.
5. Open spigot.yml again: Spigot will have added every key the generated file left out, with its default value.

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