Relauncher
面向基于 Java 的应用程序的 JVM 重新启动库。将单个 JAR 放入你的模组文件夹中,它即可在 Minecraft 1.6.4 至最新版本之间工作,或者作为早期插件或常规插件在 Hytale Server 上运行。
功能说明
Relauncher 会在游戏加载之前透明地重启 JVM 进程并添加额外的参数。这适用于以下场景:
- 添加 JVM 标志 - GC 调优、
-XX:+AlwaysPreTouch、系统属性等,无需触碰启动器设置
- 整合包工具支持 - 其他模组可以在安装依赖项或配置环境(如 javaagents、模块层等)后以编程方式触发重新启动
重新启动发生在启动过程的极早期阶段,在任何重要的游戏状态初始化之前。外部启动器会看到一个单一且连续的进程,没有额外的窗口,也没有孤立的进程残留。
支持的版本
| Loader |
Minecraft 版本 |
入口点 |
| Forge (LaunchWrapper) |
1.6.4 - 1.12.2 |
ITweaker via manifest |
| Forge (ModLauncher) |
1.13.2+ |
ITransformationService via SPI |
| NeoForge (ModLauncher) |
up to 1.21.1 |
ITransformationService via SPI |
| NeoForge (FancyModLoader) |
1.21.3+ |
IModFileCandidateLocator via SPI |
| Fabric |
1.14+ |
PreLaunchEntrypoint via fabric.mod.json |
| Quilt |
1.14+ |
Uses Fabric's PreLaunchEntrypoint |
| Hytale Server (early) |
- |
ClassTransformer SPI |
| Hytale Server (plugin) |
- |
JavaPlugin via manifest.json |
Java 版本:8 到 25
平台:Linux、Windows 和 macOS,支持 x86_64 和 aarch64。
安装方法
- 下载通用 JAR 文件 (
relauncher-universal-<version>.jar)
- 将其放入你的
mods/ 文件夹中
- 启动游戏一次,它将在
config/relauncher/config.cfg 处创建配置文件
- 编辑配置文件以添加 JVM 参数并将
enabled = true
- 重新启动游戏
配置
配置文件位于 <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
配置中的 enabled 标志仅控制配置文件自身的参数。如果另一个模组提供了 CommandLineProvider SPI 实现,无论此标志如何,都会发生重新启动。
工作原理
Relauncher 按优先级顺序尝试三种策略来重启 JVM:
-
POSIX exec (Linux / macOS) - 通过原生 Rust 库调用 execvp() 就地替换当前进程。PID 相同,零开销,最干净的重新启动方式。
-
Windows DLL - 挂钩 DllMain(DLL_PROCESS_DETACH) 以便在 JVM 完全关闭后派生子进程。在此之前会复制 stdin/stdout/stderr 以确保它们在清理过程中存活。父进程等待子进程完成并转发其退出代码。
-
Fallback (纯 Java) - 启动带有继承 I/O 的子进程,等待其完成后停止。适用于所有平台,但原始进程会在整个游戏会话期间保留。
启动器兼容性
| Launcher |
Status |
| Vanilla |
Fully supported |
| PrismLauncher |
Fully supported (system properties workaround) |
| CurseForge |
Fully supported (delegates to vanilla) |
| Modrinth |
Fully supported (theseus wrapper workaround) |
| ATLauncher |
Fully supported |
| MultiMC |
Not supported - relies on a stdin protocol that can't be replayed after relaunch. A warning is logged and the relaunch is skipped. Consider switching launchers or applying the arguments manually. |
给模组开发者
API 依赖
将 relauncher-core 添加为仅编译依赖项——通用 JAR 将在运行时存在:
dependencies {
compileOnly 'com.juanmuscaria:relauncher-core:<version>'
}
编程式重新启动
如果你的模组需要重启 JVM(例如在安装 javaagent 之后),直接调用 Relauncher.relaunch():
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 (result.isFailed()) {
logger.error("Relaunch failed: " + result.reason());
} else if (result.isSkipped()) {
logger.warn("Relaunch skipped: " + result.reason());
}
SPI 提供者
你也可以在不直接调用 API 的情况下注入 JVM 参数,只需实现 CommandLineProvider 并通过 ServiceLoader 注册即可。
Relauncher 会自动扫描 mods 文件夹中的服务文件,因此你的模组甚至尚未加入类路径也可以工作。
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; // 数值越小,优先级越高(越先运行)
}
}
在 META-INF/services/com.juanmuscaria.relauncher.CommandLineProvider 中注册:
com.example.mymod.MyProvider
检查重新加载状态
Relauncher.isRelaunched() // 如果我们处于已重新加载的 JVM 中,则返回 true
Relauncher.getDepth() // 0 = 原始进程,1 = 第一次重新加载,以此类推
调试
在启动器的 JVM 参数中添加 -Drelauncher.debug=true。这将记录完整的命令行提取、参数组装和策略选择过程。有助于排查为什么重新加载没有按预期工作。
从源码构建
./gradlew build # 完整构建
./build-natives.sh # 交叉编译原生库
你需要 Java 17+(用作工具链;输出仍针对 Java 8)以及 Gradle 9。
要交叉编译原生 Rust 库,你还需要 cross、cargo-xwin、
cargo-zigbuild 以及 Zig 工具链。
许可证
Mozilla Public License 2.0
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
| Loader |
Minecraft Versions |
Entry Point |
| Forge (LaunchWrapper) |
1.6.4 - 1.12.2 |
ITweaker via manifest |
| Forge (ModLauncher) |
1.13.2+ |
ITransformationService via SPI |
| NeoForge (ModLauncher) |
up to 1.21.1 |
ITransformationService via SPI |
| NeoForge (FancyModLoader) |
1.21.3+ |
IModFileCandidateLocator via SPI |
| Fabric |
1.14+ |
PreLaunchEntrypoint via fabric.mod.json |
| Quilt |
1.14+ |
Uses Fabric's PreLaunchEntrypoint |
| Hytale Server (early) |
- |
ClassTransformer SPI |
| Hytale Server (plugin) |
- |
JavaPlugin via manifest.json |
Java versions: 8 through 25
Platforms: Linux, Windows, and macOS, on both x86_64 and aarch64.
Installation
- Download the universal JAR (
relauncher-universal-<version>.jar)
- Drop it into your
mods/ folder
- Launch the game once, it will create a config file at
config/relauncher/config.cfg
- Edit the config to add your JVM arguments and set
enabled = true
- 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.
How it works
Relauncher tries three strategies to restart the JVM, in order of preference:
-
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.
-
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.
-
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
| Launcher |
Status |
| Vanilla |
Fully supported |
| PrismLauncher |
Fully supported (system properties workaround) |
| CurseForge |
Fully supported (delegates to vanilla) |
| Modrinth |
Fully supported (theseus wrapper workaround) |
| ATLauncher |
Fully supported |
| MultiMC |
Not supported - relies on a stdin protocol that can't be replayed after relaunch. A warning is logged and the relaunch is skipped. Consider switching launchers or applying the arguments manually. |
For Mod Developers
API dependency
Add relauncher-core as a compile-only dependency - the universal JAR will be present at runtime:
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
评论 0
登录后参与评分
还没有评论,来抢沙发吧