Development Guide - LiquidBounce

Complete guide for setting up a LiquidBounce development workspace, building from source, and contributing to the project.

Prerequisites

Before you begin, ensure you have the following installed:

Java Development Kit

JDK 17 or higher

Git

For cloning the repository

Node.js

Required for theme development

Gradle is included via the wrapper, so you don’t need to install it separately.

Initial Setup

Clone Repository

Clone the repository with submodules:

git clone --recurse-submodules https://github.com/CCBlueX/LiquidBounce

The --recurse-submodules flag is important! The theme is in a submodule.

Navigate to Directory

cd LiquidBounce

Generate Sources (Optional)

Generate Minecraft sources for better IDE experience:

./gradlew genSources

This step is optional but highly recommended for code navigation and debugging.

Open in IDE

Open the folder as a Gradle project in your preferred IDE (IntelliJ IDEA recommended).

Running the Client

Development Mode

Run the client directly from your IDE or terminal:

./gradlew runClient

Run Configurations

IntelliJ IDEA
VS Code
Eclipse

Gradle should auto-create run configurations
Look for “Minecraft Client” in the run configurations dropdown
Click the play button to launch

Install the Java Extension Pack
Use the Gradle tasks view
Navigate to fabric > runClient

Import as Gradle project
Run ./gradlew eclipse to generate Eclipse configs
Use Gradle Tasks view to run runClient

Building from Source

Production Build

Build the final JAR file:

./gradlew build

The built JAR will be located at:

build/libs/liquidbounce-<version>.jar

Build Variants

./gradlew clean build

Gradle Tasks

Common Tasks

runClient

Runs the Minecraft client with LiquidBounce in development mode.

./gradlew runClient

build

Compiles the project and creates the JAR file.

./gradlew build

clean

Removes all build artifacts.

./gradlew clean

genSources

Generates decompiled Minecraft source code for reference.

./gradlew genSources

test

Runs the test suite.

./gradlew test

Theme Tasks

The theme is built using Node.js:

cd src-theme
npm install
npm run build

Mixin Development

LiquidBounce uses Mixins to inject code into Minecraft classes.

What are Mixins?

Mixins allow you to modify Minecraft’s code at runtime without directly editing Mojang’s copyrighted source code.

Creating a Mixin

Create Mixin Class

Create a new Kotlin class in the mixins package:

package net.ccbluex.liquidbounce.injection.mixins.minecraft.client

import net.minecraft.client.Minecraft
import org.spongepowered.asm.mixin.Mixin
import org.spongepowered.asm.mixin.injection.At
import org.spongepowered.asm.mixin.injection.Inject
import org.spongepowered.asm.mixin.injection.callback.CallbackInfo

@Mixin(Minecraft::class)
class MixinMinecraft {
    
    @Inject(method = ["tick"], at = [At("HEAD")])
    private fun onTick(ci: CallbackInfo) {
        // Your code here
    }
}

Add your mixin to liquidbounce.mixins.json:

{
  "mixins": [
    "minecraft.client.MixinMinecraft"
  ]
}

Test Changes

Run the client to test your mixin:

./gradlew runClient

Mixin Injection Points

@Inject

annotation

Inject code at a specific point in a method

@Inject(method = ["methodName"], at = [At("HEAD")])

@ModifyVariable

annotation

Modify a local variable’s value

@ModifyVariable(method = ["methodName"], at = [At("STORE")])

@Redirect

annotation

Redirect a method call to your own implementation

@Redirect(method = ["methodName"], at = [At(value = "INVOKE", target = "...")])

@ModifyConstant

annotation

Modify constant values

@ModifyConstant(method = ["methodName"], constant = [Constant(intValue = 20)])

Common Injection Patterns

Method Entry
Method Exit
Cancellable
Method Call

@Inject(method = ["tick"], at = [At("HEAD")])
private fun onTickStart(ci: CallbackInfo) {
    // Runs at the start of the tick method
}

@Inject(method = ["tick"], at = [At("RETURN")])
private fun onTickEnd(ci: CallbackInfo) {
    // Runs before the method returns
}

@Inject(method = ["tick"], at = [At("HEAD")], cancellable = true)
private fun onTick(ci: CallbackInfo) {
    if (shouldCancel()) {
        ci.cancel()
    }
}

@Inject(
    method = ["render"],
    at = [At(
        value = "INVOKE",
        target = "Lnet/minecraft/client/renderer/GameRenderer;render(F)V"
    )]
)

Mixin Best Practices

Use Descriptive Names

Name mixins after the class they modify: MixinMinecraft

Minimize Injections

Only inject where absolutely necessary

Document Purpose

Add comments explaining why the mixin exists

Test Thoroughly

Test mixins with different game states

Mixins run at very low level. Bugs in mixins can crash Minecraft or cause unexpected behavior.

Contributing

We welcome contributions to LiquidBounce!

Contribution Workflow

Fork the Repository

Create a fork of LiquidBounce on GitHub.

Create a Branch

git checkout -b feature/your-feature-name

Make Changes

Implement your feature or fix.

Test Thoroughly

Ensure your changes work and don’t break existing functionality.

Commit Changes

