Character Meta
Character management system for the Lilia framework.
Overview
The character meta table provides comprehensive functionality for managing character data, attributes, and operations in the Lilia framework. It handles character creation, data persistence, attribute management, recognition systems, and character-specific operations. The meta table operates on both server and client sides, with the server managing character storage and validation while the client provides character data access and display. It includes integration with the database system for character persistence, inventory management for character items, and faction/class systems for character roles. The meta table ensures proper character data synchronization, attribute calculations with boosts, recognition between characters, and comprehensive character lifecycle management from creation to deletion.
getID()
Returns this character's unique numeric identifier.
Use when persisting, comparing, or networking character state.
Returns:
number Character ID.Example Usage:
local id = char:getID()
getPlayer()
Retrieves the player entity associated with this character.
Use whenever you need the live player controlling this character.
Returns:
Player|nil Player that owns the character, or nil if not found.Example Usage:
local ply = char:getPlayer()
getDisplayedName(client)
Returns the name to show to a viewing client, honoring recognition rules.
Use when rendering a character's name to another player.
Parameters:
Player client The viewer whose recognition determines the name.Returns:
string Display name or a localized "unknown" placeholder.Example Usage:
local name = targetChar:getDisplayedName(viewer)
hasMoney(amount)
Checks if the character has at least the given amount of money.
Use before charging a character to ensure they can afford a cost.
Parameters:
number amount The amount to verify.Returns:
boolean True if the character's balance is equal or higher.Example Usage:
if char:hasMoney(100) then purchase() end
hasFlags(flagStr)
Determines whether the character possesses any flag in the string.
Use when gating actions behind one or more privilege flags.
Parameters:
string flagStr One or more flag characters to test.Returns:
boolean True if at least one provided flag is present.Example Usage:
if char:hasFlags("ab") then grantAccess() end
getAttrib(key, default)
Gets the character's attribute value including any active boosts.
Use when calculating rolls or stats that depend on attributes.
Parameters:
string key Attribute identifier.number default Fallback value if the attribute is missing.
Returns:
number Attribute level plus stacked boosts.Example Usage:
local strength = char:getAttrib("str", 0)
doesRecognize(id)
Determines whether this character recognizes another character.
Use when deciding if a viewer should see a real name or remain unknown.
Parameters:
number|table id Character ID or object implementing getID.Returns:
boolean True if recognition is allowed by hooks.Example Usage:
if viewerChar:doesRecognize(targetChar) then showName() end
doesFakeRecognize(id)
Checks if the character recognizes another under a fake name.
Use when evaluating disguise or alias recognition logic.
Parameters:
number|table id Character ID or object implementing getID.Returns:
boolean True if fake recognition passes custom hooks.Example Usage:
local canFake = char:doesFakeRecognize(otherChar)
setData(k, v, noReplication, receiver)
Stores custom data on the character and optionally replicates it.
Use when adding persistent or networked character metadata.
Parameters:
string|table k Key to set or table of key/value pairs.any v Value to store when k is a string.
boolean noReplication Skip networking when true.
Player receiver optional Specific client to receive the update instead of owner.
Example Usage:
char:setData("lastLogin", os.time())
getData(key, default)
Retrieves previously stored custom character data.
Use when you need saved custom fields or default fallbacks.
Parameters:
string key optional Specific key to fetch or nil for the whole table.any default Value to return if the key is unset.
Returns:
any Stored value, default, or entire data table.Example Usage:
local note = char:getData("note", "")
isBanned()
Reports whether the character is currently banned.
Use when validating character selection or spawning.
Returns:
boolean True if banned permanently or until a future time.Example Usage:
if char:isBanned() then denyJoin() end
recognize(character, name)
Marks another character as recognized, optionally storing a fake name.
Invoke when a player learns or is assigned recognition of someone.
Parameters:
number|table character Target character ID or object implementing getID.string name optional Optional alias to remember instead of real recognition.
Returns:
boolean True after recognition is recorded.Example Usage:
char:recognize(otherChar)
joinClass(class, isForced)
Attempts to place the character into the specified class.
Use during class selection or forced reassignment.
Parameters:
number class Class ID to join.boolean isForced Skip eligibility checks when true.
Returns:
boolean True if the class change succeeded.Example Usage:
local ok = char:joinClass(newClassID)
kickClass()
Removes the character from its current class, falling back to default.
Use when a class is invalid, revoked, or explicitly left.
Example Usage:
char:kickClass()
updateAttrib(key, value)
Increases an attribute by the given amount, respecting maximums.
Use when awarding experience toward an attribute.
Parameters:
string key Attribute identifier.number value Amount to add.
Example Usage:
char:updateAttrib("stm", 5)
setAttrib(key, value)
Directly sets an attribute to a specific value and syncs it.
Use when loading characters or forcing an attribute level.
Parameters:
string key Attribute identifier.number value New attribute level.
Example Usage:
char:setAttrib("str", 15)
addBoost(boostID, attribID, boostAmount)
Adds a temporary boost to an attribute and propagates it.
Use when buffs or debuffs modify an attribute value.
Parameters:
string boostID Unique identifier for the boost source.string attribID Attribute being boosted.
number boostAmount Amount to add (can be negative).
Returns:
boolean Result from setVar update.Example Usage:
char:addBoost("stimpack", "end", 2)
removeBoost(boostID, attribID)
Removes a previously applied attribute boost.
Use when a buff expires or is cancelled.
Parameters:
string boostID Identifier of the boost source.string attribID Attribute to adjust.
Returns:
boolean Result from setVar update.Example Usage:
char:removeBoost("stimpack", "end")
clearAllBoosts()
Clears all attribute boosts and notifies listeners.
Use when resetting a character's temporary modifiers.
Returns:
boolean Result from resetting the boost table.Example Usage:
char:clearAllBoosts()
setFlags(flags)
Replaces the character's flag string and synchronizes it.
Use when setting privileges wholesale (e.g., admin changes).
Parameters:
string flags Complete set of flags to apply.Example Usage:
char:setFlags("abc")
giveFlags(flags)
Adds one or more flags to the character if they are missing.
Use when granting new permissions or perks.
Parameters:
string flags Concatenated flag characters to grant.Example Usage:
char:giveFlags("z")
takeFlags(flags)
Removes specific flags from the character and triggers callbacks.
Use when revoking privileges or perks.
Parameters:
string flags Concatenated flag characters to remove.Example Usage:
char:takeFlags("z")
save(callback)
Persists the character's current variables to the database.
Use during saves, character switches, or shutdown to keep data.
Parameters:
function callback optional Invoked after the save completes.Example Usage:
char:save(function() print("saved") end)
sync(receiver)
Sends character data to a specific player or all players.
Use after character creation, load, or when vars change.
Parameters:
Player receiver optional Target player to sync to; nil broadcasts to everyone.Example Usage:
char:sync(client)
setup(noNetworking)
Applies the character state to the owning player and optionally syncs.
Use right after a character is loaded or swapped in.
Parameters:
boolean noNetworking Skip inventory and char networking when true.Example Usage:
char:setup()
kick()
Forces the owning player off this character and cleans up state.
Use when removing access, kicking, or swapping characters.
Example Usage:
char:kick()
ban(time)
Bans the character for a duration or permanently and kicks them.
Use for disciplinary actions like permakill or timed bans.
Parameters:
number time optional Ban duration in seconds; nil makes it permanent.Example Usage:
char:ban(3600)
delete()
Deletes the character from persistent storage.
Use when a character is intentionally removed by the player or admin.
Example Usage:
char:delete()
destroy()
Removes the character from the active cache without DB interaction.
Use when unloading a character instance entirely.
Example Usage:
char:destroy()
giveMoney(amount)
Adds money to the character through the owning player object.
Use when rewarding or refunding currency.
Parameters:
number amount Amount to add (can be negative to deduct).Returns:
boolean False if no valid player exists; otherwise result of addMoney.Example Usage:
char:giveMoney(250)
takeMoney(amount)
Deducts money from the character and logs the transaction.
Use when charging a player for purchases or penalties.
Parameters:
number amount Amount to remove; the absolute value is used.Returns:
boolean True after the deduction process runs.Example Usage:
char:takeMoney(50)
isMainCharacter()
Checks whether this character matches the player's main character ID.
Use when showing main character indicators or restrictions.
Returns:
boolean True if this character is the player's main selection.Example Usage:
if char:isMainCharacter() then highlight() end