Using the Launcher

Learn how to launch Minecraft instances and configure launch settings

The Modrinth launcher provides powerful options for launching and managing your Minecraft instances with optimal performance and customization.

Launching Minecraft Instances

Starting your game is simple and straightforward:

1. Select your profile

   Click on the profile/instance you want to play from your library.

2. Launch the game

   Click the Play button. The launcher will:

   • Verify all required files are present
   • Download any missing components
   • Install Minecraft if not already installed
   • Apply your launch settings
   • Start the game
3. Wait for startup

   The game will initialize and load. You can see the progress in the launcher.

On first launch, the launcher will automatically install the correct version of Minecraft, the mod loader, and all required dependencies. This may take a few minutes.

Launch Process

When you click Play, the launcher:

1. Validates installation: Checks if Minecraft and the mod loader are installed
2. Downloads assets: Retrieves any missing game files, libraries, or assets
3. Runs processors: Executes Forge/NeoForge processors if needed
4. Prepares Java: Ensures the correct Java version is available
5. Executes hooks: Runs pre-launch hooks if configured
6. Starts game: Launches Minecraft with your configured settings

Java Version Management

The launcher automatically manages Java installations for optimal compatibility:

Automatic Java Installation

• The launcher detects the required Java version for each Minecraft version
• If the correct version isn’t found, it’s automatically downloaded and installed
• Different profiles can use different Java versions as needed

Java Version Requirements:

• Minecraft 1.17 and below: Java 8
• Minecraft 1.18-1.20.4: Java 17
• Minecraft 1.20.5+: Java 21

Using Custom Java

You can specify a custom Java installation for each profile:

1. Open profile settings

   Right-click your profile and select Edit or click the settings icon.

2. Navigate to Java settings

   Go to the Java section in profile settings.

3. Select Java installation

   Choose from detected Java installations or browse to a custom java or javaw.exe executable.

4. Save settings

   Click Save to apply your custom Java configuration.

Using an incorrect Java version may cause crashes or prevent the game from launching. Always use the recommended version for your Minecraft version.

Memory Allocation Settings

Proper memory allocation is crucial for performance, especially with mods:

Setting Memory Allocation

Global Settings

Set default memory for all profiles:

1. Open Settings (gear icon)
2. Navigate to Java & Memory
3. Adjust Maximum Memory slider
4. Click Save

This applies to all profiles unless overridden.

Per-Profile Settings

Set memory for a specific profile:

1. Right-click the profile and select Edit
2. Go to Java & Memory
3. Enable Override global settings
4. Adjust Maximum Memory slider
5. Click Save

Memory Recommendations

Vanilla / Light Mods

2-4 GB

Sufficient for vanilla Minecraft or modpacks with few mods.

Medium Modpacks

4-6 GB

Good for modpacks with 50-100 mods or moderate world generation mods.

Large Modpacks

6-8 GB

Recommended for extensive modpacks with 100+ mods or heavy performance mods.

Extreme Modpacks

8-12+ GB

For very large modpacks, heavy shaders, or high render distances.

Don’t allocate all your system RAM to Minecraft. Leave at least 2-4 GB for your operating system and other applications.

Game Arguments and JVM Flags

Customize how Minecraft and Java run with advanced arguments:

JVM Arguments

JVM flags control Java Virtual Machine behavior:

1. Open settings

   Go to Settings → Java & Memory (or profile-specific settings).

2. Add JVM arguments

   In the JVM Arguments field, add your custom flags.

3. Common JVM flags

   # Garbage collection optimization
   -XX:+UseG1GC
   -XX:+ParallelRefProcEnabled
   -XX:MaxGCPauseMillis=200
   -XX:+UnlockExperimentalVMOptions
   -XX:+DisableExplicitGC
   
   # Memory optimization
   -XX:G1NewSizePercent=30
   -XX:G1MaxNewSizePercent=40
   -XX:G1HeapRegionSize=8M
   -XX:G1ReservePercent=20
   
   # Performance tuning
   -XX:G1HeapWastePercent=5
   -XX:G1MixedGCCountTarget=4
   -XX:InitiatingHeapOccupancyPercent=15
   

Game Arguments

Minecraft-specific launch arguments:

• Resolution: Set custom window size
• Fullscreen: Force fullscreen mode
• Server: Quick-connect to a server on launch
• World: Auto-load a singleplayer world

Incorrect JVM flags can cause crashes or poor performance. Only modify these if you know what you’re doing, or use tested optimization arguments.

Environment Variables

Set custom environment variables for your game:

1. Open profile settings
2. Navigate to Environment Variables
3. Add key-value pairs as needed
4. Click Save

Common use cases:

• GPU selection for multi-GPU systems
• Library paths for custom natives
• Debugging flags

Launch Hooks

Execute custom commands at different points in the launch process:

Pre-Launch Hook

Runs before Minecraft starts:

# Example: Start a Discord bot
/path/to/script.sh

# Example: Clean up temp files
rm -rf /path/to/temp/*

Useful for:

• Starting companion programs
• Cleaning temporary files
• Setting up environment

Wrapper

Wraps the Java command:

# Example: Run with custom wrapper
gamemode

# Example: Use custom Java environment
optirun

Useful for:

• Performance tools (GameMode)
• GPU switching (optirun, primusrun)
• Debugging tools

Post-Exit Hook

Runs after Minecraft closes:

# Example: Backup world
/path/to/backup-script.sh

# Example: Upload logs
/path/to/upload-logs.sh

Useful for:

• Backups
• Log processing
• Cleanup tasks

Hooks are shell commands. They must be properly quoted and escaped. If a pre-launch hook fails (non-zero exit code), the game won’t launch.

Troubleshooting Launch Issues

Game Won’t Launch

Check Java Installation

• Verify the correct Java version is installed
• Try auto-installing Java through the launcher
• Check Java path in profile settings

Verify Game Files

1. Right-click the profile
2. Select Repair/Reinstall
3. Wait for the process to complete
4. Try launching again

Review Logs

1. Click the Logs button after a failed launch
2. Look for error messages or exceptions
3. Common issues:
   • OutOfMemoryError: Increase memory allocation
   • ClassNotFoundException: Mod incompatibility
   • UnsatisfiedLinkError: Wrong Java architecture

Disable Mods

Test if a mod is causing the issue:

1. Disable all mods
2. Launch the game
3. Re-enable mods one by one to find the culprit

Performance Issues

• Low FPS:

  • Increase memory allocation
  • Add performance mods (Sodium, Lithium)
  • Lower render distance
  • Adjust JVM arguments

• Stuttering:

  • Adjust GC flags
  • Increase memory allocation
  • Close background applications

• Long loading times:

  • Check disk speed (SSD recommended)
  • Reduce number of mods
  • Increase memory allocation

Crashes

1. Check crash reports: Located in crash-reports/ folder
2. Update mods: Ensure all mods are compatible versions
3. Check Java version: Use the recommended version
4. Review mod compatibility: Some mods conflict with each other
5. Clean install: Delete and reinstall the profile if needed