Skip to main content
This guide provides an overview of LiquidBounce’s project architecture and codebase organization.

Technology Stack

Core Technologies

  • Language: Kotlin (primary) + Java
  • Minecraft Version: 1.21.11
  • Mod Loader: Fabric
  • Build Tool: Gradle 8.x
  • UI Framework: Svelte (theme system)
  • JDK Version: 21

Key Dependencies

DependencyVersionPurpose
Fabric Loader0.18.4+Mod loading framework
Fabric API0.140.0+Minecraft API extensions
Fabric Kotlin1.13.9+Kotlin language support
Kotlin2.3.10Primary language
Node.jsLatest LTSTheme building

Project Structure

Root Directory

LiquidBounce/
├── src/                    # Main source code
├── src-theme/             # Theme system (Svelte)
├── buildSrc/              # Build configuration
├── config/                # Configuration files
├── gradle/                # Gradle wrapper and dependencies
├── zip_include/           # Additional distribution files
├── .github/               # GitHub workflows and templates
├── build.gradle.kts       # Main build script
├── settings.gradle.kts    # Gradle settings
├── gradle.properties      # Project properties
└── README.md              # Project documentation

Source Code Structure

src/
├── main/
│   ├── kotlin/
│   │   └── net/ccbluex/liquidbounce/
│   │       ├── LiquidBounce.kt       # Main entry point
│   │       ├── additions/            # Additional features
│   │       ├── annotations/          # Custom annotations
│   │       ├── api/                  # Public APIs
│   │       ├── config/               # Configuration system
│   │       ├── deeplearn/            # Machine learning features
│   │       ├── event/                # Event system
│   │       ├── features/             # Core features (modules, commands)
│   │       ├── integration/          # External integrations
│   │       ├── lang/                 # Language/i18n system
│   │       ├── render/               # Rendering utilities
│   │       ├── script/               # Scripting API
│   │       └── utils/                # Utility classes
│   ├── java/
│   │   └── net/                      # Java code (mainly mixins)
│   └── resources/
│       ├── assets/                   # Asset files
│       ├── resources/liquidbounce/
│       │   └── lang/                 # Translation files
│       ├── liquidbounce.accesswidener # Access widener
│       └── fabric.mod.json           # Fabric mod metadata
└── test/
    ├── kotlin/                       # Kotlin tests
    └── resources/                    # Test resources

Core Components

Main Entry Point

Location: src/main/kotlin/net/ccbluex/liquidbounce/LiquidBounce.kt The main entry point initializes all systems when Minecraft starts.

Features System

Location: src/main/kotlin/net/ccbluex/liquidbounce/features/ Contains the core functionality:
  • Modules: Combat, movement, render, and other modules
  • Commands: Chat commands for controlling features
  • Misc: Additional features and utilities

Event System

Location: src/main/kotlin/net/ccbluex/liquidbounce/event/ LiquidBounce uses a custom event system:
  • Event definitions
  • Event handlers and listeners
  • Event sequencing

Configuration System

Location: src/main/kotlin/net/ccbluex/liquidbounce/config/ Handles:
  • Module configurations
  • User settings
  • Config serialization/deserialization
  • Auto-save functionality

Rendering System

Location: src/main/kotlin/net/ccbluex/liquidbounce/render/ Provides:
  • UI rendering
  • ESP and overlay rendering
  • Shader support
  • Font rendering

Script API

Location: src/main/kotlin/net/ccbluex/liquidbounce/script/ Enables custom scripts:
  • JavaScript support via GraalVM Polyglot
  • Script module system
  • Script API bindings

Integration Layer

Location: src/main/kotlin/net/ccbluex/liquidbounce/integration/ External integrations:
  • Discord Rich Presence
  • ViaFabricPlus compatibility
  • Browser integration (MCEF)
  • Theme system integration

Theme System

Theme Structure

src-theme/
├── src/                   # Svelte source code
├── public/               # Static assets
├── dist/                 # Build output
├── resources/            # Bundled resources
├── package.json          # NPM dependencies
├── rollup.config.js      # Build configuration
└── bundle.cjs            # Bundling script

Theme Build Process

  1. Install dependencies: npm install
  2. Build Svelte app: Rollup bundles the code
  3. Create theme archive: Bundle into ZIP
  4. Include in resources: Copied to mod resources
See build.gradle.kts:220-270 for the Gradle integration.

Build System

Gradle Configuration

Main Build File: build.gradle.kts Key sections:
  1. Plugins (lines 26-33)
    • Fabric Loom for Minecraft modding
    • Kotlin JVM plugin
    • Detekt for code quality
    • Node.js plugin for theme building
  2. Dependencies (lines 97-174)
    • Minecraft and Fabric
    • Kotlin libraries
    • External libraries (bundled via JiJ)
    • Recommended mods
  3. Resource Processing (lines 178-218)
    • Theme bundling
    • Metadata expansion
    • Contributor fetching
  4. Theme Tasks (lines 222-270)
    • NPM installation
    • Theme building
    • Resource bundling

Version Catalog

Location: gradle/libs.versions.toml Centralized version management for:
  • Minecraft and Fabric versions
  • Kotlin and library versions
  • Plugin versions
  • Dependency bundles

Mixin System

What are Mixins?

Mixins modify Minecraft classes at runtime without shipping Mojang’s copyrighted code. Documentation: Mixin Documentation

Mixin Location

Java mixins: src/main/java/ (Mixins are typically written in Java)

Access Widener

Location: src/main/resources/liquidbounce.accesswidener Makes private Minecraft fields/methods accessible without reflection. Configured in build.gradle.kts:94:
loom {
    accessWidenerPath = file("src/main/resources/liquidbounce.accesswidener")
}

Testing

Test Structure

src/test/
├── kotlin/                # Kotlin test files
│   └── net/ccbluex/liquidbounce/
└── resources/             # Test resources
    ├── generic/
    ├── invcleaner/
    └── scaffold/

Test Framework

  • Kotlin Test: Kotlin’s built-in testing
  • JUnit Platform: Test execution
  • Kotlinx Coroutines Test: Async testing
Run tests:
./gradlew test

Code Quality

Detekt Configuration

Config: config/detekt/detekt.yml Baseline: config/detekt/baseline.xml Detekt enforces Kotlin code quality standards.

i18n Verification

Task: verifyI18nJsonKeys Verifies translation files have consistent keys with en_us.json as baseline.

Advanced Features

Machine Learning

Location: src/main/kotlin/net/ccbluex/liquidbounce/deeplearn/ Integrates Deep Java Library (DJL) for:
  • PyTorch models
  • AI-based gameplay features

Polyglot Scripting

Supports multiple languages via GraalVM:
  • JavaScript (primary)
  • Future language support

ViaFabricPlus Integration

Enables multi-version protocol support for connecting to servers on different Minecraft versions.

Development Tools

Useful Gradle Tasks

# Generate Minecraft sources
./gradlew genSources

# Run the client
./gradlew runClient

# Build the mod
./gradlew build

# Run Detekt
./gradlew detekt

# Verify translations
./gradlew verifyI18nJsonKeys

# Generate documentation
./gradlew dokka

IDE Configuration

IntelliJ IDEA: .idea/ contains project configuration
  • Copyright headers auto-applied
  • Code style settings
  • Run configurations

Package Conventions

All code follows the package structure:
net.ccbluex.liquidbounce.<component>
Examples:
  • net.ccbluex.liquidbounce.features.module
  • net.ccbluex.liquidbounce.event
  • net.ccbluex.liquidbounce.config

Resource Management

Assets

Location: src/main/resources/assets/liquidbounce/
  • Textures
  • Sounds
  • Shaders
  • Theme bundles

Translations

Location: src/main/resources/resources/liquidbounce/lang/ Supports multiple languages with JSON files:
  • en_us.json (baseline)
  • Other language files

Distribution

JAR Packaging

The build process creates:
  • Main JAR: Contains mod and bundled dependencies
  • Sources JAR: For development reference
  • Mappings: Included for deobfuscation

Additional Files

Location: zip_include/ Extra files copied to build/libs/zip/ during build (see build.gradle.kts:393-396).

Next Steps

Build docs developers (and LLMs) love