Performance tuning

Skill Teddy563/mcwrench/skills/performance-tuning

AI Minecraft server admin that audits configs, fixes lag, sets up proxies and permissions, picks plugin stacks, and learns any plugin's docs on demand. Works in Claude Code, Claude.ai, Codex, Antigravity, and Gemini CLI.

Install

npx -y skills add Teddy563/mcwrench --skill performance-tuning

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Diagnoses and fixes Minecraft server lag, low TPS, high MSPT, GC pauses and out-of-memory crashes. Use whenever the user says "my server is laggy", "low TPS", "TPS drops", "high MSPT", "stuttering", "freezing", "out of memory", "OOM", "GC pause", "what JVM flags", "Aikar's flags", "how much RAM", "Xmx", "view-distance", "simulation-distance", "entity activation range", "mob farms lagging", "hopper lag", "chunk lag", "spark profiler", or asks how to make their Paper/Purpur/Folia server run faster. Covers Spark profiling, Aikar's flags vs Generational ZGC on Java 25, heap sizing, view/simulation distance, entity activation ranges, mob spawn limits, hopper and chunk tuning. Prefer this skill over guessing; quote real flag and config values.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.5 KB, as published. Nobody here has run it

Performance Tuning

Diagnose first, tune second. Never hand someone a wall of flags without measuring.

Step 1 — Measure with Spark

Spark (spark.lucko.me) is the modern profiler (replaces Timings; Paper bundles it). See references/spark-cheatsheet.md. The minimum diagnostic loop:

/spark tps and /spark health — is it a TPS problem, an MSPT spike problem, or memory?
/spark profiler start --timeout 300 during the lag, then read the uploaded flame graph.
For memory pressure / GC churn: /spark profiler start --alloc, /spark gc, /spark heapsummary.

Identify whether the cost is the main thread (ticking: entities, hoppers, redstone, chunk gen), GC, or I/O (world saves, plugin storage on slow disk).

Step 2 — Heap & JVM flags

See references/aikars-flags.md for the full verified flag set and sizing rules. Key points:

Xms == Xmx. Leave 1–1.5 GB headroom for the OS + JVM native memory beyond the heap.
Aikar's flags are G1GC-tuned and remain the proven default on the official PaperMC page.
Java 25 nuance: Paper 26.1+ requires Java 25. Hosting/community guidance (e.g. WinterNode — NOT PaperMC's own docs) recommends not pairing Aikar's G1 flags with Java 25's Generational ZGC; choose one GC. Present Aikar's/G1 as the safe default and ZGC as an alternative to benchmark, and never mix the two flag sets.
On memory-capped containers (Pterodactyl/Pelican), -XX:+AlwaysPreTouch can cause "Cannot allocate memory" at boot — drop it there.

Step 3 — Config tuning (biggest wins first)

In observed frequency order:

view-distance / simulation-distance (server.properties, spigot.yml, per-world paper-world.yml). The lower of the configured values wins per world. Typical sane values: view 6–10, simulation 4–6. Anarchy/huge servers go lower.
Mob farms / entity load — spigot.yml: entity-activation-range, mob-spawn-range, Paper per-player mob spawns; cap with entity-per-chunk-save-limit for experience_orb, arrow, ender_pearl, item.
Hoppers — paper-world.yml hopper tuning / transfer-cooldown; reduce move-event overhead on hopper-heavy economies.
Chunk storms — cap player-max-chunk-load-rate (~100.0) for exploration-heavy servers.
Redstone clocks / lag machines — find them in the Spark profile and address the build.
Sync I/O — move LuckPerms/world storage off slow disks; stagger autosaves.

Output

Give a concrete diff: the exact keys to change, their current vs recommended values, and the expected effect. Tie every recommendation back to what the Spark profile showed — if you have no profile, ask for one (or list the top 3 likely causes and how to confirm each).