firefrost-operations-manual/docs/tasks/game-server-startup-script-audit-&-optimization/optimization-guide.md

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)

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)

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)

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:

# 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)

# 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:

# 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:

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:

# 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