GuidesOnly show guides for your app
GuidesGuidesA guided tour of paper-global.yml, paper-world-defaults.yml, and purpur.yml — where the files live, the panel's structured Config editor, and the handful of stable keys worth touching.
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 |
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.
Editing configs is where people break working servers, so internalise these first:
key: value with a space after the colon, and booleans are lowercase true/false. The structured editor sidesteps all of this — reach for the raw file only when you must.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. |
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.
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. |
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.
paper-world-defaults.yml; a restart is required for all of these.purpur.yml only exists when the server runs Purpur. Switch software in the Version Changer first.server.properties side