Documentation

Getting Started

Add-ons are Fabric mods that compile against LiquidBounce itself. They build on the same classes as the client's own modules, commands and HUD components, can ship Mixins and access wideners, and are loaded by the client while it starts. For small features, the Script API is the simpler option.

Add-ons are written in Kotlin or Java. The examples in this section are Kotlin, Using Java covers where Java differs. Minecraft's classes carry Mojang's official names, there is no other mapping layer.

Requirements

• JDK 25
• Git
• An IDE with Kotlin support, for example IntelliJ IDEA

Creating the project

Start from the add-on template: click Use this template on GitHub, or clone it.

git clone --depth 1 https://github.com/CCBlueX/LiquidBounce-Addon-Template my-addon

Then rename the example:

The build setup is explained in Project Setup, the manifest in Manifest and Lifecycle.

Writing a module

A module is a ClientModule. Its settings and event handlers are properties. This one counts the player's jumps and reports every tenth:

package com.example.addon.modules

import com.example.addon.ExampleCategories
import net.ccbluex.liquidbounce.event.events.PlayerJumpEvent
import net.ccbluex.liquidbounce.event.handler
import net.ccbluex.liquidbounce.features.module.ClientModule
import net.ccbluex.liquidbounce.utils.client.chat

object ModuleJumpCounter : ClientModule("JumpCounter", ExampleCategories.EXAMPLE) {

    private val every by int("Every", 10, 1..100, "jumps")

    private var jumps = 0

    override fun onEnabled() {
        jumps = 0
    }

    @Suppress("unused")
    private val jumpHandler = handler<PlayerJumpEvent> {
        jumps++

        if (jumps % every == 0) {
            chat("You jumped $jumps times.")
        }
    }

}

The handler only runs while the module is enabled and the player is in a world. chat prints to the chat without sending anything to the server.

Registering the module

Modules are registered by the entrypoint, the class named under liquidbounce in fabric.mod.json:

package com.example.addon

import com.example.addon.modules.ModuleJumpCounter
import net.ccbluex.liquidbounce.features.addon.LiquidBounceAddon

class ExampleAddon : LiquidBounceAddon() {

    override val categories = listOf(ExampleCategories.EXAMPLE)

    override fun onInitialize() {
        registerModules(ModuleJumpCounter)
    }

}

categories registers the template's Example category. A module can also go into a built-in category from ModuleCategories, see Categories.

Adding a description

The ClickGUI shows a description for every module and setting. They come from src/main/resources/resources/<id>/lang/en_us.json:

{
  "liquidbounce.module.jumpCounter.description": "Counts your jumps.",
  "liquidbounce.module.jumpCounter.every.description": "Jumps between two messages."
}

A module without an en_us description logs a warning when it is registered. The key format is explained in Translations.

Running and building

./gradlew runClient

starts Minecraft with LiquidBounce and the add-on. Join a world, open the ClickGUI with RIGHT SHIFT and find JumpCounter under Example. .addon list lists the add-on, .addon info <id> shows what it registered.

./gradlew build

writes the add-on to build/libs/, as example-addon-1.0.0+26.3.jar next to a -sources jar. Install the jar like any other mod, as an additional mod in LiquidLauncher or in the mods folder of a manual installation. To offer it on the Marketplace, see Publishing.

Examples

• LiquidBounce-Addon-Template: the starting point, with a module, a command, a category and a Mixin.
• LiquidBounce-Addon-Extras: modules in Kotlin and Java side by side, each covered by a game test.
• LiquidBounce-Addon-ScriptAPI: a larger add-on with Mixins into LiquidBounce.
• LiquidBounce-Addon-Wry: a browser backend.