Documentation

Settings

Settings are declared on a ValueGroup: a module, a mode, a nested group, or a group passed to the add-on's config(...). They show up in the ClickGUI and are stored with the client's configs.

In Kotlin, by reads the setting like a plain property. Without by the property holds the Value, which is needed for its modifiers or to set it from code. In Java, fields hold the Value and are read with get(), see Using Java.

private val range by float("Range", 4.2f, 1f..6f, "blocks") // Float
private val rangeValue = float("Range", 4.2f, 1f..6f, "blocks") // Value<Float>

The name is the key in the config file and part of the setting's translation key. Renaming a setting loses its stored value, unless the old name goes into aliases where the builder has that parameter. A module already has settings named Enabled, Bind and Hidden.

In Kotlin, a property holding a setting cannot be called name, tag, key or anything else Value or ClientModule already declares.

Builder summary

boolean(name, default, aliases)

Creates an on/off setting. Java: bool.

Example:

private val sneak by boolean("Sneak", true)

---

int(name, default, range, suffix, aliases)

Creates an integer setting between the bounds of range. Java: integer, also as integer(name, default, min, max, suffix).

Example:

private val delay by int("Delay", 10, 0..40, "ticks")

---

float(name, default, range, suffix, aliases)

Creates a floating-point setting between the bounds of range. Java: floating, also as floating(name, default, min, max, suffix).

Example:

private val range by float("Range", 4.2f, 1f..6f, "blocks")

---

intRange(name, default, range, suffix, aliases)

Creates a setting with a low and a high integer, both between the bounds of range.

Example:

private val cps by intRange("CPS", 8..12, 1..20)

---

floatRange(name, default, range, suffix, aliases)

Creates a setting with a low and a high floating-point value, both between the bounds of range.

Example:

private val jitter by floatRange("Jitter", 0.5f..1.5f, 0f..5f, "deg")

---

text(name, default)

Creates a text setting.

Example:

private val message by text("Message", "Hello")

---

textList(name, default)

Creates a list of texts the player can add to and remove from.

Example:

private val messages by textList("Messages", mutableListOf("Hello", "Hi"))

---

regex(name, default)

Creates a regular expression setting, edited as text.

Example:

private val filter by regex("Filter", Regex("^[a-z0-9_]+$"))

---

regexList(name, default)

Creates a list of regular expressions.

Example:

private val ignored by regexList("Ignored", mutableListOf(Regex("\\[Ad].*")))

---

color(name, default)

Creates a color setting with alpha. See Color4b.

Example:

private val fill by color("Fill", Color4b(0, 160, 255, 120))

---

key(name, default)

Creates a setting holding a single key, as InputConstants.Key.

Example:

private val openKey by key("OpenKey", InputConstants.KEY_R)

---

bind(name, default)

Creates a key binding like the one every module has, with an action (TOGGLE, HOLD, SMART) and modifier keys. Check it against key events with InputBind.matchesKeyPress(event) and matchesKeyRelease(event).

Example:

private val boostBind by bind("BoostBind", InputBind(InputConstants.Type.KEYBOARD, InputConstants.KEY_V, InputBind.BindAction.HOLD))

---

enumChoice(name, default, aliases)

Creates a single choice between the constants of an enum. The enum implements Tagged, whose tag is the name shown for each constant. Java: enumChoice(name, default). Any other set of Tagged values works with enumChoice(name, default, choices).

Example:

enum class Target(override val tag: String) : Tagged {
    PLAYERS("Players"),
    MOBS("Mobs"),
    ANIMALS("Animals"),
}

private val target by enumChoice("Target", Target.PLAYERS)

---

multiEnumChoice(name, vararg default, canBeNone)

Creates a choice of any number of an enum's constants. The value is a MutableSet. default can also be an Iterable or an EnumSet, the EnumSet form takes choices to offer only some constants. Java: multiEnumChoice(name, type, default, canBeNone) with the enum's Class.

Example:

enum class Part(override val tag: String) : Tagged {
    HEAD("Head"),
    BODY("Body"),
    FEET("Feet"),
}

private val parts by multiEnumChoice("Parts", Part.HEAD, Part.BODY)

---

easing(name, default)

Creates a choice of an Easing curve. Easing.transform(x) maps progress from 0 to 1.

Example:

private val transition by easing("Transition", Easing.QUAD_OUT)

---

curve(name) { ... }

Creates a curve the player shapes by moving points. Keep the CurveValue and call transform(x) to read the curve at x. The builder takes the axes as "Label" x range and "Label" y range, the initial points(...) (at least two, inside the axes) and optionally tension (0 to 1, default 0.4).

