Documentation

Manifest and Lifecycle

fabric.mod.json

An add-on is described by its fabric.mod.json, like any Fabric mod. What LiquidBounce reads from it:

{
  "schemaVersion": 1,
  "id": "example-addon",
  "version": "${version}",
  "name": "Example Addon",
  "description": "An add-on template for LiquidBounce add-ons.",
  "authors": ["You"],
  "contact": {
    "homepage": "https://liquidbounce.net/",
    "sources": "https://github.com/CCBlueX/LiquidBounce-Addon-Template",
    "issues": "https://github.com/CCBlueX/LiquidBounce-Addon-Template/issues"
  },
  "license": "GPL-3.0-or-later",
  "icon": "resources/example-addon/icon.png",
  "environment": "client",
  "entrypoints": {
    "liquidbounce": ["com.example.addon.ExampleAddon"]
  },
  "mixins": ["example-addon.mixins.json"],
  "accessWidener": "example-addon.accesswidener",
  "depends": {
    "minecraft": ">=${minecraft_version}",
    "fabricloader": ">=${loader_version}",
    "fabric-language-kotlin": ">=${fabric_kotlin_version}",
    "liquidbounce": "*"
  },
  "custom": {
    "liquidbounce": {
      "color": "#FF5555"
    },
    "modmenu": {
      "parent": "liquidbounce"
    }
  }
}

Resource files

Everything the add-on ships besides code goes into src/main/resources/resources/<id>/: translations under lang/, the mod icon, category icons.

Never use assets/<id>/. Fabric registers every mod jar as a resource pack, so anything under assets/ becomes part of Minecraft's resources, where anything that inspects the loaded resource packs can see it. LiquidBounce reads the resources/ folder from the jar directly.

Lifecycle

flowchart TD
    jar["mods/your-addon.jar"] --> discover

    subgraph startup ["LiquidBounce startup"]
        direction TB
        discover["AddonManager.discover()"]
        regcat["registerCategories()"]
        init["initializeAddons()"]
        loadAll["ConfigSystem.loadAll()"]
        started["notifyStarted()"]
        stopping["notifyStopping()"]
        storeAll["ConfigSystem.storeAll()"]
    end

    discover --> regcat --> init --> loadAll --> started
    started --> running(["game running"])
    running --> stopping --> storeAll

    regcat -. your code .-> h1["categories"]
    init -. your code .-> h2["onInitialize()<br/>registerModules / registerCommand / config"]
    started -. your code .-> h3["onStarted()<br/>settings are restored"]
    stopping -. your code .-> h4["onStopping()<br/>flush state"]

The entrypoint is constructed while the client discovers add-ons. metadata and everything read from it, such as id and logger, is only available once the constructor has returned, so use them from the hooks and not from property initializers. Add-ons run in the order of their ids.

object ExampleSettings : ValueGroup("General") {
    val greeting by text("Greeting", "Hello")
}

class ExampleAddon : LiquidBounceAddon() {

    override fun onInitialize() {
        config(tree = mutableListOf(ExampleSettings))
    }

    override fun onStarted() {
        logger.info("Greeting is '${ExampleSettings.greeting}'")
    }

    override fun onStopping() {
        logger.info("Shutting down")
    }

}

When categories, onInitialize() or onStarted() throws, the add-on is marked as errored and everything it registered through the functions below is withdrawn again. The client and the other add-ons keep running. An exception in onStopping() is logged, nothing is withdrawn.

Registering

Register through the add-on, not through ModuleManager or CommandManager directly, so a failing add-on can be withdrawn.

HUD components are registered through HudComponentManager and are not withdrawn.

Properties

The add-on is an event listener itself. Its handlers run while its state is LOADED. It also has the Minecraft shortcuts every module has: mc, player, world, network, interaction and inGame.

object ChatLogger : EventListener {

    @Suppress("unused")
    private val chatHandler = handler<ChatReceiveEvent> { event ->
        println(event.message)
    }

}

class ListenerAddon : LiquidBounceAddon() {

    override fun onInitialize() {
        registerListeners(ChatLogger)
    }

}

Disabling add-ons

The JVM argument -Dliquidbounce.disableAddons=<id>,<id> skips the listed add-ons, -Dliquidbounce.disableAddons=all skips every one. A skipped add-on is constructed but none of its hooks run, and its translations are not loaded. .addon info shows it as DISABLED.