Character Library
Comprehensive character creation, management, and persistence system for the Lilia framework.
Overview
The character library provides comprehensive functionality for managing player characters in the Lilia framework. It handles character creation, loading, saving, and management across both server and client sides. The library operates character data persistence, networking synchronization, and provides hooks for character variable changes. It includes functions for character validation, database operations, inventory management, and character lifecycle management. The library ensures proper character data integrity and provides a robust system for character-based gameplay mechanics including factions, attributes, money, and custom character variables.
lia.char.getCharacter(charID, client, callback)
Retrieve a character by ID from cache or request a load if missing.
Anytime code needs a character object by ID (selection, networking, admin tools).
Parameters:
number charID Character database ID to fetch.Player client optional Owning player; only used server-side when loading.
function callback optional Invoked with the character once available (server cached immediately, otherwise after load/network).
Returns:
table|nil The character object if already cached; otherwise nil while loading.Example Usage:
lia.char.getCharacter(targetID, ply, function(char)
if char then
char:sync(ply)
end
end)
lia.char.getAll()
Return a table of all players currently holding loaded characters.
For admin panels, diagnostics, or mass operations over active characters.
Returns:
table Keyed by Player with values of their active character objects.Example Usage:
for ply, char in pairs(lia.char.getAll()) do
print(ply:Name(), char:getName())
end
lia.char.isLoaded(charID)
Check if a character ID currently exists in the local cache.
Before loading or accessing a character to avoid duplicate work.
Parameters:
number charID Character database ID to test.Returns:
boolean True if the character is cached, otherwise false.Example Usage:
if not lia.char.isLoaded(id) then
lia.char.getCharacter(id)
end
lia.char.addCharacter(id, character)
Insert a character into the cache and resolve any pending requests.
After successfully loading or creating a character object.
Parameters:
number id Character database ID.table character Character object to store.
Example Usage:
lia.char.addCharacter(char:getID(), char)
lia.char.removeCharacter(id)
Remove a character from the local cache.
After a character is deleted, unloaded, or no longer needed.
Parameters:
number id Character database ID to remove.Example Usage:
lia.char.removeCharacter(charID)
lia.char.new(data, id, client, steamID)
Construct a character object and populate its variables with provided data or defaults.
During character creation or when rebuilding a character from stored data.
Parameters:
table data Raw character data keyed by variable name.number id optional Database ID; defaults to 0 when nil.
Player client optional Owning player entity, if available.
string steamID optional SteamID string used when no player entity is provided.
Returns:
table New character object.Example Usage:
local char = lia.char.new(row, row.id, ply)
lia.char.hookVar(varName, hookName, func)
Register a hook function that runs when a specific character variable changes.
When modules need to react to updates of a given character variable.
Parameters:
string varName Character variable name.string hookName Unique identifier for the hook.
function func Callback invoked with (character, oldValue, newValue).
Example Usage:
lia.char.hookVar("money", "OnMoneyChanged", function(char, old, new)
hook.Run("OnCharMoneyChanged", char, old, new)
end)
lia.char.registerVar(key, data)
Register a character variable and generate accessor/mutator helpers with optional networking.
During schema load to declare character fields such as name, money, or custom data.
Parameters:
string key Variable identifier.table data Configuration table defining defaults, validation, networking, and callbacks.
Example Usage:
lia.char.registerVar("title", {
field = "title",
fieldType = "string",
default = "",
})
lia.char.getCharData(charID, key)
Read character data key/value pairs stored in the chardata table.
When modules need arbitrary persisted data for a character, optionally scoped to a single key.
Parameters:
number charID Character database ID to query.string key optional Optional specific data key to return.
Returns:
table|any|nil Table of all key/value pairs, a single value when key is provided, or nil if not found/invalid.Example Usage:
local prestige = lia.char.getCharData(charID, "prestige")
lia.char.getCharDataRaw(charID, key)
Retrieve raw character data from chardata without touching the cache.
When a direct database read is needed, bypassing any loaded character state.
Parameters:
number charID Character database ID to query.string key optional Optional key for a single value; omit to fetch all.
Returns:
any|table|false|nil Decoded value for the key, a table of all key/value pairs, false if a keyed lookup is missing, or nil on invalid input.Example Usage:
local allData = lia.char.getCharDataRaw(charID)
lia.char.getOwnerByID(ID)
Find the player entity that owns a given character ID.
When needing to target or notify the current owner of a loaded character.
Parameters:
number ID Character database ID.Returns:
Player|nil Player who currently has the character loaded, or nil if none.Example Usage:
local owner = lia.char.getOwnerByID(charID)
lia.char.getBySteamID(steamID)
Get the active character of an online player by SteamID/SteamID64.
For lookups across connected players when only a Steam identifier is known.
Parameters:
string steamID SteamID or SteamID64 string.Returns:
table|nil Character object if the player is online and has one loaded, else nil.Example Usage:
local char = lia.char.getBySteamID(targetSteamID)
lia.char.getTeamColor(client)
Return the team/class color for a player, falling back to team color.
Whenever UI or drawing code needs a consistent color for the player's current class.
Parameters:
Player client Player whose color is requested.Returns:
table Color table sourced from class definition or team color.Example Usage:
local color = lia.char.getTeamColor(ply)
lia.char.create(data, callback)
Create a new character row, build its object, and initialize inventories.
During character creation after validation to persist and ready the new character.
Parameters:
table data Prepared character data including steamID, faction, and name.function callback optional Invoked with the new character ID once creation finishes.
Example Usage:
lia.char.create(payload, function(charID) print("created", charID) end)
lia.char.restore(client, callback, id)
Load all characters for a player (or a specific ID) into memory and inventory.
On player connect or when an admin requests to restore a specific character.
Parameters:
Player client Player whose characters should be loaded.function callback optional Invoked with a list of loaded character IDs once complete.
number id optional Optional single character ID to restrict the load.
Example Usage:
lia.char.restore(ply, function(chars) print("loaded", #chars) end)
lia.char.cleanUpForPlayer(client)
Unload and save all characters cached for a player.
When a player disconnects or is cleaned up to free memory and inventories.
Parameters:
Player client Player whose cached characters should be unloaded.Example Usage:
lia.char.cleanUpForPlayer(ply)
lia.char.delete(id, client)
Delete a character, its data, and inventories, and notify affected players.
By admin or player actions that permanently remove a character.
Parameters:
number id Character database ID to delete.Player client optional Player requesting deletion, if any.
Example Usage:
lia.char.delete(charID, ply)
lia.char.getCharBanned(charID)
Check the ban state of a character in the database.
Before allowing a character to load or when displaying ban info.
Parameters:
number charID Character database ID.Returns:
number|nil Ban flag/value (0 if not banned), or nil on invalid input.Example Usage:
if lia.char.getCharBanned(id) ~= 0 then return end
lia.char.setCharDatabase(charID, field, value)
Write a character variable to the database and update any loaded instance.
Whenever persistent character fields or custom data need to be changed.
Parameters:
number charID Character database ID.string field Character var or custom data key.
any value Value to store; nil removes custom data entries.
Returns:
boolean True on success, false on immediate failure.Example Usage:
lia.char.setCharDatabase(charID, "money", newAmount)
lia.char.unloadCharacter(charID)
Save and unload a character from memory, clearing associated data vars.
When a character is no longer active or needs to be freed from cache.
Parameters:
number charID Character database ID to unload.Returns:
boolean True if a character was unloaded, false if none was loaded.Example Usage:
lia.char.unloadCharacter(charID)
lia.char.unloadUnusedCharacters(client, activeCharID)
Unload all cached characters for a player except the currently active one.
After character switches to reduce memory and inventory usage.
Parameters:
Player client Player whose cached characters should be reduced.number activeCharID Character ID to keep loaded.
Returns:
number Count of characters that were unloaded.Example Usage:
lia.char.unloadUnusedCharacters(ply, newCharID)
lia.char.loadSingleCharacter(charID, client, callback)
Load a single character from the database, building inventories and caching it.
When a specific character is selected, restored, or fetched server-side.
Parameters:
number charID Character database ID to load.Player client optional Owning player, used for permission checks and inventory linking.
function callback optional Invoked with the loaded character or nil on failure.
Example Usage:
lia.char.loadSingleCharacter(id, ply, function(char) if char then char:sync(ply) end end)