Character¶
This page documents hooks in the character category.
AdjustCreationData(client, data, newData, originalData)View Source
Purpose
Allows modules to inject or override sanitized character creation values after validation but before the final character record is created.
Category
Character
Realm
Server
Parameters
Player client The player creating a new character.
table data The validated creation payload after unsupported character vars have been removed.
table newData A mutable table for additional values that will be merged into `data`.
table originalData A copy of the raw creation payload as it was originally received from the client before cleanup.
Example Usage
hook.Add("AdjustCreationData", "liaExampleAdjustCreationData", function(client, data, newData, originalData)
if originalData.name and originalData.name ~= "" then
newData.name = string.Trim(originalData.name)
end
end)
CanPlayerRespawn(client, timePassed, baseTime, lastDeath)View Source
Purpose
Allows modules to override or block a dead player's manual respawn request before the default spawn timer check runs.
Category
Character
Realm
Server
Parameters
Player client The dead player requesting a respawn.
number timePassed optional The number of seconds since the player's recorded death time, or nil when no death time was stored yet.
number baseTime The configured respawn delay after any `OverrideSpawnTime` adjustments.
number lastDeath optional The raw Unix timestamp stored in the player's `lastDeathTime` local var, if one exists.
Returns
boolean|nil Return false to block the respawn request. Return true to force an immediate respawn. Return nil to let the default timer-based logic continue.
Example Usage
hook.Add("CanPlayerRespawn", "liaExampleCanPlayerRespawn", function(client, timePassed, baseTime, lastDeath)
if client:getChar() and client:getChar():getData("permakilled") then return false end
if timePassed and timePassed >= math.max(baseTime, 10) then return true end
end)
CanPlayerUseChar(client, character)View Source
Purpose
Validates whether a player is allowed to load or switch to a specific character before setup begins.
Category
Character
Realm
Server
Parameters
Player client The player attempting to use the character.
Character character The character object that is about to be loaded for the player.
Returns
boolean|nil, string|nil Return false and an optional localized reason string to deny using the character. Return nil or true to allow loading to continue.
Example Usage
hook.Add("CanPlayerUseChar", "liaExampleCanPlayerUseChar", function(client, character)
if character:isBanned() then return false, L("permaKilledCharacter") end
if character:getFaction() == FACTION_STAFF and not client:hasPrivilege("createStaffCharacter") then
return false, L("invalidChar")
end
end)
CharDeleted(client, character)View Source
Purpose
Runs immediately before a player's owned character is deleted from memory and storage through the character deletion net message.
Category
Character
Realm
Server
Parameters
Player client The player requesting the deletion.
Character character The loaded character object that is about to be deleted.
Example Usage
hook.Add("CharDeleted", "liaExampleCharDeleted", function(client, character)
lia.log.add(client, "charDelete", character:getID())
end)
CharHasFlags(self, flags)View Source
Purpose
Allows plugins or modules to override player-side flag checks performed through `hasFlags`.
Category
Character
Realm
Shared
Parameters
Player self The player whose active character flags are being checked.
string flags The flag characters being queried.
Returns
boolean|nil Return true or false to override the flag check. Returning nil allows the default behavior to continue.
Example Usage
hook.Add("CharHasFlags", "liaExampleCharHasFlags", function(self, flags)
if self:isStaffOnDuty() and flags == "P" then
return true
end
end)
CharListLoaded(newCharList)View Source
Purpose
Runs the first time the client receives its available character ID list during a menu session.
Category
Character
Realm
Client
Parameters
table newCharList The newly received sequential array of character IDs available to the client.
Example Usage
hook.Add("CharListLoaded", "liaExampleCharListLoaded", function(newCharList)
print("[Characters] Loaded list size:", #newCharList)
end)
CharListUpdated(oldCharList, newCharList)View Source
Purpose
Runs after the client receives a replacement character ID list for an already initialized character menu session.
Category
Character
Realm
Client
Parameters
table oldCharList The previous array of character IDs stored clientside.
table newCharList The newly received array of character IDs.
Example Usage
hook.Add("CharListUpdated", "liaExampleCharListUpdated", function(oldCharList, newCharList)
print("[Characters] Updated list size:", #newCharList)
end)
CharPostSave(self)View Source
Purpose
Runs after a character's field-backed variables have been persisted to the database.
Category
Character
Realm
Server
Parameters
Character self The character that was saved.
Example Usage
hook.Add("CharPostSave", "liaExampleCharPostSave", function(self)
print("Saved character", self:getID())
end)
CharPreSave(character)View Source
Purpose
Runs before a character row is written to the database so modules can update transient state or cancel the save.
Category
Character
Realm
Server
Parameters
Character character The character that is about to be saved.
Returns
boolean|nil Return false to stop the character save. Returning nil allows the save to continue.
Example Usage
hook.Add("CharPreSave", "liaExampleCharPreSave", function(character)
if character:getData("savingLocked") then
return false
end
end)
GetBotModel(client, faction)View Source
Purpose
Allows plugins or modules to override the model used when the framework creates a bot character.
Category
Character
Realm
Server
Parameters
Player client The bot player being configured.
table faction The default faction selected for the bot.
Returns
string|nil Return a player model path to override the default bot model. Returning nil allows the default behavior to continue.
Example Usage
hook.Add("GetBotModel", "liaExampleGetBotModel", function(client, faction)
if faction and faction.uniqueID == "combine" then
return "models/player/police.mdl"
end
end)
GetModelGender(model)View Source
Purpose
Allows schemas or modules to override the gender classification used for model-dependent helpers such as voice and appearance checks.
Category
Character
Realm
Shared
Parameters
string model The model path being classified.
Returns
string|nil Return `female` or `male` to override the detected gender. Returning nil allows the default model-name checks to continue.
Example Usage
hook.Add("GetModelGender", "liaExampleGetModelGender", function(model)
if isstring(model) and model:find("custom_female", 1, true) then
return "female"
end
end)
GetRagdollTime(self, time)View Source
Purpose
Allows plugins or modules to override how long a player should stay ragdolled.
Category
Character
Realm
Server
Parameters
Returns
number|nil Return a numeric duration to override the ragdoll time. Returning nil allows the default behavior to continue.
Example Usage
hook.Add("GetRagdollTime", "liaExampleGetRagdollTime", function(self, time)
if self:Crouching() then
return time * 0.5
end
end)
OnCharAttribBoosted(client, self, attribID, boostID, boostAmount)View Source
Purpose
Runs after an attribute boost has been added, removed, or cleared.
Category
Character
Realm
Server
Parameters
Player client The player who owns the character, if valid.
Character self The character whose boost data changed.
string attribID The boosted attribute identifier.
string boostID The boost source identifier.
number|boolean boostAmount The applied boost amount, or `true` when a boost was removed.
Example Usage
hook.Add("OnCharAttribBoosted", "liaExampleOnCharAttribBoosted", function(client, self, attribID, boostID, boostAmount)
print("Boost changed:", attribID, boostID)
end)
OnCharAttribUpdated(client, self, key, value)View Source
Purpose
Runs after a character attribute has been updated and synced to the owning client.
Category
Character
Realm
Server
Parameters
Player client The player who owns the character.
Character self The character whose attribute changed.
string key The attribute identifier that changed.
number value The new attribute value.
Example Usage
hook.Add("OnCharAttribUpdated", "liaExampleOnCharAttribUpdated", function(client, self, key, value)
print("Attribute updated:", key, value)
end)
OnCharCreated(client, character, originalData)View Source
Purpose
Runs after a new character has been created, synced to its owner, and added to that player's character list, but before the character is set up as active.
Category
Character
Realm
Server
Parameters
Player client The player who created the character.
Character character The newly created character object.
table originalData The original character creation payload captured before validation and adjustment removed unsupported fields.
Example Usage
hook.Add("OnCharCreated", "liaExampleOnCharCreated", function(client, character, originalData)
if originalData.model then
lia.log.add(client, "charCreate", character:getName(), originalData.model)
end
end)
OnCharDisconnect(client, character)View Source
Purpose
Runs when a player disconnects while a character is loaded so spawn-related character state can be persisted.
Category
Character
Realm
Server
Parameters
Player client The disconnecting player.
Character character The character that was loaded for the player.
Example Usage
hook.Add("OnCharDisconnect", "liaExampleSpawnDisconnect", function(client, character)
print(character:getName())
end)
OnCharFallover(self, entity, state)View Source
Purpose
Runs when a player's character enters or leaves the ragdolled fallover state.
Category
Character
Realm
Server
Parameters
Player self The player whose character changed fallover state.
Entity entity The ragdoll entity involved in the state change.
boolean state True when the player entered fallover, false when they recovered.
Example Usage
hook.Add("OnCharFallover", "liaExampleOnCharFallover", function(self, entity, state)
print("Fallover state:", state)
end)
OnCharFlagsGiven(ply, self, addedFlags)View Source
Purpose
Runs after new flags have been granted to a character.
Category
Character
Realm
Server
Parameters
Player ply The player who owns the character.
Character self The character that received new flags.
string addedFlags The flag characters that were added.
Example Usage
hook.Add("OnCharFlagsGiven", "liaExampleOnCharFlagsGiven", function(ply, self, addedFlags)
print("Flags granted:", addedFlags)
end)
OnCharFlagsTaken(ply, self, removedFlags)View Source
Purpose
Runs after flags have been removed from a character.
Category
Character
Realm
Server
Parameters
Player ply The player who owns the character.
Character self The character that lost flags.
string removedFlags The flag characters that were removed.
Example Usage
hook.Add("OnCharFlagsTaken", "liaExampleOnCharFlagsTaken", function(ply, self, removedFlags)
print("Flags removed:", removedFlags)
end)
OnCharKick(self, client)View Source
OnCharNetVarChanged(character, key, oldVar, value)View Source
Purpose
Runs after a networked character variable has been updated on the client.
Category
Character
Realm
Client
Parameters
Character character The character whose networked variable changed.
string key The networked variable key that changed.
any oldVar The previous stored value.
any value The new networked value.
Example Usage
hook.Add("OnCharNetVarChanged", "liaExampleOnCharNetVarChanged", function(character, key, oldVar, value)
print("[Character] Net var changed:", key)
end)
OnCharPermakilled(self, time)View Source
Purpose
Runs after a character has been banned by `ban`, including permanent bans.
Category
Character
Realm
Server
Parameters
Character self The character that was banned.
number time optional The temporary ban duration passed to `ban`, or nil for a permanent ban.
Example Usage
hook.Add("OnCharPermakilled", "liaExampleOnCharPermakilled", function(self, time)
print("Character banned", self:getID(), time)
end)
OnPlayerSwitchClass(client, class, oldClass)View Source
Purpose
Runs after a character switches from one class to another through `joinClass`.
Category
Character
Realm
Server
Parameters
Player client The player whose character switched classes.
number|string class The new class identifier assigned to the character.
number|string oldClass The previous class identifier.
Example Usage
hook.Add("OnPlayerSwitchClass", "liaExampleOnPlayerSwitchClass", function(client, class, oldClass)
print(client:Nick(), oldClass, class)
end)
OverrideSpawnTime(ply, baseTime)View Source
Purpose
Allows modules to override the respawn delay value used by both the respawn HUD and the server-side respawn gate.
Category
Character
Realm
Shared
Parameters
Player ply The player whose respawn delay is being queried.
number baseTime The configured default respawn delay before overrides are applied.
Returns
number|nil Return a number to replace the respawn delay. Return nil to keep the configured default.
Example Usage
hook.Add("OverrideSpawnTime", "liaExampleOverrideSpawnTime", function(ply, baseTime)
if ply:hasPrivilege("noDeathCooldown") then return 0 end
return baseTime
end)
PlayerLiliaDataLoaded(client)View Source
Purpose
Runs after a player's stored Lilia data finishes loading so modules can continue initialization work that depends on that data.
Category
Character
Realm
Server
Parameters
Player client The player whose Lilia data has just finished loading.
Example Usage
hook.Add("PlayerLiliaDataLoaded", "liaExamplePlayerLiliaDataLoaded", function(client)
if IsValid(client) then
print("Loaded Lilia data for", client:Nick())
end
end)
PlayerLoadedChar(client, character, currentChar)View Source
Purpose
Runs after the new character has been set up so modules can apply loadout, inventory, stamina, class, and other post-load state.
Category
Character
Realm
Server
Parameters
Player client The player who just loaded the character.
Character character The character that has just been set up as active.
Character currentChar optional The player's previous active character before the load occurred, if one existed.
Example Usage
hook.Add("PlayerLoadedChar", "liaExamplePlayerLoadedChar", function(client, character, currentChar)
if currentChar and currentChar:getID() ~= character:getID() then
lia.log.add(client, "charLoad", character:getName(), character:getID())
end
end)
PlayerModelChanged(client, newVar)View Source
Purpose
Runs when a character's `model` var changes so modules can react to the player receiving a new model path.
Category
Character
Realm
Shared
Parameters
Player client The player whose character model changed.
string newVar The new model path assigned to the character.
Example Usage
hook.Add("PlayerModelChanged", "liaExamplePlayerModelChanged", function(client, newVar)
if IsValid(client) then
print(client:Nick(), "changed model to", newVar)
end
end)
PlayerShouldPermaKill(client, inflictor, attacker)View Source
Purpose
Determines whether a player death caused by another player should permanently kill the victim's character.
Category
Character
Realm
Server
Parameters
Player client The player who died.
Entity inflictor The inflictor responsible for the death.
Entity attacker The attacker responsible for the death.
Returns
boolean|nil Return true to permanently kill the victim's character. Returning nil or false allows the default death flow to continue without a perma-kill.
Example Usage
hook.Add("PlayerShouldPermaKill", "liaExamplePlayerShouldPermaKill", function(client, inflictor, attacker)
if IsValid(attacker) and attacker:IsPlayer() and attacker:isStaffOnDuty() then
return true
end
end)
PostBotSetup(client, character, inventory)View Source
Purpose
Runs after a bot player, character, and inventory have been created and spawned.
Category
Character
Realm
Server
Parameters
Player client The bot player that was configured.
Character character The newly created bot character.
Inventory inventory The bot's newly created inventory instance.
Example Usage
hook.Add("PostBotSetup", "liaExamplePostBotSetup", function(client, character, inventory)
character:giveMoney(500)
end)
PostPlayerInitialSpawn(client)View Source
Purpose
Runs after a player initially spawns so PAC part state can be synchronized to that client.
Category
Character
Realm
Server
Parameters
Player client The player whose PAC part state is being synchronized.
Example Usage
hook.Add("PostPlayerInitialSpawn", "liaExamplePostPlayerInitialSpawnPAC", function(client)
if client:hasPrivilege("canUsePAC3") then
client:ChatPrint("PAC sync queued")
end
end)
PostPlayerLoadedChar(client, character, currentChar)View Source
Purpose
Runs after the character load response has been sent and the main character setup hooks have finished.
Category
Character
Realm
Server
Parameters
Player client The player who just loaded the character.
Character character The character that is now active.
Character currentChar optional The player's previous active character before the load occurred, if one existed.
Example Usage
hook.Add("PostPlayerLoadedChar", "liaExamplePostPlayerLoadedChar", function(client, character, currentChar)
if currentChar and currentChar:getID() ~= character:getID() then
client:notifySuccessLocalized("charLoaded", character:getName())
end
end)
PostPlayerLoadout(client)View Source
Purpose
Runs after a player's loadout finishes so modules can perform final setup work.
Category
Character
Realm
Server
Parameters
Player client The player whose loadout just finished.
Example Usage
hook.Add("PostPlayerLoadout", "liaExampleCorePostLoadout", function(client)
print(client:Nick())
end)
PrePlayerLoadedChar(client)View Source
Purpose
Runs immediately before the player's bodygroups, skin, and movement state are reset for character loading.
Category
Character
Realm
Server
Parameters
Player client The player who is about to load a character.
Example Usage
hook.Add("PrePlayerLoadedChar", "liaExamplePrePlayerLoadedChar", function(client)
client:SetDSP(1, false)
end)
SetupBotPlayer(client)View Source
Purpose
Runs when a bot joins so modules can replace or extend the default bot character setup flow.
Category
Character
Realm
Server
Parameters
Player client The bot player that is being initialized.
Example Usage
hook.Add("SetupBotPlayer", "liaExampleSetupBotPlayer", function(client)
print("Preparing bot:", client:Nick())
end)
ShouldSpawnClientRagdoll(client)View Source
Purpose
Determines whether a player death should create the default client ragdoll.
Category
Character
Realm
Server
Parameters
Player client The player who has just died.
Returns
boolean|nil Return false to block ragdoll creation. Returning nil allows the default behavior to continue.
Example Usage
hook.Add("ShouldSpawnClientRagdoll", "liaExampleShouldSpawnClientRagdoll", function(client)
if client:isStaffOnDuty() then
return false
end
end)