Character
Comprehensive character creation, management, and persistence system for the Lilia framework.
Overview
lia.char.getCharacter(charID, client, callback)
Purpose
Retrieve a character by ID from cache or request a load if missing.
When Called
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()
Purpose
Return a table of all players currently holding loaded characters.
When Called
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)
Purpose
Check if a character ID currently exists in the local cache.
When Called
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.removeCharacter(id)
Purpose
Remove a character from the local cache.
When Called
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)
Purpose
Construct a character object and populate its variables with provided data or defaults.
When Called
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)
Purpose
Register a hook function that runs when a specific character variable changes.
When Called
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)
Purpose
Register a character variable and generate accessor/mutator helpers with optional networking.
When Called
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)
Purpose
Read character data key/value pairs stored in the chardata table.
When Called
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)
Purpose
Retrieve raw character data from chardata without touching the cache.
When Called
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)
Purpose
Find the player entity that owns a given character ID.
When Called
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)
Purpose
Get the active character of an online player by SteamID/SteamID64.
When Called
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)
Purpose
Return the team/class color for a player, falling back to team color.
When Called
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)
Purpose
Create a new character row, build its object, and initialize inventories.
When Called
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)
Purpose
Load all characters for a player (or a specific ID) into memory and inventory.
When Called
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)
Purpose
Unload and save all characters cached for a player.
When Called
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)
Purpose
Delete a character, its data, and inventories, and notify affected players.
When Called
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)
Purpose
Check the ban state of a character in the database.
When Called
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)
Purpose
Write a character variable to the database and update any loaded instance.
When Called
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)
Purpose
Save and unload a character from memory, clearing associated data vars.
When Called
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)
Purpose
Unload all cached characters for a player except the currently active one.
When Called
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)
Purpose
Load a single character from the database, building inventories and caching it.
When Called
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)