What's tuned here
Every change is checked against Leaf's own source and issue tracker before it ships. This page is the same breakdown as the project README, kept in sync by hand.
Branding
Every brand-facing string reads AtlasSpigot — the early [bootstrap] startup line, the console banner, the console window title, MOTD, server-list name, crash reports, the client-facing F3 brand text, and Bukkit.getName() (what plugins check for compatibility). This works even with zero config present, because it's fixed at the actual source of truth: the Brand-Name attribute baked into the jar's build manifest.
Two config files were renamed too, with matching source changes so the rename is real, not cosmetic: purpur.yml → atlas.yml, config/leaf-global.yml → config/atlas-global.yml.
Performance
| Area | Setting | What it does |
|---|---|---|
| JVM/GC | start.sh — Aikar's flags, G1GC | Tuned for an 8GB heap. -XX:+AlwaysPreTouch deliberately left out — it roughly doubles startup time for a marginal, usually unnoticeable steady-state gain. |
| Chunks | region-format: B_LINEAR | Smaller world files on disk. LINEAR_V2 was tested and rejected — Leaf's own config prints a stability warning for it on boot; B_LINEAR showed none. |
| Chunks | Chunk load/send rate uncapped, async chunk packet sending | Chunks reach players as fast as the server can push them instead of being artificially throttled. |
| Scale | view-distance/simulation-distance: 10/10 → 6/4 | The biggest lever for per-player memory/CPU cost at high concurrent player counts. |
| Scale | entity-tracking-range roughly halved | Less network/CPU overhead in crowded areas — this cost scales with entities × nearby players. |
| Scale | max-joins-per-tick: 5 → 25 | Removes an artificial ~100/sec cap on how fast a mass-reconnect queue drains. |
| Mobs/AI | Distance-based AI throttling (DAB) | Entities far from any player tick less often. |
| World | ALTERNATE_CURRENT redstone engine, optimize-explosions | Well-established, largely vanilla-compatible engine swaps for two of the heaviest world-simulation hot paths. |
| World | optimized-powered-rails | Rewrites powered/activator rail update propagation to run from a single rail instead of each block iterating separately — up to 4x faster toggling, same vanilla order. |
| I/O | dont-save-primed-tnt, dont-save-falling-block | Skips writing these to disk on chunk save/unload — cuts I/O when a lot of TNT is active. Trade-off: those entities don't survive an unload+reload. |
| Network | Reduced entity move/motion packets, disabled decorative particles, larger item merge radius | Less per-tick network chatter and fewer duplicate item-entity ticks in busy areas. |
| World | cache-biome (mob spawning + advancements) | Memoizes biome lookups on the hot paths that call them repeatedly per tick. Pure cache, same results — its past correctness bugs are closed and fixed upstream, verified against the issue tracker before enabling. |
| Threading | Virtual threads for the Bukkit async scheduler and profile-download pool | Same JDK 21 virtual-thread swap already used for the async chat executor, extended to the other two background thread pools with no gameplay effect. |
| Memory | Ring-buffer combat tracker (MC-301114) | Worth being precise: Paper already fixes this leak and that fix is already active here, so this doesn't add protection — it swaps the mechanism. Paper scans and trims the entry list on every damage event; Leaf uses an O(1) ring buffer that evicts the oldest entry automatically. Same cap, same result, cheaper per-hit path. |
Deliberately not enabled
Checked and rejected, with reasons — not just left at defaults by omission.
optimize-entity-activation
Briefly enabled in v8/v9, then reverted. Reading the ~76-line patch, it looked safe (just deduplicates entity collection across overlapping player activation ranges, same DAB/priority logic). What that read missed: Leaf's own source tags the field @Experimental, an explicit signal from the maintainers that they don't consider it fully battle-tested yet. Caught during a full re-verification pass (boot log showed the experimental-module warning) and reverted before it shipped any further.
optimize-mob-spawning, optimize-random-tick
Both are deep rewrites of core vanilla mechanics (mob spawning, and the random ticks driving crop growth/leaf decay/fire spread). optimize-mob-spawning's own patch notes say it "reduce[s] random calls" — a real change to vanilla's RNG consumption pattern, not just speed. Not enabled without being able to verify they're truly behavior-preserving.
parallel-world-ticking
Leaf's own issue tracker has a real, open cluster of concurrency bugs tied to this exact experimental feature (crashes, a memory leak, thread blocking).
sleeping-block-entity
(Lithium-derived hopper/comparator sleep optimization) Broad surface area across hoppers, comparators, and inventory tracking, with a real history of closed bugs specifically about hopper item collection at chunk edges. Fixed since, but too much surface to fully re-verify for this build.
async-pathfinding
No @Experimental tag, but the issue tracker currently has an open PR ("fix async pathfinding tick rate") against it — an unresolved, acknowledged bug. Open issues are a hard no by themselves, tag or not.
faster-random-generator
Not @Experimental either, but its own boot-time log entry warns that enabling it offsets slime chunk locations from vanilla — a real, admitted behavior deviation, not just a speed change. Left off to stay behavior-preserving.
skip-inactive-entity-for-execute-command
Changes which entities /execute selectors actually return (skips ones outside AI activation range) — a real, visible difference for command-block and datapack-heavy servers, not a transparent perf win. Its one past bug (a datapack crash) is closed and fixed, but the behavior change itself is the reason this stays off by default.
OptimizeNonFlushPacketSending
A genuinely cheaper packet-send path, but upstream's own config comment states it is NOT compatible with ProtocolLib and may break other plugins that touch packet handling. Too much of the plugin ecosystem depends on that to enable by default.
async-switch-state
Moves connection state switching off the main thread — it rewires the login/configuration protocol state machine across Connection and both packet listeners. No @Experimental tag and no open issues, but concurrency bugs in the join handshake are exactly the kind that only appear under real concurrent logins. Not enabled on the strength of a clean single-player boot.
throttle-mob-spawning, entity-goal.start-tick-chance, cactus-check-survival
All three trade gameplay for speed rather than being free. The first two change spawn rates and AI responsiveness; the third stops cacti growing where they'd immediately break — which is precisely the mechanic cactus farms are built on.
optimize-end-surface-gen
Skips part of the End surface rule build. Upstream's own comment flags possible incompatibility with datapacks that modify End generation — a conditional break, but a real one, and this build ships to servers whose datapacks it can't know about.
mc-270656, mc-152094
Real vanilla bug fixes (an advancement mis-grant and End City ships cut at chunk borders), but neither buys any performance, and mc-152094 changes what actually generates — moving worlds further from vanilla rather than closer. The one vanilla-bug-fix that is enabled, MC-301114, is in because it's a memory fix, not a gameplay one.
How settings are actually screened
Not vibes — a checklist, applied the same way every time before anything gets enabled.
- 1Read the actual patch/diff, not just the config comment.
- 2Check for an explicit upstream caution flag: Leaf's @Experimental/@Deprecated annotations, or Paper's own unsupported-settings config section. Either one is treated as a hard no by itself.
- 3Search Leaf's issue tracker for open reports mentioning the feature.
- 4Boot with it enabled and read the entire log, not a grep for expected lines.
- 5Where practical, verify past just "it booted" — a simulated client completing login, or a deliberately-broken config proving a setting actually does what it claims.
A full pass through every currently-enabled setting is done periodically, not just when adding something new — that's how the entity-activation regression above got caught two releases after it shipped, not zero.
First-boot startup time
A brand-new world has to generate its spawn chunks before the server can finish starting — a one-time cost tied to the host's CPU allocation. A single-vCPU container will always take longer here; expect 30–60s on the very first boot. Once the world exists on disk, restarts skip generation entirely.
Handling a lot of players
The tuning above genuinely raises what one instance can hold on limited RAM — but there's a real ceiling. A single JVM has a per-player memory/CPU floor that no setting erases. Getting into the thousands of concurrent players is a Velocity proxy in front of multiple backend instances, not a single-server config problem.