Configuration - LiquidBounce

What is Configuration?

The configuration system in LiquidBounce manages all settings, module states, and user preferences. It provides a hierarchical structure for storing and loading configurations, allowing you to save different setups for various scenarios.

The configuration system is implemented in ConfigSystem.kt and uses a hierarchy-based approach with JSON serialization.

Configuration Structure

Configurations are organized hierarchically:

LiquidBounce/
├── configs/           # User configuration files
├── backups/           # Configuration backups
└── *.json            # Root configuration files

Configuration Root

The configuration system uses a root folder in your Minecraft directory:

val rootFolder = File(mc.gameDirectory, LiquidBounce.CLIENT_NAME).apply {
    if (!exists()) {
        isFirstLaunch = true
        mkdir()
    }
}

Source: ConfigSystem.kt:56-65

Value Types

LiquidBounce supports various value types for configuration:

Boolean

True/false toggles for binary settings

Integer

Whole numbers with optional min/max ranges

Float

Decimal numbers for precise values

Text

String values for names and text input

Range

Min/max value pairs (e.g., 3.0..6.0)

Choice

Selection from predefined options

Color

RGB/RGBA color values

Block/Item

Minecraft blocks or items

Multi-Choice

Multiple selections from a list

Mode Group

Grouped settings with multiple modes

Value Implementation

Values are implemented in the Value class:

open class Value<T : Any>(
    val name: String,
    val aliases: List<String> = emptyList(),
    private var defaultValue: T,
    val valueType: ValueType,
    var independentDescription: Boolean = false
)

Source: Value.kt:63-73

Value Properties

Each value has several important properties:

Key Path

Values are identified by hierarchical keys:

val baseKey: String = "${ConfigSystem.KEY_PREFIX}.module.${name.toLowerCamelCase()}"

Example: liquidbounce.module.killAura.range

Default Value

Each value stores its default state for restoration:

open fun restore() {
    set(defaultValue)
}

Source: Value.kt:254-256

Value Listeners

Values support change listeners for reactive behavior:

fun onChange(listener: ValueListener<T>)
fun onChanged(listener: ValueChangedListener<T>)

Source: Value.kt:264-269

Saving and Loading Configs

Automatic Saving

LiquidBounce automatically saves configurations when:

You change a setting
You close the game
You switch configurations

Manual Operations

Save
Load
Backup

// Save all configs
ConfigSystem.storeAll()

// Save specific config
ConfigSystem.store(config)

Or use the command:

.config save myconfig

// Load all configs
ConfigSystem.loadAll()

// Load specific config
ConfigSystem.load(config)

Or use the command:

.config load myconfig

// Create a backup
ConfigSystem.backup("my-backup")

// Restore from backup
ConfigSystem.restore("my-backup")

Configuration Files

Configurations are stored as JSON files:

{
  "name": "modules",
  "value": [
    {
      "name": "KillAura",
      "value": [
        {
          "name": "Range",
          "value": 4.2
        },
        {
          "name": "enabled",
          "value": true
        }
      ]
    }
  ]
}

Serialization and Deserialization

The configuration system uses Gson for JSON processing:

Serialization

fun serializeValueGroup(valueGroup: ValueGroup, writer: Writer, gson: Gson = fileGson) {
    gson.newJsonWriter(writer).use {
        gson.toJson(valueGroup, ValueGroup::class.javaObjectType, it)
    }
}

Source: ConfigSystem.kt:228-232

Deserialization

fun deserializeValueGroup(valueGroup: ValueGroup, reader: Reader, gson: Gson = fileGson) {
    gson.newJsonReader(reader).use { reader ->
        deserializeValueGroup(valueGroup, reader.parseTree())
    }
}

Source: ConfigSystem.kt:243-247

Auto-Config Feature

One of LiquidBounce’s most powerful features is the Auto-Config system, which provides server-optimized configurations.

Auto-configs are community-made configurations designed for specific servers and game modes.

What is Auto-Config?

Auto-config automatically adjusts your settings for optimal performance on specific servers. It includes:

Module enable/disable states
Optimized value settings
Server-specific configurations
Protocol version information
Bypass status indicators

Loading Auto-Configs

suspend fun loadAutoConfig(autoConfig: AutoSettings) = withLoading {
    ClientApi.requestSettingsScript(autoConfig.settingId).use(::loadAutoConfig)
}

Source: AutoConfig.kt:102-104

Auto-Config Metadata

Auto-configs include metadata about their creation:

Server Address: Target server
Protocol Version: Minecraft version
Author: Who created it
Date/Time: When it was created
Client Version: LiquidBounce version used
Status: Bypass status (bypassing, outdated, etc.)

jsonObject.addProperty("author", author)
jsonObject.addProperty("date", date)
jsonObject.addProperty("time", time)
jsonObject.addProperty("clientVersion", LiquidBounce.clientVersion)
jsonObject.addProperty("protocolName", protocolName)
jsonObject.addProperty("protocolVersion", protocolVersion)