git add .
git commit -m "Add: Your feature description"

Push to Fork

git push origin feature/your-feature-name

Create Pull Request

Open a pull request on the main repository with a clear description.

Code Style Guidelines

Kotlin Conventions

Follow Kotlin coding conventions
Use 4 spaces for indentation
Maximum line length: 120 characters
Use meaningful variable names

Comments

Document public APIs with KDoc
Explain complex logic with inline comments
Keep comments up-to-date with code changes

File Organization

Place files in appropriate packages
Keep related code together
Avoid circular dependencies

Naming

Classes: PascalCase (e.g., ModuleKillAura)
Functions: camelCase (e.g., attackEntity)
Constants: SCREAMING_SNAKE_CASE (e.g., MAX_DISTANCE)

Pull Request Guidelines

One feature or fix per PR

Clear and descriptive title

Detailed description of changes

Screenshots/videos for UI changes

All tests passing

No merge conflicts

License Compliance

LiquidBounce is licensed under GPL v3.0. Any code you contribute must be compatible with this license.

GPL v3.0 Requirements

Use GPL-Compatible Code

Only use code that is GPL-compatible or public domain.

Disclose Source

If you distribute LiquidBounce (or forks), you must provide source code.

License Derivatives

Any modifications must also be licensed under GPL v3.0.

Preserve Notices

Keep all license headers and copyright notices intact.

For full license details, see the GPL v3.0 license.

Project Structure

LiquidBounce/
├── src/
│   └── main/
│       ├── kotlin/
│       │   └── net/ccbluex/liquidbounce/
│       │       ├── config/          # Configuration system
│       │       ├── deeplearn/       # AI/ML features
│       │       ├── event/           # Event system
│       │       ├── features/        # Core features
│       │       │   ├── module/      # Modules (hacks)
│       │       │   └── spoofer/     # Spoofers
│       │       ├── integration/     # Browser & integrations
│       │       └── utils/           # Utility classes
│       ├── resources/
│       │   └── liquidbounce.mixins.json
│       └── java/                    # Java sources (mixins)
├── src-theme/                       # Web-based theme (submodule)
├── build.gradle.kts                 # Build configuration
└── gradle/                          # Gradle wrapper

Debugging

IntelliJ IDEA Debugger

Set Breakpoints

Click in the gutter next to line numbers to set breakpoints.

Debug Mode

Click the debug icon (bug) instead of run.

Inspect Variables

Hover over variables or use the Variables panel.

Step Through Code

Use F8 (step over), F7 (step into), Shift+F8 (step out).

Remote Debugging

For debugging in production:

./gradlew runClient --debug-jvm

Then attach a remote debugger on port 5005.

Troubleshooting

Gradle build fails

Try ./gradlew clean build --refresh-dependencies
Check you’re using JDK 17 or higher
Ensure internet connection for dependency downloads

Client won't start

Check the run configuration is correct
Look for errors in the IDE console
Try regenerating sources: ./gradlew genSources

Mixin not applying

Verify the mixin is registered in liquidbounce.mixins.json
Check the target class/method names are correct
Look for mixin errors in the log

Theme not building

Ensure Node.js is installed
Run npm install in src-theme/
Check for errors in theme build output

Resources

Mixin Documentation

Official Mixin framework documentation

Fabric Wiki

Fabric modding documentation

Kotlin Docs

Official Kotlin documentation

GitHub Issues

Report bugs and request features

Community

Discord

Join our Discord server

Forum

Community forums

YouTube

Video tutorials and updates

For quick questions, join our Discord server. For bug reports and feature requests, use GitHub Issues.

Getting Started

Core Concepts

Modules

Features

Scripting

Advanced

​Prerequisites

Java Development Kit

Git

Node.js

​Initial Setup

​Running the Client

​Development Mode

​Run Configurations

​Building from Source

​Production Build

​Build Variants

​Gradle Tasks

​Common Tasks

​Theme Tasks

​Mixin Development

​What are Mixins?

​Creating a Mixin

​Mixin Injection Points

​Common Injection Patterns

​Mixin Best Practices

Use Descriptive Names

Minimize Injections

Document Purpose

Test Thoroughly

​Contributing

​Contribution Workflow

​Code Style Guidelines

​Pull Request Guidelines

​License Compliance

​GPL v3.0 Requirements

​Project Structure

​Debugging

​IntelliJ IDEA Debugger

​Remote Debugging

​Troubleshooting

​Resources

Mixin Documentation

Fabric Wiki

Kotlin Docs

GitHub Issues

​Community

Discord

Forum

YouTube

Build docs developers (and LLMs) love

Prerequisites

Initial Setup

Running the Client

Development Mode

Run Configurations

Building from Source

Production Build

Build Variants

Gradle Tasks

Common Tasks

Theme Tasks

Mixin Development

What are Mixins?

Creating a Mixin

Mixin Injection Points

Common Injection Patterns

Mixin Best Practices

Contributing

Contribution Workflow

Code Style Guidelines

Pull Request Guidelines

License Compliance

GPL v3.0 Requirements

Project Structure

Debugging

IntelliJ IDEA Debugger

Remote Debugging

Troubleshooting

Resources

Community