LiquidBounce 项目开发与使用全指南

一、剖析项目架构

1.1 核心源码组织

项目采用 Kotlin 与 Java 混合开发架构，核心功能模块集中在 src/main/kotlin/net/ccbluex/liquidbounce 目录。其中：

• features/module：包含 643 个功能模块（如移动、战斗、渲染等），构成客户端核心能力
• injection/mixins：153 个注入类，通过 Fabric API 实现对 Minecraft 底层的修改
• utils：工具类集合，涵盖数学计算、实体处理、渲染辅助等基础功能

1.2 资源与主题系统

资源文件采用分离式管理：

• src-theme/public：存放 UI 主题资源，包括背景图片、字体文件和组件配置
• src/main/resources：包含游戏内资源，如纹理、音效和默认配置
• zip_include：存储分发所需的许可文件和外部链接信息

二、快速启动流程

2.1 环境准备

1. 安装 JDK 17+ 和 Git（建议使用 Git 2.30+ 版本）
2. 克隆项目：git clone --recurse-submodules https://gitcode.com/gh_mirrors/li/LiquidBounce
   ⚠️ 注意：--recurse-submodules 参数用于同步子项目依赖，不可省略
3. 进入项目目录：cd LiquidBounce

💡 技巧：国内用户可配置 Git 代理加速克隆过程：git config --global http.proxy http://127.0.0.1:7890

2.2 构建执行

1. 生成源代码：./gradlew genSources（此过程约需3-5分钟，首次执行会下载依赖）
2. 启动客户端：./gradlew runClient
   • Windows 系统使用：gradlew.bat runClient
   • 如需调试模式：./gradlew runClient --debug-jvm

2.3 验证安装

启动成功后应看到：

• Minecraft 启动界面，顶部显示 "BOUNCE" 标识
• 主菜单包含 "Singleplayer"、"Multiplayer" 等标准选项
• 按 Right Shift 键可打开 LiquidBounce 功能菜单

三、个性化配置指南

3.1 基础配置

配置文件路径：.minecraft/config/LiquidBounce/

文件名	作用	常用参数	修改建议
hudlayout.json	界面布局配置	x/y坐标、scale缩放	建议先导出默认配置备份
modules.json	功能模块状态	enabled: true/false	按 [/] 键快速切换模块

💡 技巧：配置文件支持热重载，修改后无需重启客户端

3.2 进阶配置

主题自定义：

1. 编辑 src-theme/public/components 下的 JSON 文件调整 UI 组件
2. 替换 src-theme/public/backgrounds/background.png 更改背景（建议保持 2560x1440 分辨率）
3. 通过 src-theme/src/theme/theme_config.ts 修改主题配色方案

3.3 故障排除

常见配置问题解决：

• HUD 元素丢失：删除 hudlayout.json 后重启客户端恢复默认布局
• 模块无法启用：检查 modules.json 中是否存在语法错误（可使用在线 JSON 验证工具）
• 主题不生效：执行 ./gradlew buildTheme 重新构建主题资源

四、常见问题速查表

问题现象	可能原因	解决方案
启动时报错 "NoSuchMethodError"	Gradle 依赖冲突	删除 ~/.gradle/caches 后重新构建
游戏崩溃于 "Render thread"	显卡驱动不兼容	更新显卡驱动或添加 -Dliquidbounce.legacyRender=true 启动参数
模块列表为空	资源加载失败	执行 ./gradlew clean genSources 重建源码
主题修改不生效	缓存未更新	运行 ./gradlew clean buildTheme 清理并重建主题
无法连接服务器	代理配置错误	检查 .minecraft/config/LiquidBounce/proxy.properties

五、开发扩展建议

5.1 模块开发

1. 在 features/module 目录下创建新的 Kotlin 类
2. 继承 Module 基类并添加 @ModuleInfo 注解
3. 实现 onEnable()/onDisable() 方法处理模块生命周期

5.2 构建优化

• 使用 ./gradlew build --parallel 启用并行构建（缩短约 30% 构建时间）
• 添加 -x test 参数跳过测试加速构建：./gradlew build -x test

⚠️ 注意：开发环境需要配置 Java 17+ 和 Kotlin 1.8+，否则可能出现编译错误