Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Gradle

Build automation tool for compiling LiquidBounce

Node.js

Required for building the client’s custom theme system

Git

Version control for cloning the repository with submodules

JDK 21+

Java Development Kit for running and building the project

​
Check Gradle Installation

Gradle is essential for building LiquidBounce. Verify your installation: 
gradle --version
If Gradle is not installed, follow the official Gradle installation guide.
LiquidBounce uses Gradle wrapper (gradlew), so you can use the included wrapper script even without a system-wide Gradle installation.

​
Check Node.js Installation

Node.js is required for building the theme system. Verify your installation: 
node --version
npm --version
If Node.js is not installed, download it from nodejs.org.

​
Installation Steps

1

Clone the Repository

Clone the LiquidBounce repository with all submodules:
git clone --recurse-submodules https://github.com/CCBlueX/LiquidBounce
The --recurse-submodules flag is required to properly clone all dependencies. Without it, the build will fail.
2

Navigate to the Directory

Change into the LiquidBounce directory:
cd LiquidBounce
3

Generate Sources (Optional)

Generate decompiled Minecraft sources for better IDE support:
./gradlew genSources
This step is optional but highly recommended for development. It provides better code completion and allows you to browse Minecraft’s source code in your IDE.
On Windows, use:
gradlew.bat genSources
4

Open in Your IDE

Open the project folder as a Gradle project in your preferred IDE:IntelliJ IDEA (Recommended):
  • File → Open → Select the LiquidBounce folder
  • IntelliJ will automatically detect it as a Gradle project
  • Wait for Gradle to sync and index the project
Eclipse:
  • File → Import → Gradle → Existing Gradle Project
  • Select the LiquidBounce folder
VS Code:
  • Open the folder in VS Code
  • Install the “Gradle for Java” extension
  • Let the extension configure the project
5

Run the Client

Launch LiquidBounce using Gradle:
./gradlew runClient
On Windows:
gradlew.bat runClient
The first run will take some time as Gradle downloads all dependencies and builds the theme system.

​
Build Configuration

LiquidBounce’s build is configured through several files:

​
build.gradle.kts

The main build script written in Kotlin DSL. Key configurations:
  • Minecraft Version: Defined in gradle/libs.versions.toml
  • Fabric Loader: Mod loading framework
  • Fabric API: Core API for Fabric mods
  • Fabric Kotlin: Kotlin language support for Fabric

​
gradle.properties

Project properties and metadata: 
mod_version=0.36.1
maven_group=net.ccbluex
archives_base_name=liquidbounce

​
Theme System

LiquidBounce includes a custom theme built with Node.js:

​
Theme Build Process

The theme is automatically built during compilation:
  1. npmInstallTheme: Installs Node.js dependencies
  2. buildTheme: Builds the theme using Rollup
  3. bundleTheme: Packages the theme into a ZIP file
The built theme is located at: 
src-theme/resources/assets/liquidbounce/themes/liquidbounce.zip
The theme build is automatically triggered by the processResources task, so you don’t need to build it manually.

​
Building the JAR

To build a distributable JAR file: 
./gradlew build
The built JAR will be located in: 
build/libs/liquidbounce-0.36.1.jar

./gradlew build

​
First Launch

1

Launch Minecraft

After running ./gradlew runClient, Minecraft will start with LiquidBounce installed.
2

Verify Installation

Look for the LiquidBounce logo and branding in the main menu. You should see:
  • Modified main menu (if theme is loaded)
  • LiquidBounce version in the corner
  • Access to the ClickGUI (press Right Shift)
3

Check the Console

Monitor the console output for any errors. A successful launch shows:
[LiquidBounce] Loading LiquidBounce...
[LiquidBounce] Loaded X modules
[LiquidBounce] Loaded X commands

​
Troubleshooting

You forgot to clone with --recurse-submodules. Fix it by running:
git submodule update --init --recursive
Ensure Node.js and npm are properly installed:
node --version
npm --version
Then clean and rebuild:
./gradlew clean build
Increase Gradle’s memory allocation in gradle.properties:
org.gradle.jvmargs=-Xms1024m -Xmx4096m -XX:+UseZGC -XX:+ZGenerational
Make sure the Kotlin plugin is installed in your IDE. For IntelliJ IDEA:
  • File → Settings → Plugins
  • Search for “Kotlin” and install it
  • Restart the IDE

​
Development Tools

​
Code Quality

LiquidBounce uses Detekt for code quality: 
./gradlew detekt

​
Testing

Run the test suite: 
./gradlew test

​
Documentation

Generate Dokka documentation: 
./gradlew dokkaHtml

​
Next Steps

Now that you have LiquidBounce installed, learn how to use it:

Quick Start Guide

Learn the basics and enable your first module

Contributing

Contribute to LiquidBounce development

Build docs developers (and LLMs) love

Get started for freeTalk to us