relauncher

Relauncher

JVM relaunch library for Java based applications. Drop a single JAR into your mods folder, and it should work from Minecraft 1.6.4 to the latest version, or on Hytale Server as an early plugin or regular plugin.

What it does

Relauncher restarts the JVM process with additional arguments transparently and before the game loads. This is useful for:

• Adding JVM flags - GC tuning, -XX:+AlwaysPreTouch, system properties, etc., without needing to touch launcher settings
• Modpack tooling - other mods can trigger a relaunch programmatically after installing dependencies or configuring the environment (javaagents, module layers, you name it)

The relaunch happens very early during startup, before any significant game state is initialized. External launchers see a single continuous process with no extra windows, no orphaned processes.

Supported Versions

Java versions: 8 through 25

Platforms: Linux, Windows, and macOS, on both x86_64 and aarch64.

Installation

1. Download the universal JAR (relauncher-universal-<version>.jar)
2. Drop it into your mods/ folder
3. Launch the game once, it will create a config file at config/relauncher/config.cfg
4. Edit the config to add your JVM arguments and set enabled = true
5. Relaunch the game

Configuration

The config file is at <game directory>/config/relauncher/config.cfg:

# Relauncher Configuration
# Extra JVM arguments to add when relaunching, one per line.
# Lines starting with # are comments, blank lines are ignored.

# Set to false to disable relaunching without removing your arguments.
enabled = true

# Add extra JVM arguments below, one per line:
-XX:+UseG1GC
-XX:+AlwaysPreTouch
-Dsome.java.property=true

The config enabled flag only controls the config file's own arguments. If another mod provides a CommandLineProvider SPI implementation, the relaunch will happen regardless of this flag.

Editions

The project produces two editions of each JAR:

• Full (default) - includes native libraries for all platforms. Supports all three relaunch strategies listed below.
• CurseForge (-curseforge classifier) - identical to the full edition but without bundled native libraries. Only the pure-Java fallback strategy is available out of the box. CurseForge does not permit bundled native binaries, so this edition exists to comply with their distribution policy.

Features not available in the CurseForge edition (without manually providing natives):

Windows users: Without the native library, the CurseForge edition cannot use GetCommandLineW() to read the original command line. It falls back to reconstructing it from system properties, which can be inaccurate when launchers or tools like ForgeWrapper mutate java.class.path or other JVM state. This may cause the relaunch to fail or produce incorrect behavior on Windows. Linux and macOS are unaffected as they can read /proc/self/cmdline.

The CurseForge edition still contains all JNI declarations, so if you manually place the native libraries in the launcher's native library folder, the native strategies and accurate command-line extraction will activate automatically.

How it works

Relauncher tries three strategies to restart the JVM, in order of preference:

1. POSIX exec (Linux / macOS) - calls execvp() through a native Rust library to replace the current process in-place. Same PID, zero overhead, cleanest possible restart.

2. Windows DLL - hooks DllMain(DLL_PROCESS_DETACH) to spawn a child process after the JVM has fully shut down. stdin/stdout/stderr are duplicated beforehand so they survive the teardown. The parent waits for the child and forwards its exit code.

3. Fallback (pure Java) - starts a child process with inherited I/O, waits for it to finish, then halts. Works everywhere, but the original process sticks around for the duration of the game session.

Launcher Compatibility

For Mod Developers

API dependency

relauncher-core is published on Maven Central. Add it as a compile-only dependency - the universal JAR will be present at runtime:

repositories {
    mavenCentral()
}

dependencies {
    compileOnly 'com.juanmuscaria:relauncher-core:<version>'
}

Programmatic relaunch

If your mod needs to restart the JVM (e.g., after installing a javaagent), call Relauncher.relaunch() directly:

import com.juanmuscaria.relauncher.Relauncher;
import com.juanmuscaria.relauncher.RelaunchResult;

List<String> extraArgs = Arrays.asList("-Dfoo=bar", "-XX:+AlwaysPreTouch");
RelaunchResult result = Relauncher.relaunch(extraArgs);

// If we get here, the relaunch didn't happen
if (result.isFailed()) {
    logger.error("Relaunch failed: " + result.reason());
    } else if (result.isSkipped()) {
    logger.warn("Relaunch skipped: " + result.reason());
    }

SPI provider

You can also inject JVM arguments without calling the API directly, just implement CommandLineProvider and register it via 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.

import com.juanmuscaria.relauncher.CommandLineProvider;

public class MyProvider implements CommandLineProvider {
    @Override
    public List<String> extraJvmArguments() {
        return Collections.singletonList("-Dmy.mod.installed=true");
    }

    @Override
    public int priority() {
        return 0; // lower = runs first
    }
}

Register it in META-INF/services/com.juanmuscaria.relauncher.CommandLineProvider:

com.example.mymod.MyProvider

Checking relaunch state

Relauncher.isRelaunched()  // true if we're inside a relaunched JVM
Relauncher.getDepth()      // 0 = original, 1 = first relaunch, etc.

Debugging

Add -Drelauncher.debug=true to your launcher's JVM arguments. This logs the full command-line extraction, argument assembly, and strategy selection process. Useful for figuring out why a relaunch isn't working the way you expect.

Building from source

./gradlew build                           # Full build
./build-natives.sh                        # Cross-compile native libraries

You'll need Java 17+ (used as a toolchain; the output still targets Java 8) and Gradle 9. For cross-compiling the native Rust libraries you'll also need cross, cargo-xwin, and cargo-zigbuild, and Zig toolchain.

License

Mozilla Public License 2.0