Character
Character management system for the Lilia framework.
Overview
getID()
Purpose
Returns this character's unique numeric identifier.
When Called
Use when persisting, comparing, or networking character state.
Returns
number Character ID.
Example Usage
local id = char:getID()
getPlayer()
Purpose
Retrieves the player entity associated with this character.
When Called
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)
Purpose
Returns the name to show to a viewing client, honoring recognition rules.
When Called
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)
Purpose
Checks if the character has at least the given amount of money.
When Called
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)
Purpose
Determines whether the character possesses any flag in the string.
When Called
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)
Purpose
Gets the character's attribute value including any active boosts.
When Called
Use when calculating rolls or stats that depend on attributes.
Parameters
Returns
number Attribute level plus stacked boosts.
Example Usage
local strength = char:getAttrib("str", 0)
doesRecognize(id)
Purpose
Determines whether this character recognizes another character.
When Called
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)
Purpose
Checks if the character recognizes another under a fake name.
When Called
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)
Purpose
Stores custom data on the character and optionally replicates it.
When Called
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)
Purpose
Retrieves previously stored custom character data.
When Called
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()
Purpose
Reports whether the character is currently banned.
When Called
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)
Purpose
Marks another character as recognized, optionally storing a fake name.
When Called
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)
Purpose
Attempts to place the character into the specified class.
When Called
Use during class selection or forced reassignment.
Parameters
Returns
boolean True if the class change succeeded.
Example Usage
local ok = char:joinClass(newClassID)
addBoost(boostID, attribID, boostAmount)
Purpose
Adds a temporary boost to an attribute and propagates it.
When Called
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)
clearAllBoosts()
Purpose
Clears all attribute boosts and notifies listeners.
When Called
Use when resetting a character's temporary modifiers.
Returns
boolean Result from resetting the boost table.
Example Usage
char:clearAllBoosts()
setFlags(flags)
Purpose
Replaces the character's flag string and synchronizes it.
When Called
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)
Purpose
Adds one or more flags to the character if they are missing.
When Called
Use when granting new permissions or perks.
Parameters
string flags Concatenated flag characters to grant.
Example Usage
char:giveFlags("z")
takeFlags(flags)
Purpose
Removes specific flags from the character and triggers callbacks.
When Called
Use when revoking privileges or perks.
Parameters
string flags Concatenated flag characters to remove.
Example Usage
char:takeFlags("z")
save(callback)
Purpose
Persists the character's current variables to the database.
When Called
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)
Purpose
Sends character data to a specific player or all players.
When Called
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)
Purpose
Applies the character state to the owning player and optionally syncs.
When Called
Use right after a character is loaded or swapped in.
Parameters
boolean noNetworking Skip inventory and char networking when true.
Example Usage
char:setup()
ban(time)
Purpose
Bans the character for a duration or permanently and kicks them.
When Called
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)
giveMoney(amount)
Purpose
Adds money to the character through the owning player object.
When Called
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)
isMainCharacter()
Purpose
Checks whether this character matches the player's main character ID.
When Called
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