FLFHMCL — Fabric Loader for Hello Minecraft! Launcher

将 Fabric Loader 挂载到 HMCL 自身，使 Fabric mod 可以通过 Mixin 扩展 HMCL 功能。

开源协议：LGPL-2.1-only

功能特性

核心功能

• Fabric Loader 桥接 — 将 HMCL 封装为 Fabric GameProvider，运行在 KnotClassLoader 下
• Mixin 支持 — 任何 Fabric mod 均可通过 @Mixin 注入 HMCL 的 Java 类
• Mod 发现 — 自动扫描 mods/ 目录加载 Fabric mod
• Java Agent 引导 — 通过 -javaagent:FLFHMCL.jar 在 premain 阶段启动 Fabric Loader，无需修改 HMCL 自身

日志系统

• Log4j 集成 — 将 Fabric Loader 的日志输出路由到 Log4j 2
• SLF4J 桥接 — log4j-slf4j2-impl 使所有 SLF4J 调用也路由到 Log4j
• 可配置 — 通过 log4j2.xml 自定义日志级别和输出格式
• 调试模式 — -Dflfhmcl.debug=true 启用 DEBUG 级日志

模组兼容性

• HMCL 版本注册 — 将 HMCL 注册为 Fabric 内置模组 (hmcl)，其他 mod 可通过 depends 声明版本依赖
• FLFHMCL 版本注册 — 将 FLFHMCL 自身也注册为内置模组 (flfhmcl)
• 版本号标准化 — 自动将非语义版本（如 3.16.SNAPSHOT）标准化为语义版本（如 3.16.0）
• HMCL 版本号系统属性 — flfhmcl.hmclVersion 供运行时检查

错误处理

• 原生错误对话框 — 模组兼容性错误或引导失败时，使用 Swing 显示错误详情窗口，不依赖 JavaFX
• 详细错误信息 — 显示完整异常栈

游戏启动

• KnotClassLoader 托管 — HMCL 运行在 Fabric 的类加载器下
• 自动代理注入 — lwjgl-unsafe-agent 自动注入以解决 LWJGL 内存问题
• JavaFX 自动发现 — 自动从 HMCL 依赖缓存加载 JavaFX

安装与使用

前提条件

• Java 17+
• HMCL 3.15.x 或 3.16.x
• Fabric Loader 0.19.3

构建

cd FLFHMCL
./gradlew build

输出在 build/libs/FLFHMCL-[version].jar。

构建同时会自动执行 collectLibraries 任务，将运行时依赖复制到 build/libraries/。

运行

java -javaagent:FLFHMCL-0.3.0-alpha.jar -jar HMCL-3.16.SNAPSHOT.jar
# 或 HMCL 3.15.x
java -javaagent:FLFHMCL-0.3.0-alpha.jar -jar HMCL-3.15.2.jar

调试模式

java -Dflfhmcl.debug=true -javaagent:FLFHMCL-0.3.0-alpha.jar -jar HMCL-3.16.SNAPSHOT.jar

Mods 目录结构

test/
├── FLFHMCL-0.3.0-alpha.jar    # FLFHMCL Agent
├── HMCL-3.16.SNAPSHOT.jar      # HMCL Launcher
├── libraries/                   # 运行时依赖
│   ├── fabric-loader-0.19.3.jar
│   ├── sponge-mixin-*.jar
│   ├── log4j-api-2.24.3.jar
│   ├── log4j-core-2.24.3.jar
│   ├── log4j-slf4j2-impl-2.24.3.jar
│   └── ...
└── mods/                        # Fabric mods
    ├── flf-title-mod.jar
    ├── mod-flf-hibernet-sso-1.0.0.jar
    └── mod-flf-sso-bridge-1.0.0.jar

项目结构

FLFHMCL/
├── build.gradle.kts                  # Gradle 构建配置
├── settings.gradle.kts               # Gradle 设置
├── README.md                         # 本文件
└── src/main/
    ├── java/com/hibernet/flfhmcl/
    │   ├── agent/
    │   │   └── FLFAgent.java         # Java Agent 入口（premain + ClassFileTransformer）
    │   ├── game/
    │   │   ├── HMCLGameProvider.java  # GameProvider 实现（定位 HMCL、注册内置模组）
    │   │   ├── HMCLGameTransformer.java  # 空 GameTransformer
    │   │   └── HMCLVersionDetector.java # HMCL 版本检测
    │   ├── log/
    │   │   └── Log4jLogHandler.java   # Fabric Log → Log4j 桥接
    │   └── util/
    │       ├── FLFLogger.java         # 传统日志工具（Agent 阶段使用）
    │       └── PlatformUtils.java     # 平台检测
    ├── resources/
    │   ├── log4j2.xml                 # Log4j 配置
    │   └── META-INF/services/
    │       └── net.fabricmc.loader.impl.game.GameProvider  # ServiceLoader 注册
    └── mod-flf-*/                     # 示例和附属 Fabric mod
        ├── mod-flf-title/             # 标题栏修改 mod
        ├── mod-flf-test/              # 测试 mod
        ├── mod-flf-ui-api/            # UI API 注册中心
        └── mod-flf-hibernet-sso/      # HiBerNET SSO 认证 mod

工作原理

启动流程

1. JVM 调用 FLFAgent.premain()（-javaagent: 参数触发）
2. Agent 将 libraries/ 下所有 jar 加载到系统类加载器
3. Agent 注册 ClassFileTransformer 拦截 HMCL 入口类
4. 当 HMCL 入口类被加载时，Agent 通过反射启动 KnotClient.main()
5. Fabric Loader 加载 HMCLGameProvider（通过 ServiceLoader 发现）
6. HMCLGameProvider.locateGame() 在 classpath 中定位 HMCL jar
7. Fabric Loader 初始化 Mixin、加载 mod、调用 preLaunch 入口点
8. HMCLGameProvider.launch() 通过 KnotClassLoader 启动 HMCL

为 HMCL 编写 Fabric Mod

FLFHMCL 启动后，Fabric mod 放在 mods/ 目录下即可被加载。示例 mod：

// 用 Mixin 注入 HMCL 的 UI 类
@Mixin(org.jackhuang.hmcl.ui.main.RootPage.class)
public class MixinRootPage {
    @Inject(method = "start", at = @At("HEAD"))
    private void onStart(CallbackInfo ci) {
        System.out.println("HMCL 被 Fabric mod 拦截！");
    }
}

相关项目

• HBNS/mod-flf-sso-bridge — SSO 桥接模组（将 SSO 信息传递到 Minecraft 游戏）
• HBNS/mod-flf-hibernet-sso — SSO 认证模组（OIDC Authorization Code + PKCE）
• HBNS/mod-flf-modern-syn — ModernSyn 版本管理模组

许可证

FLFHMCL is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 2.1 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see https://www.gnu.org/licenses/.