Skip to main content
This guide walks you through the process of building LiquidBounce from source code.

​
Prerequisites

Before you begin, ensure you have the following installed:

​
Required Software

  • Java Development Kit (JDK) 21
    • LiquidBounce requires JDK 21 or higher
    • Download from Adoptium or Oracle
  • Gradle
    • The project uses Gradle for build automation
    • Check installation guide at gradle.org/install
    • Alternatively, use the included Gradle wrapper (./gradlew)
  • Node.js
    • Required for building the theme system
    • Download from nodejs.org
    • Latest LTS or stable release recommended
  • Git
    • For cloning the repository with submodules
    • Download from git-scm.com

​
Cloning the Repository

Clone the repository with all submodules: 
git clone --recurse-submodules https://github.com/CCBlueX/LiquidBounce
The --recurse-submodules flag is important as LiquidBounce uses git submodules for certain components.
Navigate to the project directory: 
cd LiquidBounce

​
Setting Up the Workspace

​
Generate Sources (Optional)

For a better development experience, generate decompiled Minecraft sources: 
./gradlew genSources
This task decompiles Minecraft code and makes it available for reference in your IDE. While optional, it’s highly recommended for development.

​
Open in IDE

Open the project folder as a Gradle project in your preferred IDE:
  • IntelliJ IDEA: File → Open → Select the LiquidBounce folder
  • Eclipse: File → Import → Gradle → Existing Gradle Project
  • VS Code: Open folder and install Gradle extensions
IntelliJ IDEA is the recommended IDE for LiquidBounce development. The project includes .idea configuration for automatic setup.

​
Building the Project

​
Standard Build

Build the mod JAR file: 
./gradlew build
The built JAR file will be located in build/libs/.

​
Build Tasks

LiquidBounce uses several Gradle tasks for building:
TaskDescription
./gradlew buildComplete build including tests and theme
./gradlew jarBuild the mod JAR only
./gradlew sourcesJarGenerate sources JAR
./gradlew assembleAssemble all outputs without running tests

​
Theme Building

The theme is built automatically as part of the build process: 
# Install theme dependencies
./gradlew npmInstallTheme

# Build the theme
./gradlew buildTheme

# Bundle theme into resources
./gradlew bundleTheme
These tasks run automatically during processResources but can be executed individually if needed.

​
Running the Client

​
Development Run

Run the client directly from Gradle: 
./gradlew runClient
This launches Minecraft with LiquidBounce installed in a development environment.

​
Debug Mode

For debugging in your IDE:
  1. Open Run Configurations
  2. Add a new Gradle configuration
  3. Set task to runClient
  4. Enable debug mode

​
Build Configuration

​
Project Properties

The build is configured via gradle.properties: 
mod_version=0.36.1
maven_group=net.ccbluex
archives_base_name=liquidbounce

​
Version Information

Version dependencies are managed in gradle/libs.versions.toml:
  • Minecraft: 1.21.11
  • Fabric Loader: 0.18.4+
  • Fabric API: 0.140.0+
  • Kotlin: 2.3.10
  • JDK: 21

​
Gradle Performance

The project is optimized for faster builds: 
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configureondemand=true
org.gradle.jvmargs=-Xms1024m -Xmx4096m -XX:+UseZGC -XX:+ZGenerational
The build uses ZGC (Z Garbage Collector) from JDK 21 for better performance. Ensure you’re using JDK 21 or higher.

​
Common Build Tasks

​
Clean Build

Remove all build artifacts: 
./gradlew clean

​
Rebuild Everything

Clean and build from scratch: 
./gradlew clean build

​
Run Tests

Execute all tests: 
./gradlew test

​
Code Quality Checks

Run Detekt for Kotlin code analysis: 
./gradlew detekt

​
Verify Translations

Check i18n JSON key consistency: 
./gradlew verifyI18nJsonKeys

​
Troubleshooting

​
Build Fails Due to Memory

Increase Gradle memory in gradle.properties: 
org.gradle.jvmargs=-Xms2048m -Xmx6144m

​
Theme Build Issues

Ensure Node.js is installed and accessible: 
node --version
npm --version
Manually install theme dependencies: 
cd src-theme
npm install
npm run build
cd ..

​
Gradle Wrapper Issues

If ./gradlew fails, ensure it’s executable: 
chmod +x gradlew
Or use the system Gradle: 
gradle build

​
Submodules Not Loaded

If you forgot --recurse-submodules when cloning: 
git submodule update --init --recursive

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us