Source: AutoConfig.kt:289-298

Value Groups

Value groups organize related settings together:

Types of Value Groups

ValueGroup

Basic grouping of related values

object GlobalSettings : ValueGroup("Commands") {
    var prefix by text("Prefix", ".")
    val hintCount by int("HintCount", 5, 0..10)
}

ToggleableValueGroup

Groups that can be enabled/disabled (used by modules)

open class ClientModule(
    name: String,
    category: ModuleCategory,
    state: Boolean = false
) : ToggleableValueGroup(null, name, state)

ModeValueGroup

Groups with multiple selectable modes

val modes = choices(
    "Mode",
    VanillaMode,
    CustomMode,
    active = VanillaMode
)

Configuration Best Practices

Organize by Purpose

Create separate configs for different servers or game modes

Use Descriptive Names

Name your configs clearly: hypixel-bedwars, survival-vanilla, etc.

Backup Regularly

The system auto-backups, but manual backups before major changes are wise

Test Auto-Configs

Always test auto-configs in a safe environment before using on main servers

Document Changes

Keep notes about what each config is optimized for

Value State Management

Values use reactive state management with StateFlow:

private val stateFlow = MutableStateFlow(inner)

fun asStateFlow(): StateFlow<T> = stateFlow

Source: Value.kt:91-93

This allows UI components to reactively update when values change.

Include Configuration

When creating auto-configs, you can control what gets included:

var includeConfiguration = IncludeConfiguration.Companion.DEFAULT

This determines:

Whether to include module binds
Whether to include hidden states
Which modules to include
Which categories to include

Finding Values by Key

The configuration system provides lookup functions:

fun findValueByKey(key: String): Value<*>? {
    ensureRootKeys()
    val normalizedKey = normalizeKeyInput(key)
    return configs.asSequence()
        .flatMap { it.collectValuesRecursively().asSequence() }
        .firstOrNull { it.key?.equals(normalizedKey, true) == true }
}

Source: ConfigSystem.kt:90-96

Using Configurations via Commands

# Show all available configs
.config list

# Show local configs
.localconfig list

Configuration Events

Values emit events when changed:

EventManager.callEvent(ValueChangedEvent(this))

Source: Value.kt:243

Other parts of the client can listen to these events and react accordingly.

Immutable Values

Some values are marked as immutable and cannot be changed:

fun immutable() = apply {
    isImmutable = true
}

Source: Value.kt:260-262

Attempts to modify immutable values are silently ignored.

Conditional Inclusion

Values can be conditionally excluded from configs:

fun doNotIncludeWhen(condition: () -> Boolean) = apply {
    doNotInclude = condition
}

Source: Value.kt:276-278

This is useful for values that should only be saved in specific contexts.

Troubleshooting

Config Not Loading

Check if the file exists in the configs folder
Verify JSON syntax is valid
Look for error messages in the console
Try reloading all configs with .config reload

Settings Not Saving

Ensure LiquidBounce has write permissions
Check if the value is marked as immutable
Verify the config file isn’t corrupted

Auto-Config Issues

Verify your protocol version matches
Check server compatibility
Ensure you have the latest LiquidBounce version
Try loading the config manually

Modules

Learn about modules that configurations control

Commands

Use commands to manage configurations

Scripting

Access configuration programmatically

ClickGUI

Manage settings through the GUI

Getting Started

Core Concepts

Modules

Features

Scripting

Advanced

​What is Configuration?

​Configuration Structure

​Configuration Root

​Value Types

Boolean

Integer

Float

Text

Range

Choice

Color

Block/Item

Multi-Choice

Mode Group

​Value Implementation

​Value Properties

​Key Path

​Default Value

​Value Listeners

​Saving and Loading Configs

​Automatic Saving

​Manual Operations

​Configuration Files

​Serialization and Deserialization

​Serialization

​Deserialization

​Auto-Config Feature

​What is Auto-Config?

​Loading Auto-Configs

​Auto-Config Metadata

​Value Groups

​Types of Value Groups

​Configuration Best Practices

​Value State Management

​Include Configuration

​Finding Values by Key

​Using Configurations via Commands

​Configuration Events

​Immutable Values

​Conditional Inclusion

​Troubleshooting

​Related Topics

Modules

Commands

Scripting

ClickGUI

Build docs developers (and LLMs) love

What is Configuration?

Configuration Structure

Configuration Root

Value Types

Value Implementation

Value Properties

Key Path

Default Value

Value Listeners

Saving and Loading Configs

Automatic Saving

Manual Operations

Configuration Files

Serialization and Deserialization

Serialization

Deserialization

Auto-Config Feature

What is Auto-Config?

Loading Auto-Configs

Auto-Config Metadata

Value Groups

Types of Value Groups

Configuration Best Practices

Value State Management

Include Configuration

Finding Values by Key

Using Configurations via Commands

Configuration Events

Immutable Values

Conditional Inclusion

Troubleshooting

Related Topics