Every Spigot.yml Setting Explained

Where Spigot.yml Fits In

Even if you run Paper or Purpur, you still have a spigot.yml file. Paper inherits from Spigot, so Spigot's configuration layer is always active. Some settings in spigot.yml are overridden or extended by Paper's own config files, and this guide notes where that happens. If a setting exists in both spigot.yml and paper-world-defaults.yml, the Paper value takes priority.

The file lives in your server root directory alongside server.properties and bukkit.yml. Changes require a server restart, /reload does not reliably apply spigot.yml modifications.

Global Settings

These settings appear under the top-level settings: key and affect the entire server.

bungeecord

settings:
  bungeecord: false

What it does: Enables BungeeCord IP forwarding. When true, the server accepts forwarded player IPs and UUIDs from a BungeeCord or Waterfall proxy. Important: Only set this to true if your server actually sits behind a BungeeCord proxy. Enabling it on a standalone server is a critical security vulnerability, it allows anyone to spoof any player's UUID and log in as them. If you use Velocity instead of BungeeCord, leave this false and configure modern forwarding in Paper's config instead.

player-shuffle

settings:
  player-shuffle: 0

What it does: When set to a value greater than 0, Spigot shuffles the order in which players are processed every N ticks. This prevents players who joined first from consistently getting priority in tick processing. Recommended: 0 (disabled) for most servers. Only relevant on very large servers (200+) where tick order fairness matters for PvP.

save-user-cache-on-stop-only

settings:
  save-user-cache-on-stop-only: false

What it does: When true, the user cache (username-to-UUID mappings) is only written to disk on server shutdown. When false, it writes on every player join/leave. Recommended: true, reduces disk writes significantly on busy servers. The only risk is losing recent cache entries if the server crashes, which simply means those players need to be re-looked-up on next login. The performance gain is worth it.

moved-wrongly-threshold and moved-too-quickly-multiplier

settings:
  moved-wrongly-threshold: 0.0625
  moved-too-quickly-multiplier: 10.0

What they do: Anti-cheat thresholds for player movement. moved-wrongly-threshold determines how much positional error is tolerated before rubber-banding. moved-too-quickly-multiplier caps maximum movement speed relative to vanilla walking speed. Recommended: Keep defaults unless you have plugins that modify player speed (vehicles, mounts, custom abilities) and players report getting rubber-banded. In that case, raise moved-too-quickly-multiplier to 15.0 or 20.0.

netty-threads

settings:
  netty-threads: 4

What it does: Number of threads allocated to Netty for handling network I/O. Default 4 is sufficient for servers up to 200 players. On high-population servers (300+), increasing to 6-8 can reduce network latency. Going above 8 provides diminishing returns.

World Settings

These settings appear under world-settings: and can be configured per-world or under the default: key for all worlds.

entity-tracking-range

world-settings:
  default:
    entity-tracking-range:
      players: 48
      animals: 48
      monsters: 48
      misc: 32
      display: 128
      other: 64

What it does: The maximum distance (in blocks) at which the server sends entity position data to clients. Entities beyond this range are invisible to the player. Recommended values:

Category	Default	Performance	Notes
players	48	48	Never lower, breaks PvP visibility
animals	48	32-40	Players rarely need to see animals at 48 blocks
monsters	48	32-40	Reducing saves bandwidth; mobs still exist, just invisible far away
misc	32	16-24	Covers item frames, dropped items, experience orbs
display	128	64-96	Text/block displays for plugins; lower if not using display entities
other	64	48	Covers minecarts, boats, and other misc entities

Lowering tracking ranges is one of the most effective bandwidth optimizations. Each tracked entity requires regular position update packets. On a server with 1,000 animals loaded across all players, reducing animal tracking from 48 to 32 blocks can cut animal-related network traffic by 50%.

mob-spawn-range

world-settings:
  default:
    mob-spawn-range: 8

What it does: The radius (in chunks, not blocks) around each player where mobs can spawn. Default is 8 chunks (128 blocks). Recommended: 6 for better performance, 3-4 for aggressive optimization on laggy servers. This value interacts with bukkit.yml spawn limits and Paper's despawn ranges, lowering it without adjusting those can result in mobs clumping near players or spawning too densely in a small area. Refer to the mob spawning guide for balanced values.

entity-activation-range

