Character¶
Character helpers for Lilia character creation, lookup, loading, caching, variable registration, persistence, and cleanup.
Overview
lia.char.getCharacter(charID, client, callback)View Source
Purpose
Gets a character by ID from the loaded cache. On the server, missing characters are loaded from the database. On the client, missing characters are requested from the server and resolved through the callback.
Realm
Shared
Parameters
number charID The character ID to retrieve.
Player client optional The player requesting or owning the character. Used server-side when loading a missing character.
function callback optional Optional callback called with the character when it is available.
Returns
Character|nil The loaded character when it is already available immediately.
Example Usage
lia.char.getCharacter(charID, client, function(character)
if character then print(character:getName()) end
end)
lia.char.getAll()View Source
Purpose
Gets every currently active player character.
Realm
Shared
Returns
table A table keyed by Player with Character values for players that currently have a character.
Example Usage
for client, character in pairs(lia.char.getAll()) do
print(client:Name(), character:getName())
end
lia.char.isLoaded(charID)View Source
Purpose
Checks whether a character ID is currently present in the loaded character cache.
Realm
Shared
Parameters
number charID The character ID to check.
Returns
boolean True if the character is loaded, otherwise false.
Example Usage
if lia.char.isLoaded(charID) then print("Character is loaded") end
lia.char.addCharacter(id, character)View Source
Purpose
Adds a character to the loaded character cache and resolves any pending clientside request callback for that character ID.
Realm
Shared
Parameters
Returns
nil This function does not return a value.
Example Usage
lia.char.addCharacter(id, character)
lia.char.removeCharacter(id)View Source
lia.char.new(data, id, client, steamID)View Source
Purpose
Creates a character object from registered character variables, supplied data, an optional ID, and an optional owning player or SteamID.
Realm
Shared
Parameters
table data Character data keyed by registered character variable name.
number id optional The character ID. Defaults to 0 when omitted.
Player client optional The player associated with the character.
string steamID optional Fallback SteamID used when a valid player is not available.
Returns
Character A character object using `lia.meta.character` as its metatable.
Example Usage
local character = lia.char.new(data, id, client)
lia.char.hookVar(varName, hookName, func)View Source
Purpose
Registers a named callback for a character variable hook table.
Realm
Shared
Parameters
string varName The character variable name to attach the hook to.
string hookName The unique hook name for the callback.
function func The callback function to store.
Returns
nil This function does not return a value.
Example Usage
lia.char.hookVar("money", "TrackMoneyChange", function(character, value) end)
lia.char.registerVar(key, data)View Source
Purpose
Registers a character variable definition and generates matching character getter and setter methods when applicable.
Realm
Shared
Parameters
string key The character variable key.
table data Variable metadata such as default value, database field, validation, networking, display, getter, setter, and sync behavior.
Returns
nil This function does not return a value.
Example Usage
lia.char.registerVar("example", {
default = "value",
field = "example",
fieldType = "string"
})
lia.char.getCharData(charID, key)View Source
Purpose
Reads saved key-value character data for a character from `lia_chardata` and decodes stored values.
Realm
Server
Parameters
number|string charID The character ID whose data should be read.
string key optional Optional data key to return from the decoded data table.
Returns
table|any|nil The full decoded character data table, one value when `key` is provided, or nil when the character ID is invalid.
Example Usage
local data = lia.char.getCharData(charID)
local value = lia.char.getCharData(charID, "rgn")
lia.char.getCharDataRaw(charID, key)View Source
Purpose
Reads saved key-value character data directly from `lia_chardata`, optionally returning a single decoded key.
Realm
Server
Parameters
number|string charID The character ID whose data should be read.
string key optional Optional data key to read.
Returns
table|any|false|nil The decoded data table when no key is provided, the decoded value for a key, false when a requested key does not exist, or nil when the character ID is invalid.
Example Usage
local value = lia.char.getCharDataRaw(charID, "customKey")
lia.char.getOwnerByID(ID)View Source
Purpose
Finds the online player currently using a character ID.
Realm
Shared
Parameters
number|string ID The character ID to search for.
Returns
Player|nil The owning player if the character is active online.
Example Usage
local owner = lia.char.getOwnerByID(charID)
lia.char.getBySteamID(steamID)View Source
Purpose
Finds the active character for an online player by SteamID or SteamID64.
Realm
Shared
Parameters
string steamID The SteamID or SteamID64 to search for.
Returns
Character|nil The active character belonging to the matching online player.
Example Usage
local character = lia.char.getBySteamID("STEAM_0:1:12345")
lia.char.getTeamColor(client)View Source
Purpose
Gets the display color for a player's current character class, falling back to the player's team color.
Realm
Shared
Parameters
Player client The player whose character or team color should be resolved.
Returns
Color The class color when available, otherwise the team color.
Example Usage
local color = lia.char.getTeamColor(client)
lia.char.create(data, callback)View Source
Purpose
Creates a new character database record, builds the character object, creates its default inventory, caches it, and stores any additional character data.
Realm
Server
Parameters
table data Character creation data including name, description, model, SteamID, faction, money, recognition, and optional extra data.
function callback optional Optional callback called with the new character ID after creation completes.
Returns
nil This function does not return a value.
Example Usage
lia.char.create(data, function(charID)
print("Created character", charID)
end)
lia.char.restore(client, callback, id)View Source
Purpose
Restores all characters belonging to a player, or one specific character when an ID is provided, from the character database.
Realm
Server
Parameters
Player client The player whose characters should be restored.
function callback optional Optional callback called with a list of restored character IDs.
number id optional Optional character ID to restore instead of all characters for the player.
Returns
nil This function does not return a value.
Example Usage
lia.char.restore(client, function(characters)
PrintTable(characters)
end)
lia.char.cleanUpForPlayer(client)View Source
lia.char.delete(id, client)View Source
Purpose
Deletes a character from active memory and persistent storage, removes related character data and inventories, and synchronizes affected players.
Realm
Server
Parameters
number id The character ID to delete.
Player client optional Optional player associated with the deletion.
Returns
nil This function does not return a value.
Example Usage
lia.char.delete(charID, client)
lia.char.getCharBanned(charID)View Source
Purpose
Reads the ban state stored on a character record.
Realm
Server
Parameters
number|string charID The character ID to check.
Returns
number|nil The stored banned value, or nil when the character ID is invalid or no row exists.
Example Usage
local banned = lia.char.getCharBanned(charID)
lia.char.setCharDatabase(charID, field, value)View Source
Purpose
Updates a registered character variable field or custom character data value in persistent storage and mirrors the change to a loaded character when available.
Realm
Server
Parameters
number|string charID The character ID to update.
string field The registered character variable or custom data key to update.
any value The value to store.
Returns
boolean|nil True when an update path completes, false when the update cannot be completed, or nil when the character ID or field is invalid.
Example Usage
lia.char.setCharDatabase(charID, "money", 250)
lia.char.setCharDatabase(charID, "customKey", "value")
lia.char.unloadCharacter(charID)View Source
Purpose
Saves a loaded character, clears replicated character data for its player, cleans up inventories, removes it from the loaded cache, and runs cleanup hooks.
Realm
Server
Parameters
number charID The character ID to unload.
Returns
boolean True when the character was unloaded, or false when the character was not loaded.
Example Usage
lia.char.unloadCharacter(charID)
lia.char.unloadUnusedCharacters(client, activeCharID)View Source
Purpose
Unloads loaded characters from a player's character list except for the active character ID.
Realm
Server
Parameters
Player client The player whose unused characters should be unloaded.
number activeCharID The character ID that should remain loaded.
Returns
number The number of characters unloaded.
Example Usage
local count = lia.char.unloadUnusedCharacters(client, activeCharID)
lia.char.loadSingleCharacter(charID, client, callback)View Source
Purpose
Loads one character from the database, validates access when needed, restores inventories, caches the character, and returns it through a callback.
Realm
Server
Parameters
number charID The character ID to load.
Player client optional The player requesting or owning the character.
function callback optional Optional callback called with the loaded character or nil when loading fails.
Returns
nil This function does not return a value.
Example Usage
lia.char.loadSingleCharacter(charID, client, function(character)
if character then print(character:getName()) end
end)
Hooks
Library-specific hooks documented for this library.
CharCleanUp(character)View Source
Purpose
Runs after a loaded character is saved, detached from inventories, and removed from the loaded character cache.
Realm
Server
Parameters
Character character The unloaded character.
CharRestored(character)View Source
Purpose
Runs after a character object is rebuilt from persistent data and before its inventories finish loading.
Realm
Server
Parameters
Character character The restored character object.
CreateDefaultInventory(character)View Source
GetAttributeStartingMax(client, attributeKey)View Source
Purpose
Allows schemas, plugins, or modules to override the maximum starting value for a specific attribute.
Realm
Shared
Parameters
Player client The player creating the character.
string attributeKey The attribute key being validated.
Returns
number|nil The maximum allowed starting value for the attribute, or nil to use default behavior.
GetDefaultCharDesc(client, faction, data)View Source
Purpose
Allows schemas, plugins, or modules to provide a default character description during character creation.
Realm
Shared
Parameters
Player client The player creating the character.
any faction The submitted faction value.
table data The submitted character creation data.
Returns
string|nil The default description to use. boolean|nil Return true as the second value to force the returned description and bypass normal description validation.
GetDefaultCharName(client, faction, data)View Source
Purpose
Allows schemas, plugins, or modules to provide a default character name during character creation.
Realm
Shared
Parameters
Player client The player creating the character.
any faction The submitted faction value.
table data The submitted character creation data.
Returns
string|nil The default name to use. boolean|nil Return true as the second value to force the returned name and bypass normal name validation.
GetMaxStartingAttributePoints(client, defaultPoints)View Source
Purpose
Allows schemas, plugins, or modules to override the total starting attribute points available during character creation.
Realm
Shared
Parameters
Player client The player creating the character.
number defaultPoints The configured default starting attribute point amount.
Returns
number|nil The maximum starting attribute points, or nil to use default behavior.
OnCharDelete(client, id)View Source
OnCharVarChanged(character, key, oldValue, newValue)View Source
PlayerBodyGroupChanged(client, oldBodygroups, newBodygroups)View Source
PreCharDelete(id)View Source
Purpose
Runs before a character is deleted from memory and persistent storage.
Realm
Server
Parameters
number id The ID of the character being deleted.
SyncCharList(client)View Source
Purpose
Runs when a player whose character list contained a deleted character needs their character list synchronized.
Realm
Server
Parameters
Player client The player whose character list should be synchronized.