Paper, Purpur, and the other plugin servers add configuration far beyond server.properties — extra YAML files where you tune performance, mob behaviour, and quality-of-life tweaks. This guide is a careful tour of the ones worth knowing, with an honest rule running through it: change one thing at a time, and when in doubt, leave the default alone. The Paper team ships sensible defaults; most keys exist for people with a specific problem to solve.
| At a glance | |
|---|---|
| You need | A server running Paper, Purpur, or another Paper fork |
| Time | Twenty minutes to find your way around; a lifetime to master |
| Plan | Any — every setting here is editable on the free plan |
Two ways to edit these files
The Config editor (easiest). The panel detects which config files your server has and gives each one a structured editor — labelled fields, descriptions, and the right input type (toggle, number, dropdown) instead of raw text. It's the same page family as your server.properties editor; the known keys come with plain-English labels so you're not guessing what keep-spawn-loaded means. This is the safe way to change a value without breaking the file's formatting.
The File Manager (full control). Every key lives in a real file you can open in the File Manager. Here's where each one is:
| File | Path | What it's for |
|---|---|---|
server.properties |
/server.properties |
Vanilla settings (covered here) |
bukkit.yml |
/bukkit.yml |
Spawn limits, chunk GC, autosave interval |
spigot.yml |
/spigot.yml |
Spigot tweaks, view/mob limits, BungeeCord mode |
paper-global.yml |
/config/paper-global.yml |
Server-wide Paper settings |
paper-world-defaults.yml |
/config/paper-world-defaults.yml |
Per-world Paper defaults |
purpur.yml |
/purpur.yml |
Purpur's extra gameplay knobs (Purpur only) |
🎯 Good to know: Paper 1.19 split the old single
paper.ymlinto paper-global.yml (settings that apply to the whole server) and paper-world-defaults.yml (defaults each world inherits). On older versions you'll still see onepaper.ymlin the root. The panel labels whichever ones your server actually has.
The golden rules
Editing configs is where people break working servers, so internalise these first:
- Take a backup before you start. One bad edit can stop the server from booting.
- One change, one restart, one test. Change several keys at once and you won't know which one caused the problem. YAML changes need a full restart — most of these are read only at startup.
- Mind the YAML. Indentation is significant, values are
key: valuewith a space after the colon, and booleans are lowercasetrue/false. The structured editor sidesteps all of this — reach for the raw file only when you must. - Don't chase settings you don't understand. A key you can't explain is a key you shouldn't touch.
paper-global.yml — server-wide settings
These apply to the entire server, not one world. The stable, worth-knowing ones:
| Setting | What it does |
|---|---|
| Max joins per tick | How many players the server lets in per tick. Lower it if a rush of joins lags the server; the default is fine for small servers. |
Anti-Xray (anti-xray.enabled) |
Paper's built-in x-ray protection — hides ores from clients so cheaters can't see them through stone. Engine mode 1 replaces ores with stone (light); mode 2 uses random blocks (stronger, heavier). Turn it on for survival servers. |
| Proxy forwarding | Where you configure Velocity/BungeeCord forwarding when this server sits behind a proxy — see server networks. |
paper-world-defaults.yml — per-world tuning
This is where most performance tuning lives, because it governs how each world simulates entities and chunks. The classics:
| Setting | What it does |
|---|---|
Despawn ranges (despawn-ranges.soft / .hard) |
How far from a player mobs start to despawn (soft) and are forced to despawn (hard). Lowering both trims entity load on a busy world. |
| Entity per-chunk save limits | Caps how many arrows, XP orbs, etc. are saved per chunk (-1 = unlimited). Stops arrow machines and mob farms from bloating chunk files. |
| Keep spawn loaded | Holds spawn chunks in memory always. Turning it off frees memory on servers where nobody hangs around spawn. |
| Optimize explosions | Uses Paper's faster explosion maths. Safe to leave on. |
Faster redstone (use-faster-eigencraft-redstone) |
An optimised redstone implementation — helps redstone-heavy worlds, occasionally changes edge-case timing. |
| Armor stands tick | Whether armor stands run their tick logic. Decorative-only servers can disable it for a free performance win. |
| Max auto-save chunks per tick | Spreads autosave work out so saves don't cause a stutter. |
💡 Tip: For lag specifically, start with
view-distanceandsimulation-distancein server.properties and a profiler — these Paper keys are the second pass. The performance guide covers the order that actually matters.
purpur.yml — the fun extras
Running Purpur? It adds a large set of gameplay toggles on top of Paper. A taste of the stable, popular ones:
| Setting | What it does |
|---|---|
| Lobotomize villagers | Reduces the AI of villagers that can't pathfind (like those in trading halls). A big performance saver on trading-heavy servers. |
| Ender chest six rows | Expands ender chests from 27 to 54 slots. |
| Barrel rows | Changes barrel storage size (vanilla is 3 rows / 27 slots). |
| Alternate keepalive | Fewer timeout disconnects for players on shaky connections. |
| TPS catchup | Lets the server speed back up to catch up after a lag spike. |
| AFK broadcasts & tab prefixes | Built-in AFK messages and tab-list markers, no plugin needed. |
| Server mod name | The brand shown on the F3 debug screen. |
Verify it works
After a restart, the console should log the config loading cleanly with no "Failed to load" or YAML parse errors near the top. Then confirm the behaviour in-game — join and check that the thing you changed actually changed. If the server refuses to boot, the config is almost always the cause: read the top of the console, it names the file and line.
Troubleshooting
- Server won't start after an edit — a YAML syntax slip (bad indentation, a missing space after a colon, a tab character). The console points at the file and line. Fix it, or restore your backup.
- My change did nothing — you edited the wrong file, or didn't restart. Per-world settings live in
paper-world-defaults.yml; a restart is required for all of these. - Purpur settings missing —
purpur.ymlonly exists when the server runs Purpur. Switch software in the Version Changer first. - A key isn't in the panel's editor — the structured editor labels the well-known keys and shows the rest as-is; brand-new or obscure keys appear without a friendly label. Check the official docs for what it does.
Next steps
- Make your server yours — the
server.propertiesside - Fixing Minecraft lag — where performance tuning should really start
- Backups — take one before every config session
- Paper and Purpur own the full reference, with every key, its default, and what changed between versions — read docs.papermc.io before trusting any key you found in a random forum post.