world-settings:
  default:
    entity-activation-range:
      animals: 32
      monsters: 32
      raiders: 48
      misc: 16
      water: 16
      villagers: 32
      flying-monsters: 32
      villagers-work-immunity-after: 100
      villagers-work-immunity-for: 20
      villagers-active-for-panic: true
      tick-inactive-villagers: true
      wake-up-inactive:
        animals-max-per-tick: 4
        animals-every: 1200
        animals-for: 100
        villagers-max-per-tick: 4
        villagers-every: 600
        villagers-for: 100
        monsters-max-per-tick: 8
        monsters-every: 400
        monsters-for: 100
        flying-monsters-max-per-tick: 8
        flying-monsters-every: 200
        flying-monsters-for: 100

What it does: Entity activation range is one of the most impactful performance settings in the entire server. Mobs outside the activation range stop running their full AI, they do not pathfind, attack, or perform complex behaviors. They still exist and are visible, but they are essentially frozen until a player comes within range.

Recommended values: Lowering these ranges is the single easiest way to improve TPS on mob-heavy servers. For a 50-player server:

• animals: 16, animals do not need AI beyond 16 blocks. They just stand around.
• monsters: 24, gives mobs enough range to notice and path toward players, but saves AI cycles on distant zombies staring at walls.
• villagers: 16, villagers in trading halls only need to work when a player is nearby.
• water: 12, fish and squid AI is expensive relative to how little players interact with them.
• misc: 8, items and XP orbs rarely need activation at distance.

tick-inactive-villagers: When true, villagers outside the activation range still restock their trades. Keep this true or players will complain that villager trades never refresh.

The wake-up-inactive section periodically activates a few dormant entities to prevent them from being permanently frozen. The defaults are reasonable. Only lower monsters-every on servers with severe TPS problems.

merge-radius

world-settings:
  default:
    merge-radius:
      item: 2.5
      exp: 3.0

What it does: The distance within which dropped items or experience orbs merge into a single entity. Higher values mean more aggressive merging, which reduces entity count but can look odd (items teleporting together from far away). Recommended: item: 3.5 and exp: 6.0. This merges items and XP more aggressively, significantly reducing entity counts near mob farms and mining areas. The visual trade-off is minimal.

growth modifiers

world-settings:
  default:
    growth:
      cactus-modifier: 100
      cane-modifier: 100
      melon-modifier: 100
      mushroom-modifier: 100
      pumpkin-modifier: 100
      sapling-modifier: 100
      beetroot-modifier: 100
      carrot-modifier: 100
      potato-modifier: 100
      wheat-modifier: 100

What it does: Percentage modifiers for crop and plant growth speed. 100 is vanilla speed, 200 is double speed, 50 is half speed. Recommended: Keep at 100 for survival servers. On skyblock or economy servers where you want faster farming cycles, 150-200 works well. On economy servers, be cautious, faster growth means more items entering the economy, which can cause inflation if sell prices are not adjusted accordingly.

hunger

world-settings:
  default:
    hunger:
      jump-walk-exhaustion: 0.05
      jump-sprint-exhaustion: 0.2
      combat-exhaustion: 0.1
      regen-exhaustion: 6.0
      swim-multiplier: 0.01
      sprint-multiplier: 0.1
      other-multiplier: 0.0

What it does: Controls how quickly players lose hunger from different activities. Recommended: Keep vanilla values unless your server has a specific gameplay reason to change them. Some survival servers reduce all values by 50% to make hunger less punishing, which is popular with casual player bases but trivializes food mechanics.

ticks-per

world-settings:
  default:
    ticks-per:
      hopper-transfer: 8
      hopper-check: 1

hopper-transfer: How often (in ticks) hoppers move items. Default 8 means hoppers transfer one item every 0.4 seconds. Raising to 16 or 24 slows hopper speed but dramatically reduces the performance cost of hopper-heavy builds. On servers with large item sorters or auto-farms, this is a significant optimization. Recommended: 8 for vanilla behavior, 16 for balanced performance, 24+ for servers where hopper lag is a problem.

hopper-check: How often hoppers check for items above them. Default 1 (every tick) is expensive. Paper overrides this with its own hopper optimization, so on Paper servers this setting has limited effect.

Summary: Most Impactful Spigot Settings

If you only change five things in spigot.yml, make it these:

1. entity-activation-range, Lower animals to 16, monsters to 24, villagers to 16
2. merge-radius, Raise item to 3.5 and exp to 6.0
3. entity-tracking-range, Lower animals and monsters to 32
4. mob-spawn-range, Reduce from 8 to 6
5. save-user-cache-on-stop-only, Set to true

These five changes alone can improve TPS by 10-30% on a busy server. Combine them with the settings in paper-world-defaults.yml and bukkit.yml for the full picture.

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.