Skip to main content

​
Prerequisites

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

Gradle

Build automation tool required for compiling LiquidBounce

Node.js

JavaScript runtime needed for the theme system

Git

Version control system for cloning the repository

JDK 21+

Java Development Kit version 21 or higher
LiquidBounce uses Gradle and requires Node.js for the custom theme located in src-theme/. The project is configured to use JDK 21 with ZGC (Z Garbage Collector) for optimal performance.

​
Verify Gradle installation

Check if Gradle is properly installed by running: 
gradle --version
If Gradle is not installed, visit gradle.org/install for installation instructions.

​
Verify Node.js installation

Check if Node.js is properly installed by running: 
node --version
npm --version
If Node.js is not installed, visit nodejs.org to download and install it.

​
Setting up a workspace

Follow these steps to set up your LiquidBounce development workspace:
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 important as it ensures all required submodules are cloned along with the main repository.
2

Navigate to the directory

Change into the LiquidBounce directory:
cd LiquidBounce
3

Generate sources (optional)

Generate source files for a better development experience:
./gradlew genSources
This step is optional but recommended as it generates decompiled Minecraft sources for easier development and debugging.
On Windows, use gradlew.bat instead of ./gradlew:
gradlew.bat genSources
4

Open in your IDE

Open the folder as a Gradle project in your preferred IDE:
  • IntelliJ IDEA: File > Open and select the LiquidBounce folder
  • Eclipse: File > Import > Gradle > Existing Gradle Project
  • VS Code: Open the folder and ensure the Gradle extension is installed
The IDE will automatically import the Gradle project and download dependencies.
5

Run the client

Launch the Minecraft client with LiquidBounce:
./gradlew runClient
This command will:
  1. Build the theme from src-theme/ using Node.js and npm
  2. Compile the Kotlin source code
  3. Process resources and apply Fabric mixins
  4. Launch Minecraft with LiquidBounce injected

​
Project structure

Understanding the project structure will help you navigate the codebase: 
LiquidBounce/
├── src/
│   ├── main/
│   │   ├── kotlin/
│   │   │   └── net/ccbluex/liquidbounce/
│   │   │       ├── features/
│   │   │       │   └── module/
│   │   │       │       ├── modules/
│   │   │       │       │   ├── combat/      # Combat modules
│   │   │       │       │   ├── movement/    # Movement modules
│   │   │       │       │   ├── player/      # Player modules
│   │   │       │       │   ├── world/       # World modules
│   │   │       │       │   ├── render/      # Render modules
│   │   │       │       │   ├── misc/        # Misc modules
│   │   │       │       │   ├── exploit/     # Exploit modules
│   │   │       │       │   └── fun/         # Fun modules
│   │   │       │       ├── ModuleCategories.kt
│   │   │       │       └── ModuleCategory.kt
│   │   │       └── ...
│   │   └── resources/
│   └── test/
├── src-theme/              # Custom UI theme (Node.js/npm)
├── build.gradle.kts        # Gradle build configuration
├── gradle.properties       # Project properties
└── settings.gradle.kts     # Gradle settings

​
Build configuration

LiquidBounce is configured in build.gradle.kts with the following key settings:
  • Fabric Loom: Gradle plugin for Fabric mod development
  • Kotlin JVM: Kotlin support with explicit backing fields
  • Access Widener: Located at src/main/resources/liquidbounce.accesswidener
  • Custom Theme: Built from src-theme/ and bundled into the JAR

​
Key Gradle tasks

# Run the Minecraft client
./gradlew runClient

# Build the project (creates JAR in build/libs/)
./gradlew build

# Generate sources for development
./gradlew genSources

# Run tests
./gradlew test

# Build the theme separately
./gradlew buildTheme

​
Dependencies

LiquidBounce includes several important dependencies:
  • Fabric API: Core modding framework
  • Fabric Kotlin: Kotlin language support for Fabric
  • ViaFabricPlus: Multi-version protocol support
  • ModMenu: In-game mod configuration menu
  • GraalVM Polyglot: ScriptAPI support for custom scripts
  • MCEF: Chromium Embedded Framework for web rendering
  • OkHttp: HTTP client library
  • Discord IPC: Discord Rich Presence integration
Optional recommended mods for better performance include Sodium, Lithium, ImmediatelyFast, and Iris. These are automatically included in the development environment.

​
Troubleshooting

Ensure Node.js is installed and available in your PATH. The theme build process (src-theme/) requires npm to install dependencies and build the UI.
# Verify Node.js installation
node --version
npm --version
If you see OutOfMemory errors, increase the JVM heap size in gradle.properties:
org.gradle.jvmargs=-Xms2048m -Xmx6144m -XX:+UseZGC -XX:+ZGenerational
Ensure the access widener is properly configured in build.gradle.kts:
loom {
    accessWidenerPath = file("src/main/resources/liquidbounce.accesswidener")
}
Clean and rebuild the project:
./gradlew clean build
If you forgot to use --recurse-submodules when cloning, initialize them manually:
git submodule update --init --recursive

​
Next steps

Now that you have LiquidBounce set up, head over to the quick start guide to learn how to run the client and use your first modules.

Quick start guide

Learn how to launch the client, access the ClickGUI, and enable your first modules

Build docs developers (and LLMs) love

Get started for freeTalk to us