Skip to content

Configuration Library

Comprehensive user-configurable settings management system for the Lilia framework.

Overview

The configuration library provides comprehensive functionality for managing user-configurable settings in the Lilia framework. It handles the creation, storage, retrieval, and persistence of various types of options including boolean toggles, numeric sliders, color pickers, text inputs, and dropdown selections. The library operates on both client and server sides, with automatic persistence to JSON files and optional networking capabilities for server-side options. It includes a complete user interface system for displaying and modifying options through the configuration menu, with support for categories, visibility conditions, and real-time updates. The library ensures that all user preferences are maintained across sessions and provides hooks for modules to react to option changes.

lia.config.add(key, name, value, callback, data)

Register a config entry with defaults, UI metadata, and optional callback.

During schema/module initialization to expose server-stored configuration.

Parameters:

string key Unique identifier for the config entry.

string name Display text or localization key for UI.

any value Default value; type inferred when data.type is omitted.

function callback optional Invoked server-side as callback(oldValue, newValue) after set().

table data Fields such as type, desc, category, options/optionsFunc, noNetworking, etc.

Example Usage:

    lia.config.add("MaxThirdPersonDistance", "maxThirdPersonDistance", 100, function(old, new)
        lia.option.set("thirdPersonDistance", math.min(lia.option.get("thirdPersonDistance", new), new))
    end, {category = "Lilia", type = "Int", min = 10, max = 200})
lia.config.getOptions(key)

Resolve a config entry's selectable options, static list or generated.

Before rendering dropdown-type configs or validating submitted values.

Parameters:

string key Config key to resolve options for.

Returns:

table Options array or key/value table; empty when unavailable.

Example Usage:

    local opts = lia.config.getOptions("Theme")
lia.config.setDefault(key, value)

Override the default value for an already registered config entry.

During migrations, schema overrides, or backward-compatibility fixes.

Parameters:

string key Config key to override.

any value New default value.

Example Usage:

    lia.config.setDefault("StartingMoney", 300)
lia.config.forceSet(key, value, noSave)

Force-set a config value and fire update hooks without networking.

Runtime adjustments (admin tools/commands) or hot reload scenarios.

Parameters:

string key Config key to change.

any value Value to assign.

boolean noSave optional When true, skip persisting to disk.

Example Usage:

    lia.config.forceSet("MaxCharacters", 10, false)
lia.config.set(key, value)

Set a config value, fire update hooks, run server callbacks, network to clients, and persist.

Through admin tools/commands or internal code updating configuration.

Parameters:

string key Config key to change.

any value Value to assign and broadcast.

Example Usage:

    lia.config.set("RunSpeed", 420)
lia.config.get(key, default)

Retrieve a config value with fallback to its stored default or a provided default.

Anywhere configuration influences gameplay or UI logic.

Parameters:

string key Config key to read.

any default Optional fallback when no stored value or default exists.

Returns:

any Stored value, default value, or supplied fallback.

Example Usage:

    local walkSpeed = lia.config.get("WalkSpeed", 200)
lia.config.load()

Load config values from the database (server) or request them from the server (client).

On initialization to hydrate lia.config.stored after database connectivity.

Example Usage:

    hook.Add("DatabaseConnected", "LoadLiliaConfig", lia.config.load)
lia.config.getChangedValues(includeDefaults)

Collect config entries whose values differ from last synced values or their defaults.

Prior to sending incremental config updates to clients.

Parameters:

boolean includeDefaults optional When true, compare against defaults instead of last synced values.

Returns:

table key → value for configs that changed.

Example Usage:

    local changed = lia.config.getChangedValues()
    if next(changed) then lia.config.send() end
lia.config.hasChanges()

Check whether any config values differ from the last synced snapshot.

To determine if a resync to clients is required.

Returns:

boolean True when at least one config value has changed.

Example Usage:

    if lia.config.hasChanges() then lia.config.send() end
lia.config.send(client)

Send config values to one player (full payload) or broadcast only changed values.

After config changes or when a player joins the server.

Parameters:

Player client optional Target player for full sync; nil broadcasts only changed values.

Example Usage:

    hook.Add("PlayerInitialSpawn", "SyncConfig", function(ply) lia.config.send(ply) end)
    lia.config.send() -- broadcast diffs
lia.config.save()

Persist all config values to the database.

After changes, on shutdown, or during scheduled saves.

Example Usage:

    lia.config.save()
lia.config.reset()

Reset all config values to defaults, then save and sync to clients.

During admin resets or troubleshooting.

Example Usage:

    lia.config.reset()