Skip to main content
We appreciate contributions to LiquidBounce! This guide will help you understand how to contribute effectively.

​
Getting Started

​
Before You Contribute

  1. Check existing issues - Look for existing issues or feature requests
  2. Discuss major changes - Open an issue first for significant changes
  3. Read the coding standards - Follow the project’s coding conventions
  4. Test your changes - Ensure everything works as expected

​
Ways to Contribute

  • Report bugs and issues
  • Suggest new features
  • Submit pull requests
  • Improve documentation
  • Help with translations

​
Reporting Issues

If you notice bugs or missing features, open an issue on GitHub: github.com/CCBlueX/LiquidBounce/issues

​
Bug Reports

When reporting bugs, include:
  • LiquidBounce version
  • Minecraft version
  • Steps to reproduce
  • Expected vs actual behavior
  • Crash logs or screenshots
  • List of other mods (if applicable)

​
Feature Requests

When suggesting features, describe:
  • The problem it solves
  • How it should work
  • Why it would be useful
  • Potential implementation approaches

​
Coding Standards

LiquidBounce enforces strict coding standards to maintain code quality and consistency.

​
Language Preferences

We prefer Kotlin for new code. In the long term, we aim to largely migrate LiquidBounce to Kotlin.
Use Java only when:
  • The framework is designed for Java (e.g., mixins)
  • Java achieves better readability or performance (explain in PR)
For Java code:
  • Use JSpecify annotations for nullability
  • Avoid legacy features from older Java versions
  • Follow modern Java best practices

​
Kotlin Conventions

Follow Kotlin’s official conventions:

​
Java Conventions

Follow Java’s official standards:

​
File Standards

​
File Headers

All code files (.kt and .java) must include this header: 
/*
 * This file is part of LiquidBounce (https://github.com/CCBlueX/LiquidBounce)
 *
 * Copyright (c) 2015 - 2026 CCBlueX
 *
 * LiquidBounce is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * LiquidBounce is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with LiquidBounce. If not, see <https://www.gnu.org/licenses/>.
 */
If you’re using IntelliJ IDEA, this header will be automatically added when you create a new file.

​
Documentation Tags

Allowed tags: 
// You can use @author tags, but limit usage
@author YourName

// For bypasses, use these tags:
@anticheat AntiCheatName
@anticheatVersion 1.0.0
@testedOn test.server.com
@note Special note about this bypass
Do not use other tags beyond those listed above.

​
Package Naming

Follow this naming convention: 
country.company-name.product-name
Example: 
net.ccbluex.liquidbounce

​
External Packages

If your code is self-contained and not designed exclusively for LiquidBounce, you may use a separate package (subject to approval): 
net.yourname  // instead of net.ccbluex

​
Code Quality Tools

​
Detekt (Kotlin)

Run Detekt to check for Kotlin code style violations: 
./gradlew detekt
Fix issues before submitting your PR.

​
Creating a Baseline

To create a new Detekt baseline: 
./gradlew detektProjectBaseline

​
JSpecify (Java)

All new Java code must use JSpecify annotations for nullability: 
import org.jspecify.annotations.Nullable;
import org.jspecify.annotations.NonNull;

public class Example {
    public @Nullable String getValue() {
        return null;
    }
    
    public void processValue(@NonNull String value) {
        // value is guaranteed non-null
    }
}

​
Submitting Pull Requests

​
PR Workflow

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Create a feature branch 
    git checkout -b feature/my-feature
  4. Make your changes following coding standards
  5. Test thoroughly - ensure everything works
  6. Run code quality checks 
    ./gradlew detekt
./gradlew test
  7. Commit your changes with clear messages
  8. Push to your fork 
    git push origin feature/my-feature
  9. Open a pull request on GitHub

​
PR Best Practices

  • Keep PRs focused on a single feature/fix
  • Write clear commit messages
  • Update documentation if needed
  • Add tests for new functionality
  • Respond to review feedback promptly
  • Keep your branch up to date with main

​
Commit Messages

Write descriptive commit messages: 
Add velocity prediction to killaura

Implements velocity-based target prediction for improved accuracy
when targeting moving entities.
Format:
  • First line: Brief summary (50 chars or less)
  • Blank line
  • Detailed explanation (optional)

​
Testing Your Changes

​
Running Tests

Execute the test suite: 
./gradlew test

​
Manual Testing

Test your changes in-game: 
./gradlew runClient

​
Verification Checks

Before submitting:
  • Code follows coding standards
  • Detekt passes without new violations
  • All tests pass
  • Feature works as intended in-game
  • No new compiler warnings
  • Documentation updated (if applicable)
  • i18n translations added (if applicable)

​
License Agreement

By contributing to LiquidBounce, you agree that your contributions will be licensed under the GNU General Public License v3.0.

​
Key Points

  • Your contributions become part of the GPL-licensed codebase
  • You must disclose the source code of any modifications
  • Derivative works must also be licensed under GPL
  • You cannot use code from this project in closed-source applications
See LICENSE for full details.

​
Community

​
Get Help

If you need help with contributing:

​
Contributors

See all contributors: github.com/CCBlueX/LiquidBounce/graphs/contributors

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us