Example:

private val falloff = curve("Falloff") {
    "Distance" x 0f..8f
    "Strength" y 0f..1f
    points(Vector2f(0f, 1f), Vector2f(8f, 0f))
}

val strength = falloff.transform(3f)

---

file(name, default, dialogMode, supportedExtensions)

Creates a file setting with a button that opens the system's file dialog. Paths inside the LiquidBounce folder are stored relative to it.

Example:

private val sound by file("Sound", dialogMode = FileDialogMode.OPEN_FILE, supportedExtensions = setOf("ogg"))

---

block(name, default) and item(name, default)

Create a setting holding one block or one item, picked from a list in the ClickGUI.

Example:

private val ore by block("Ore", Blocks.DIAMOND_ORE)
private val food by item("Food", Items.GOLDEN_APPLE)

---

blocks(name, default), items(name, default) and other registry lists

Create a set of registry entries, picked from a searchable list in the ClickGUI. default is a SequencedSet, for example linkedSetOf(...).

Example:

private val containers by blocks("Containers", linkedSetOf(Blocks.CHEST, Blocks.BARREL))
private val throwables by items("Throwables", linkedSetOf(Items.ENDER_PEARL, Items.SNOWBALL))
private val alerts by sounds("Alerts", linkedSetOf(SoundEvents.ANVIL_LAND))
private val effects by mobEffects("Effects", linkedSetOf(MobEffects.SPEED.value()))
private val mobs by entityTypes("Mobs", linkedSetOf(EntityTypes.ZOMBIE, EntityTypes.SKELETON))
private val enchantments by enchantments("Enchantments", linkedSetOf(Identifier.withDefaultNamespace("sharpness")))
private val outgoing by c2sPackets("Outgoing", sortedSetOf())
private val incoming by s2cPackets("Incoming", sortedSetOf())

A packet matches when event.packet.type().id in outgoing.

---

itemList(name, default)

Creates an ordered list of items, which may contain an item more than once.

Example:

private val hotbar by itemList("Hotbar", mutableListOf(Items.DIAMOND_SWORD, Items.BOW))

---

item(name, default)

Creates a setting holding a single item.

Example:

private val weapon by item("Weapon", Items.DIAMOND_SWORD)

---

vec2f(name, default), vec3i(name, default, useLocateButton, aliases) and vec3d(...)

Create a vector setting. With useLocateButton, the ClickGUI shows a button that sets a 3D vector to the block the player looks at, or to the player's position.

Example:

private val offset by vec2f("Offset", Vector2f(0f, 0f))
private val home by vec3i("Home", Vec3i.ZERO)
private val anchor by vec3d("Anchor", Vec3.ZERO, useLocateButton = false)

---

choices(name, modes)

Creates a choice between modes, each a Mode with settings and handlers of its own. Available in modules and other toggleable groups; a Mode declares nested modes with modes(name, active, choices).

Each mode points back to the group with override val parent. activeMode returns the selected one.

Example:

object ModuleNotifier : ClientModule("Notifier", ModuleCategories.MISC) {

    private val output = choices("Output", Chat, Title)

    private object Chat : Mode("Chat") {
        override val parent get() = output
        val prefix by text("Prefix", "[!]")
    }

    private object Title : Mode("Title") {
        override val parent get() = output
        val duration by int("Duration", 40, 10..200, "ticks")
    }

}

---

tree(group)

Nests a group of settings. A ValueGroup only groups them; a ToggleableValueGroup also has its own on/off switch, and handlers declared in it only run while it and its parent are enabled. treeAll(vararg groups) nests several at once.

Example:

object ModuleAutoLog : ClientModule("AutoLog", ModuleCategories.PLAYER) {

    private object Health : ToggleableValueGroup(this, "Health", true) {
        val below by float("Below", 6f, 1f..20f)
    }

    private object Timing : ValueGroup("Timing") {
        val delay by int("Delay", 0, 0..20, "ticks")
    }

    init {
        tree(Health)
        tree(Timing)
    }

}

Modifiers

Every builder returns the Value, and these return it again, so they chain:

Example:

private val mode by enumChoice("Mode", Target.PLAYERS)

private val range by float("Range", 4f, 1f..6f)
    .visibleWhen { mode == Target.MOBS }
    .onChange { it.coerceAtMost(5f) }
    .onChanged { println("Range is now $it") }

private val secret by text("Secret", "")
    .notPersistent()
    .doNotIncludeAlways()

get(), set(value) and restore() read, change and reset a Value directly. asStateFlow() exposes it as a Kotlin StateFlow.