From ab14e1c276650d5cf0a23d4db1fa53667529c5e9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Feb 2026 00:50:58 +0000 Subject: [PATCH] docs: Add comprehensive JVM optimization guide for game servers Created complete optimization guide (500+ lines): Modern JVM Flags (2024-2026 Best Practices): - Aikar's Flags optimized for Minecraft - G1GC configuration for 4-16GB heaps - Per-server RAM recommendations (all 11 servers) - Deprecated flags to remove Server-Specific Configuration: - Vanilla: 4GB (lightweight) - Standard modpacks: 8GB - Heavy modpacks: 10-12GB - ATM10: 16GB (kitchen sink) - Custom G1HeapRegionSize per heap size Implementation: - 3-phase deployment (backup, update, monitor) - Via Pterodactyl panel startup variables - 1 hour total for all 11 servers - Rollback procedure included Performance Impact: - Expected +0.5 to +2 TPS improvement - More stable memory usage - Shorter GC pause times - Fewer lag spikes Comprehensive troubleshooting for common issues. Ready to execute via Pterodactyl panel. Task: Game Server Startup Script Audit (Tier 3) FFG-STD-002 compliant --- .../optimization-guide.md | 513 ++++++++++++++++++ 1 file changed, 513 insertions(+) create mode 100644 docs/tasks/game-server-startup-script-audit-&-optimization/optimization-guide.md diff --git a/docs/tasks/game-server-startup-script-audit-&-optimization/optimization-guide.md b/docs/tasks/game-server-startup-script-audit-&-optimization/optimization-guide.md new file mode 100644 index 0000000..4adb522 --- /dev/null +++ b/docs/tasks/game-server-startup-script-audit-&-optimization/optimization-guide.md @@ -0,0 +1,513 @@ +# Game Server Startup Script Audit & Optimization - Complete Guide + +**Status:** Ready to Execute +**Priority:** Tier 3 - Performance Optimization +**Time Estimate:** 1 hour (all 11 servers) +**Last Updated:** 2026-02-17 + +--- + +## Overview + +Comprehensive audit and optimization of JVM startup flags for all 11 Minecraft servers. Modernize flags, optimize memory allocation, and improve performance using current best practices for Java 17/21. + +**Benefits:** +- Reduced lag and improved TPS +- Better garbage collection performance +- Optimized memory usage +- Fewer crashes and OOM errors +- Future-proofed for modern Java versions + +--- + +## Current Server List (11 Servers) + +**TX1 Dallas (5 servers):** +1. Vanilla 1.21.11 +2. All The Mons +3. Stoneblock 4 +4. Society: Sunlit Valley +5. Reclamation + +**NC1 Charlotte (6 servers):** +6. The Ember Project +7. Minecolonies: Create and Conquer +8. All The Mods 10 +9. Homestead +10. EMC Subterra Tech +11. Hytale (non-Minecraft) + +--- + +## Modern JVM Optimization Strategy + +### Java Version Considerations + +**For Minecraft 1.20+:** Java 17 or 21 (recommended) +**For older modpacks:** Java 17 minimum +**Never use:** Java 8 (outdated, poor performance) + +--- + +## Recommended JVM Flags (2024-2026 Best Practices) + +### For Servers with 8-16GB RAM (Most Servers) + +```bash +java -Xms8G -Xmx8G \ + -XX:+UseG1GC \ + -XX:+ParallelRefProcEnabled \ + -XX:MaxGCPauseMillis=200 \ + -XX:+UnlockExperimentalVMOptions \ + -XX:+DisableExplicitGC \ + -XX:+AlwaysPreTouch \ + -XX:G1NewSizePercent=30 \ + -XX:G1MaxNewSizePercent=40 \ + -XX:G1HeapRegionSize=8M \ + -XX:G1ReservePercent=20 \ + -XX:G1HeapWastePercent=5 \ + -XX:G1MixedGCCountTarget=4 \ + -XX:InitiatingHeapOccupancyPercent=15 \ + -XX:G1MixedGCLiveThresholdPercent=90 \ + -XX:G1RSetUpdatingPauseTimePercent=5 \ + -XX:SurvivorRatio=32 \ + -XX:+PerfDisableSharedMem \ + -XX:MaxTenuringThreshold=1 \ + -Dusing.aikars.flags=https://mcflags.emc.gs \ + -Daikars.new.flags=true \ + -jar server.jar nogui +``` + +**These are Aikar's Flags (2024 edition) - proven optimal for Minecraft.** + +--- + +### For ATM10 (16GB+ RAM, Memory-Hungry Modpack) + +```bash +java -Xms16G -Xmx16G \ + -XX:+UseG1GC \ + -XX:+ParallelRefProcEnabled \ + -XX:MaxGCPauseMillis=200 \ + -XX:+UnlockExperimentalVMOptions \ + -XX:+DisableExplicitGC \ + -XX:+AlwaysPreTouch \ + -XX:G1NewSizePercent=30 \ + -XX:G1MaxNewSizePercent=40 \ + -XX:G1HeapRegionSize=16M \ + -XX:G1ReservePercent=20 \ + -XX:G1HeapWastePercent=5 \ + -XX:G1MixedGCCountTarget=4 \ + -XX:InitiatingHeapOccupancyPercent=15 \ + -XX:G1MixedGCLiveThresholdPercent=90 \ + -XX:G1RSetUpdatingPauseTimePercent=5 \ + -XX:SurvivorRatio=32 \ + -XX:+PerfDisableSharedMem \ + -XX:MaxTenuringThreshold=1 \ + -Dusing.aikars.flags=https://mcflags.emc.gs \ + -Daikars.new.flags=true \ + -jar server.jar nogui +``` + +--- + +### For Vanilla (Lightweight, 4-6GB RAM) + +```bash +java -Xms4G -Xmx4G \ + -XX:+UseG1GC \ + -XX:+ParallelRefProcEnabled \ + -XX:MaxGCPauseMillis=200 \ + -XX:+UnlockExperimentalVMOptions \ + -XX:+DisableExplicitGC \ + -XX:+AlwaysPreTouch \ + -XX:G1HeapRegionSize=8M \ + -XX:G1ReservePercent=20 \ + -XX:G1HeapWastePercent=5 \ + -XX:G1MixedGCCountTarget=4 \ + -XX:InitiatingHeapOccupancyPercent=15 \ + -XX:G1MixedGCLiveThresholdPercent=90 \ + -XX:SurvivorRatio=32 \ + -XX:+PerfDisableSharedMem \ + -XX:MaxTenuringThreshold=1 \ + -jar server.jar nogui +``` + +--- + +## Flag Explanations + +### Memory Allocation + +**-Xms and -Xmx (ALWAYS SET EQUAL)** +- `-Xms8G` - Initial heap size +- `-Xmx8G` - Maximum heap size +- **Critical:** Must be equal to avoid heap resizing overhead +- **Rule:** Allocate 80% of available RAM to Minecraft + +**Why equal?** Prevents Java from dynamically resizing heap (causes lag spikes) + +--- + +### Garbage Collection (G1GC) + +**-XX:+UseG1GC** +- Use G1 Garbage Collector (best for Minecraft) +- Designed for large heaps (>4GB) +- Low pause times +- Better than CMS, ZGC, or Shenandoah for MC + +**-XX:MaxGCPauseMillis=200** +- Target max GC pause time: 200ms +- Lower = more frequent but shorter pauses +- 200ms is sweet spot for Minecraft + +**-XX:+ParallelRefProcEnabled** +- Process references in parallel +- Reduces GC pause time + +--- + +### G1GC Tuning + +**-XX:G1NewSizePercent=30** +**-XX:G1MaxNewSizePercent=40** +- Young generation size: 30-40% of heap +- Optimized for Minecraft's object creation patterns + +**-XX:G1HeapRegionSize=8M (or 16M for large heaps)** +- Size of G1 heap regions +- 8M for <16GB heaps +- 16M for 16GB+ heaps + +**-XX:G1ReservePercent=20** +- Reserve 20% of heap to prevent full GC +- Safety margin for allocation spikes + +**-XX:InitiatingHeapOccupancyPercent=15** +- Start concurrent GC when heap is 15% full +- Earlier start = smoother collection + +--- + +### Performance Flags + +**-XX:+AlwaysPreTouch** +- Pre-touch all memory at startup +- Prevents lazy allocation lag during gameplay + +**-XX:+DisableExplicitGC** +- Ignore System.gc() calls from mods +- Prevents mods from triggering GC unnecessarily + +**-XX:+PerfDisableSharedMem** +- Disable JVM performance data collection +- Reduces disk I/O + +**-XX:MaxTenuringThreshold=1** +- Promote objects to old generation quickly +- Optimized for Minecraft's object lifecycle + +--- + +## Deprecated Flags to REMOVE + +**Remove these if found in current startup scripts:** + +```bash +# REMOVE - Outdated +-XX:+UseConcMarkSweepGC # Use G1GC instead +-XX:+CMSParallelRemarkEnabled +-XX:+CMSIncrementalMode +-XX:+CMSClassUnloadingEnabled + +# REMOVE - Deprecated in Java 17+ +-XX:+AggressiveOpts +-XX:+UseAdaptiveSizePolicy + +# REMOVE - Can cause issues +-XX:+UseStringDeduplication # Can cause memory leaks +-Xmn (explicit young gen size) # Let G1 manage it + +# REMOVE - Not helpful +-server # Default in modern Java +``` + +--- + +## Server-Specific Recommendations + +### Vanilla 1.21.11 +**RAM:** 4GB (Xms4G -Xmx4G) +**Reason:** Vanilla is lightweight +**Special:** None needed + +### All The Mons (Cobblemon) +**RAM:** 8GB (Xms8G -Xmx8G) +**Reason:** Moderate mod count +**Special:** None + +### Stoneblock 4 +**RAM:** 8GB (Xms8G -Xmx8G) +**Reason:** Skyblock with tech mods +**Special:** None + +### Society: Sunlit Valley +**RAM:** 8GB (Xms8G -Xmx8G) +**Reason:** Moderate modpack +**Special:** None + +### Reclamation +**RAM:** 8GB (Xms8G -Xmx8G) +**Reason:** Moderate modpack +**Special:** None + +### The Ember Project +**RAM:** 10GB (Xms10G -Xmx10G) +**Reason:** Large modpack +**Special:** None + +### Minecolonies: Create and Conquer +**RAM:** 12GB (Xms12G -Xmx12G) +**Reason:** Minecolonies is RAM-hungry +**Special:** May need more if colonies grow large + +### All The Mods 10 (ATM10) +**RAM:** 16GB (Xms16G -Xmx16G) +**Reason:** Kitchen sink modpack, very large +**Special:** G1HeapRegionSize=16M for large heap +**Note:** Known memory leak - monitor closely + +### Homestead +**RAM:** 8GB (Xms8G -Xmx8G) +**Reason:** Moderate modpack +**Special:** None + +### EMC Subterra Tech +**RAM:** 10GB (Xms10G -Xmx10G) +**Reason:** Tech-focused modpack +**Special:** None + +--- + +## Implementation Procedure + +### Phase 1: Backup Current Scripts (5 min) + +```bash +# On TX1 and NC1 +cd /var/lib/pterodactyl/volumes + +# Backup all startup scripts +for server in */; do + if [ -f "${server}start.sh" ]; then + cp "${server}start.sh" "${server}start.sh.backup.$(date +%Y%m%d)" + fi +done +``` + +--- + +### Phase 2: Update via Pterodactyl Panel (40 min) + +**For each server:** + +1. Log into panel.firefrostgaming.com +2. Navigate to server +3. Go to **Startup** tab +4. Edit **Java Arguments** field +5. Replace with recommended flags (from above) +6. Click **Save** +7. Restart server +8. Monitor for 10 minutes + +**Test checklist per server:** +- Server starts successfully +- Players can join +- TPS remains stable (use `/tps` or `/forge tps`) +- No errors in console +- Memory usage is stable + +--- + +### Phase 3: Monitor Performance (15 min) + +**Check after 24 hours:** +- TPS average (should be 19.5-20) +- GC pause times (check logs) +- Memory usage patterns +- Player reports of lag + +**Tools:** +- Pterodactyl console +- `/tps` command in-game +- Server logs for GC messages + +--- + +## Pterodactyl Startup Variable + +**In Pterodactyl, the startup command looks like:** + +``` +java {{JAVA_ARGS}} -jar {{SERVER_JARFILE}} nogui +``` + +**The {{JAVA_ARGS}} variable is where you paste the optimization flags.** + +**Example for 8GB server:** + +``` +-Xms8G -Xmx8G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true +``` + +--- + +## Common Issues & Solutions + +### Server Won't Start After Update + +**Issue:** Server crashes on startup + +**Check:** +- RAM allocation doesn't exceed available RAM +- Java version is compatible (17 or 21) +- No typos in flags + +**Fix:** +- Restore backup: `start.sh.backup.YYYYMMDD` +- Reduce RAM allocation +- Verify Java version: `java -version` + +--- + +### Worse Performance After Update + +**Issue:** TPS lower than before + +**Possible causes:** +- RAM allocation too high (swapping to disk) +- G1HeapRegionSize wrong for heap size +- Java version incompatibility + +**Fix:** +- Reduce RAM allocation by 2GB +- For <16GB heap, use `G1HeapRegionSize=8M` +- For 16GB+ heap, use `G1HeapRegionSize=16M` + +--- + +### Memory Leaks (ATM10) + +**Issue:** Memory usage keeps climbing + +**ATM10 specific:** Known memory leak in some versions + +**Solution:** +- Increase restart frequency (use staggered restart system) +- Monitor memory usage via Pterodactyl +- Alert when usage hits 90% +- Restart before OOM + +--- + +## Performance Testing + +### Before Optimization (Record Baseline) + +For each server, record: +- Average TPS (check over 1 hour) +- Memory usage (initial, average, peak) +- GC frequency and pause time +- Player complaints + +### After Optimization (Compare) + +Same metrics after 24 hours: +- TPS should improve by 0.5-2 +- Memory usage should be more stable +- GC pauses should be shorter +- Fewer lag spikes + +--- + +## Documentation Template + +**After updating each server, document:** + +``` +Server: [Name] +Date: 2026-02-17 +Previous Flags: [paste old flags] +New Flags: [paste new flags] +RAM: [old] → [new] +Java Version: [version] + +Performance: +- TPS Before: X.X +- TPS After: X.X +- Improvement: +X.X TPS +- Notes: [any observations] +``` + +Save in: `docs/reference/startup-optimization-log.md` + +--- + +## Rollback Procedure + +**If optimization causes problems:** + +```bash +# Via Pterodactyl panel: +1. Go to Startup tab +2. Restore previous flags from backup +3. Save and restart + +# Or via SSH (if needed): +cd /var/lib/pterodactyl/volumes/[uuid]/ +mv start.sh.backup.YYYYMMDD start.sh +# Restart via panel +``` + +--- + +## Additional Optimizations (Optional) + +### CPU Affinity (Advanced) + +Pin specific servers to specific CPU cores for better performance: + +```bash +taskset -c 0-7 java [flags...] -jar server.jar nogui +``` + +**Example:** Pin ATM10 to cores 0-15 (first 16 cores) + +### Huge Pages (Advanced) + +Enable huge pages for better memory performance: + +```bash +# Add to JVM flags +-XX:+UseTransparentHugePages +``` + +--- + +## References + +- **Aikar's Flags:** https://mcflags.emc.gs (official source) +- **G1GC Documentation:** https://docs.oracle.com/en/java/javase/17/gctuning/ +- **Minecraft Optimization Guide:** https://github.com/brucethemoose/Minecraft-Performance-Flags-Benchmarks + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️ + +--- + +**Document Status:** COMPLETE +**Ready to Execute:** When Pterodactyl panel access available (1 hour) +**Risk Level:** LOW (easy rollback via backups) +**Expected Improvement:** +0.5 to +2 TPS per server