Character Library
This page covers utilities for manipulating character data.
Overview
The character library handles creation and persistence of player characters. It manages character variables, interacts with the database, and offers helpers for retrieving characters by ID or SteamID. Because these functions directly modify stored data, use them carefully or you may corrupt character information.
Description:
Creates a new character instance with default variables and metatable.
Parameters:
-
data (table) – Table of character variables.
-
id (number) – Character ID.
-
client (Player) – Player entity.
-
steamID (string) – SteamID64 string if client is not valid.
Realm:
- Shared
Returns:
- character (table) – New character object.
Example Usage:
-- This snippet demonstrates a common usage of lia.char.new
local char = lia.char.new({name = "John"}, 1, client)
lia.char.hookVar(varName, hookName, func)
Description:
Registers a hook function for when a character variable changes.
Parameters:
-
varName (string) – Variable name to hook.
-
hookName (string) – Unique hook identifier.
-
func (function) – Function to call on variable change.
Realm:
- Shared
Returns:
- None
Example Usage:
-- This snippet demonstrates a common usage of lia.char.hookVar
lia.char.hookVar("name", "PrintName", function(old, new) print(new) end)
lia.char.registerVar(key, data)
Description:
Registers a character variable with metadata and generates accessor methods.
Parameters:
-
key (string) – Variable key.
-
data (table) – Variable metadata including default, validation, networking, etc.
Realm:
- Shared
Returns:
- None
Example Usage:
-- This snippet demonstrates a common usage of lia.char.registerVar
lia.char.registerVar("age", {field = "_age", default = 20})
lia.char.getCharData(charID, key)
Description:
Retrieves character data JSON from the database as a Lua table.
Parameters:
-
charID (number|string) – Character ID.
-
key (string) – Specific data key to return (optional).
Realm:
- Shared
Returns:
- value (any) – Data value or full table if no key provided.
Example Usage:
-- This snippet demonstrates a common usage of lia.char.getCharData
local age = lia.char.getCharData(1, "age")
lia.char.getCharDataRaw(charID, key)
Description:
Retrieves raw character database row or specific column.
Parameters:
-
charID (number|string) – Character ID.
-
key (string) – Specific column name to return (optional).
Realm:
- Shared
Returns:
- row (table|any) – Full row table or column value.
Example Usage:
-- This snippet demonstrates a common usage of lia.char.getCharDataRaw
local row = lia.char.getCharDataRaw(1)
lia.char.getOwnerByID(ID)
Description:
Finds the player entity that owns the character with the given ID.
Parameters:
- ID (number|string) – Character ID.
Realm:
- Shared
Returns:
- Player – Player entity or nil if not found.
Example Usage:
-- This snippet demonstrates a common usage of lia.char.getOwnerByID
local ply = lia.char.getOwnerByID(1)
lia.char.getBySteamID(steamID)
Description:
Retrieves a character object by SteamID or SteamID64.
Parameters:
- steamID (string) – SteamID or SteamID64.
Realm:
- Shared
Returns:
- Character – Character object or nil.
Example Usage:
-- This snippet demonstrates a common usage of lia.char.getBySteamID
local char = lia.char.getBySteamID("STEAM_0:0:11101")
lia.char.getAll()
Description:
Returns a table mapping all players to their loaded character objects.
Parameters:
- None
Realm:
- Shared
Returns:
- table – Map of Player to Character.
Example Usage:
-- This snippet demonstrates a common usage of pairs
for ply, char in pairs(lia.char.getAll()) do print(ply, char:getName()) end
lia.char.GetTeamColor(client)
Description:
Determines the team color for a client based on their character class or default team.
Parameters:
- client (Player) – Player entity.
Realm:
- Shared
Returns:
- Color – Team or class color.
Example Usage:
-- This snippet demonstrates a common usage of lia.char.GetTeamColor
local color = lia.char.GetTeamColor(client)
lia.char.create(data, callback)
Description:
Inserts a new character into the database and sets up default inventory.
Parameters:
-
data (table) – Character creation data.
-
callback (function) – Callback receiving new character ID.
Realm:
- Server
Returns:
- None
Example Usage:
-- This snippet demonstrates a common usage of lia.char.create
lia.char.create({name = "John"}, function(id) print("Created", id) end)
lia.char.restore(client, callback, id)
Description:
Loads characters for a client from the database, optionally filtering by ID.
Parameters:
-
client (Player) – Player entity.
-
callback (function) – Callback receiving list of character IDs.
-
id (number) – Specific character ID to restore (optional).
Realm:
- Server
Returns:
- None
Example Usage:
lia.char.cleanUpForPlayer(client)
Description:
Cleans up loaded characters and inventories for a player on disconnect.
Parameters:
- client (Player) – Player entity.
Realm:
- Server
Returns:
- None
Example Usage:
-- This snippet demonstrates a common usage of lia.char.cleanUpForPlayer
lia.char.cleanUpForPlayer(client)
lia.char.delete(id, client)
Description:
Deletes a character by ID from the database, cleans up and notifies players.
Parameters:
-
id (number) – Character ID to delete.
-
client (Player) – Player entity reference.
Realm:
- Server
Returns:
- None
Example Usage:
lia.char.setCharData(charID, key, val)
Description:
Updates a character's JSON data field in the database and loaded object.
Parameters:
-
charID (number|string) – Character ID.
-
key (string) – Data key.
-
val (any) – New value.
Realm:
- Server
Returns:
- boolean – True on success, false on failure.
Example Usage:
-- This snippet demonstrates a common usage of lia.char.setCharData
lia.char.setCharData(1, "age", 25)
lia.char.setCharName(charID, name)
Description:
Updates the character's name in the database and loaded object.
Parameters:
-
charID (number|string) – Character ID.
-
name (string) – New character name.
Realm:
- Server
Returns:
- boolean – True on success, false on failure.
Example Usage:
-- This snippet demonstrates a common usage of lia.char.setCharName
lia.char.setCharName(1, "NewName")
lia.char.setCharModel(charID, model, bg)
Description:
Updates the character's model and bodygroups in the database and in-game.
Parameters:
-
charID (number|string) – Character ID.
-
model (string) – Model path.
-
bg (table) – Bodygroup table list.
Realm:
- Server
Returns:
- boolean – True on success, false on failure.
Example Usage: