Relauncher: Seamless JVM Restart for Minecraft

What Is Relauncher and Why Your Modpack Needs It

Minecraft modding often feels like a delicate balancing act. You tweak garbage collection flags, set system properties, or add a Java agent, only to realize your launcher doesn't pass those arguments the way you need. Relauncher solves that headache by restarting the JVM with extra arguments before the game even begins to load. It's a tiny library that drops into your mods folder and works across nearly every Minecraft version from 1.6.4 to the latest snapshot, plus Hytale Server as an early or regular plugin.

Think of it as a transparent middleman. The relaunch happens so early that external launchers see a single continuous process with no extra windows or orphaned processes. Modpack creators love it because other mods can trigger a relaunch programmatically after installing dependencies or configuring the environment — perfect for javaagents, module layers, or any setup that demands precise JVM tuning.

How Relauncher Works Under the Hood

Relauncher attempts three restart strategies in order of preference, all handled automatically:

• POSIX exec (Linux / macOS) — calls execvp() through a native Rust library to replace the current process in-place. Same PID, zero overhead, the cleanest possible restart.
• Windows DLL — hooks DllMain(DLL_PROCESS_DETACH) to spawn a child process after the JVM shuts down completely. Standard I/O streams are duplicated beforehand so they survive the teardown, and the parent waits for the child, forwarding its exit code.
• Pure Java fallback — uses ProcessBuilder and waitFor to start a child process with inherited I/O. The original process sticks around for the duration of the game session, but it works everywhere.

This layered approach means Relauncher adapts to your operating system and available native libraries without any manual intervention. On Linux and macOS, the POSIX exec strategy keeps the same process ID, which can be crucial for scripts or monitoring tools that track the game by PID.

Supported Versions and Loaders

One of Relauncher's standout features is its broad compatibility. The same universal JAR works across all these environments:

• Forge (LaunchWrapper) — Minecraft 1.6.4 to 1.12.2, using ITweaker via manifest.
• Forge (ModLauncher) — 1.13.2 and above, via ITransformationService through SPI.
• NeoForge (ModLauncher) — up to 1.21.1, same ITransformationService mechanism.
• NeoForge (FancyModLoader) — 1.21.3+, using IModFileCandidateLocator via SPI.
• Fabric — 1.14 and newer, through PreLaunchEntrypoint in fabric.mod.json.
• Quilt — 1.14+, reusing Fabric's PreLaunchEntrypoint.
• Hytale Server — both early (ClassTransformer SPI) and regular plugin (JavaPlugin via manifest.json) modes.

Java versions 8 through 25 are supported on Linux, Windows, and macOS, for both x86_64 and aarch64 architectures. That means you can use Relauncher on modern ARM-based Macs without any extra steps.

Installation and Configuration

Getting started takes only a few steps:

1. Download the universal JAR (relauncher-universal-<version>.jar) from the project's releases page.
2. Place it into your mods/ folder.
3. Launch the game once. Relauncher will generate a config file at config/relauncher/config.cfg.
4. Open that file, set enabled = true, and add your JVM arguments one per line.
5. Relaunch the game, and your custom flags take effect immediately.

For those who prefer a streamlined experience, the foxygame.net launcher offers a convenient, flexible, and modern way to manage your Minecraft mods; you can download relauncher directly from its built-in mod menu, making setup a breeze. The configuration file itself is straightforward: comments start with #, blank lines are ignored, and each non-comment line becomes an extra JVM argument. The enabled flag only controls the config file's own arguments — if another mod provides a CommandLineProvider SPI implementation, the relaunch will happen regardless of that flag.

Editions: Full vs. CurseForge

Relauncher ships two editions of each JAR. The Full edition bundles native libraries for all platforms, so all three restart strategies work out of the box. The CurseForge edition omits those native binaries to comply with CurseForge's distribution policy, leaving only the pure Java fallback strategy available.

This distinction matters most on Windows, where the CurseForge edition cannot use GetCommandLineW() to read the original command line. Instead, it reconstructs arguments from system properties, which can be inaccurate when tools like ForgeWrapper mutate java.class.path. Linux and macOS users are unaffected because they can read /proc/self/cmdline directly. However, the CurseForge edition still contains all JNI declarations, so if you manually place the native libraries in the launcher's native folder, the full native strategies activate automatically.

Launcher Compatibility

Relauncher works seamlessly with most popular launchers:

• Vanilla — fully supported.
• PrismLauncher — fully supported, with a workaround for system properties.
• CurseForge — fully supported, delegating to vanilla behavior.
• Modrinth — fully supported, using a Theseus wrapper workaround.
• ATLauncher — fully supported.
• MultiMC — not supported. It relies on a stdin protocol that can't be replayed after relaunch. A warning is logged and the relaunch is skipped. If you use MultiMC, consider applying JVM arguments manually or switching to a compatible launcher.

For Mod Developers: API and SPI

If you're building a mod that needs to restart the JVM programmatically, Relauncher exposes a clean API. Add relauncher-core as a compile-only dependency from Maven Central:

repositories { mavenCentral() }
dependencies { compileOnly 'com.juanmuscaria:relauncher-core:<version>' }

Then call Relauncher.relaunch() with a list of extra arguments. The method returns a RelaunchResult that tells you whether the relaunch failed or was skipped, so you can handle it gracefully in your mod's logic.

You can also inject arguments without calling the API directly by implementing the CommandLineProvider interface and registering it via Java's ServiceLoader. Relauncher scans the mods folder for service files on its own, so your mod doesn't even need to be on the classpath yet. This is ideal for modpack tooling that sets up javaagents or system properties before the game fully initializes. You can also check Relauncher.isRelaunched() and Relauncher.getDepth() to adjust behavior inside a relaunched JVM.

Debugging and Building from Source

If something goes wrong, add -Drelauncher.debug=true to your launcher's JVM arguments. This logs the full command-line extraction, argument assembly, and strategy selection process, making it easy to pinpoint why a relaunch isn't working as expected.

For those who want to build from source, the project uses Gradle 9 and Java 17+ as a toolchain (the output still targets Java 8). Cross-compiling the native Rust libraries requires cross, cargo-xwin, cargo-zigbuild, and the Zig toolchain. The build scripts handle everything with ./gradlew build and ./build-natives.sh.

Conclusion

Relauncher strips away the friction of JVM argument management in Minecraft modding. Whether you're fine-tuning garbage collection, injecting a javaagent, or building a modpack that demands a pristine startup environment, this library delivers a reliable, cross-platform restart mechanism that feels invisible to the player. Its broad version support, intelligent strategy selection, and developer-friendly API make it a must-have for anyone who wants to take full control of their Minecraft Java process without wrestling with launcher settings. Drop it in your mods folder, tweak a config file, and let Relauncher handle the rest.