Player¶
Player metadata helpers for character access, notifications, requests, progression, persistence, and ragdoll state.
Overview
getChar()View Source
Purpose
Returns the currently loaded character attached to this player.
Realm
Shared
Returns
Character|nil The active character object when one is loaded.
Example Usage
local character = client:getChar()
if character then print(character:getName()) end
tostring()View Source
Purpose
Produces a string representation of the player using the active character name when available.
Realm
Shared
Returns
string The character name or the Steam display name.
Example Usage
print(client:tostring())
Name()View Source
Purpose
Overrides the player name lookup to prefer the active character name.
Realm
Shared
Returns
string The character name or the original Steam name fallback.
Example Usage
print(client:Name())
doGesture(a, b, c)View Source
Purpose
Restarts a player gesture locally and syncs it to nearby players.
Realm
Shared
Parameters
number a The gesture slot.
number b The animation activity or gesture ID.
boolean|number c optional Optional autokill or blend argument passed to the engine call.
Example Usage
client:doGesture(GESTURE_SLOT_ATTACK_AND_RELOAD, ACT_GMOD_GESTURE_WAVE, true)
setAction(text, time, callback)View Source
Purpose
Starts, updates, or clears the action bar for this player and optionally runs a callback when it completes.
Realm
Shared
Parameters
string text optional The label to display, or `nil` to clear the action.
number time optional The duration in seconds.
function callback optional Runs when the timer completes successfully.
Example Usage
client:setAction("Searching crate", 4, function(ply)
ply:notify("Search complete.")
end)
doStaredAction(entity, callback, time, onCancel, distance)View Source
Purpose
Requires the player to keep looking at an entity for a duration before a callback fires.
Realm
Shared
Parameters
Entity entity The entity the player must keep tracing.
function callback optional Runs when the stare completes.
number time The total stare time in seconds.
function onCancel optional Runs if the action is interrupted.
number distance optional Optional trace distance override.
Example Usage
client:doStaredAction(door, function()
client:notify("Unlocked.")
end, 3)
stopAction()View Source
hasPrivilege(privilegeName)View Source
Purpose
Checks whether the player has access to a named administrative privilege.
Realm
Shared
Parameters
string privilegeName The privilege identifier to test.
Returns
boolean `true` when the player has access.
Example Usage
if client:hasPrivilege("canEditVendors") then
print("Vendor editing allowed.")
end
removeRagdoll()View Source
getItemWeapon()View Source
Purpose
Resolves the equipped inventory item that matches the player's active weapon.
Realm
Shared
Returns
Weapon|nil The active weapon entity when it maps to an equipped item. Item|nil The matching inventory item.
Example Usage
local weapon, item = client:getItemWeapon()
if item then print(item.uniqueID) end
getItemDropPos()View Source
Purpose
Calculates a nearby valid world position for dropping an item in front of the player.
Realm
Shared
Returns
Vector The traced drop position.
Example Usage
local dropPos = client:getItemDropPos()
getItems()View Source
Purpose
Returns the item table for the player's active character inventory.
Realm
Shared
Returns
table|nil A table of inventory items when the character and inventory exist.
Example Usage
local items = client:getItems() or {}
print(#items)
getTracedEntity(distance)View Source
notify(message, notifType)View Source
notifyLocalized(message, notifType)View Source
notifyError(message)View Source
Purpose
Sends an error notification.
Realm
Shared
Parameters
string message The error text.
Example Usage
client:notifyError("You cannot do that.")
notifyWarning(message)View Source
Purpose
Sends a warning notification.
Realm
Shared
Parameters
string message The warning text.
Example Usage
client:notifyWarning("You are over-encumbered.")
notifyInfo(message)View Source
Purpose
Sends an informational notification.
Realm
Shared
Parameters
string message The info text.
Example Usage
client:notifyInfo("Waypoint updated.")
notifySuccess(message)View Source
Purpose
Sends a success notification.
Realm
Shared
Parameters
string message The success text.
Example Usage
client:notifySuccess("Craft complete.")
notifyMoney(message)View Source
Purpose
Sends a money-themed notification.
Realm
Shared
Parameters
string message The money notice text.
Example Usage
client:notifyMoney("+250 tokens")
notifyAdmin(message)View Source
Purpose
Sends an admin-themed notification.
Realm
Shared
Parameters
string message The admin notice text.
Example Usage
client:notifyAdmin("Staff mode enabled.")
notifyErrorLocalized(key)View Source
Purpose
Sends a localized error notification.
Realm
Shared
Parameters
string key The localization token.
Example Usage
client:notifyErrorLocalized("notEnoughMoney")
notifyWarningLocalized(key)View Source
Purpose
Sends a localized warning notification.
Realm
Shared
Parameters
string key The localization token.
Example Usage
client:notifyWarningLocalized("storageNotLocked")
notifyInfoLocalized(key)View Source
Purpose
Sends a localized informational notification.
Realm
Shared
Parameters
string key The localization token.
Example Usage
client:notifyInfoLocalized("questUpdate")
notifySuccessLocalized(key)View Source
Purpose
Sends a localized success notification.
Realm
Shared
Parameters
string key The localization token.
Example Usage
client:notifySuccessLocalized("npcCustomizedSuccessfully")
notifyMoneyLocalized(key)View Source
Purpose
Sends a localized money notification.
Realm
Shared
Parameters
string key The localization token.
Example Usage
client:notifyMoneyLocalized("salary", "250", "salary")
notifyAdminLocalized(key)View Source
Purpose
Sends a localized admin notification.
Realm
Shared
Parameters
string key The localization token.
Example Usage
client:notifyAdminLocalized("groupPermissionsUpdated")
canEditVendor(vendor)View Source
isStaff()View Source
Purpose
Checks whether the player's admin group is classified as staff.
Realm
Shared
Returns
boolean `true` when the user's group inherits the `Staff` type.
Example Usage
if client:isStaff() then print("Staff account.") end
isStaffOnDuty()View Source
Purpose
Checks whether the player is currently on the staff faction.
Realm
Shared
Returns
boolean `true` when the player's team matches `FACTION_STAFF`.
Example Usage
if client:isStaffOnDuty() then print("On-duty staff.") end
hasWhitelist(faction)View Source
Purpose
Checks whether the player has access to a faction whitelist.
Realm
Shared
Parameters
number faction The faction index to test.
Returns
boolean `true` when the faction is default or whitelisted for this schema.
Example Usage
if client:hasWhitelist(FACTION_CWU) then
print("Whitelist available.")
end
getClassData()View Source
Purpose
Returns the class definition for the player's active character.
Realm
Shared
Returns
table|nil The class data table when a class is assigned.
Example Usage
local classData = client:getClassData()
if classData then print(classData.name) end
getDarkRPVar(var)View Source
Purpose
Provides DarkRP compatibility for retrieving player money.
Realm
Shared
Parameters
string var The DarkRP var name to query.
Returns
number|nil The player's money for the `"money"` key.
Example Usage
local money = client:getDarkRPVar("money")
getMoney()View Source
Purpose
Returns the current money value from the player's active character.
Realm
Shared
Returns
number The character's money, or `0` if no character is loaded.
Example Usage
print(client:getMoney())
canAfford(amount)View Source
Purpose
Checks whether the player can afford a given amount.
Realm
Shared
Parameters
number amount The amount to compare against the player's money.
Returns
boolean|nil `true` when the character has enough money.
Example Usage
if client:canAfford(100) then
print("Purchase allowed.")
end
hasSkillLevel(skill, level)View Source
Purpose
Checks whether the active character meets a minimum level for one skill.
Realm
Shared
Parameters
Returns
boolean `true` when the character's effective attribute meets the threshold.
Example Usage
if client:hasSkillLevel("stm", 10) then
print("Stamina requirement met.")
end
meetsRequiredSkills(requiredSkillLevels)View Source
Purpose
Checks whether the active character satisfies every required skill threshold in a table.
Realm
Shared
Parameters
table requiredSkillLevels optional A map of skill IDs to minimum levels.
Returns
boolean `true` when all requirements are satisfied or no requirements were supplied.
Example Usage
if client:meetsRequiredSkills({str = 5, stm = 10}) then
print("All skill requirements met.")
end
getFlags()View Source
Purpose
Returns the active character's flags.
Realm
Shared
Returns
string The character flag string, or an empty string.
Example Usage
print(client:getFlags())
giveFlags(flags)View Source
Purpose
Grants flags to the active character.
Realm
Shared
Parameters
string flags The flags to add.
Example Usage
client:giveFlags("ab")
takeFlags(flags)View Source
Purpose
Removes flags from the active character.
Realm
Shared
Parameters
string flags The flags to remove.
Example Usage
client:takeFlags("b")
networkAnimation(active, boneData)View Source
Purpose
Broadcasts or applies procedural bone animation state for the player.
Realm
Shared
Parameters
boolean active Whether the animation should be applied or cleared.
table boneData A map of bone names to target angles.
Example Usage
client:networkAnimation(true, {
["ValveBiped.Bip01_Head1"] = Angle(10, 0, 0)
})
getAllLiliaData()View Source
Purpose
Returns the full Lilia profile data table for this player on the current realm.
Realm
Shared
Returns
table The server-side `liaData` table or the client-side `lia.localData` cache.
Example Usage
local allData = client:getAllLiliaData()
setWaypoint(name, vector, logo, onReach)View Source
Purpose
Sets a waypoint for the player or renders one locally until it is reached.
Realm
Shared
Parameters
string name The waypoint label.
Vector vector The world position to target.
string logo optional Optional material path for the waypoint icon.
function onReach optional Optional callback fired when the waypoint is cleared locally.
Example Usage
client:setWaypoint("Safehouse", Vector(0, 0, 0), "materials/icon16/house.png")
getLiliaData(key, default)View Source
Purpose
Returns one stored Lilia data value with a fallback default.
Realm
Shared
Parameters
Returns
any The stored value or the provided default.
Example Usage
local whitelists = client:getLiliaData("whitelists", {})
getMainCharacter()View Source
Purpose
Returns the player's configured main character ID.
Realm
Shared
Returns
number|nil The main character ID, if one has been set.
Example Usage
local mainCharID = client:getMainCharacter()
setMainCharacter(charID)View Source
Purpose
Sets or clears the player's main character, enforcing cooldowns and ownership checks on the server.
Realm
Shared
Parameters
number charID optional The character ID to set as main, or `nil`/`0` to clear it.
Returns
boolean|nil On the server, `true` for success or `false` on failure. string|nil An optional localized error message when blocked by cooldowns.
Example Usage
local success, err = client:setMainCharacter(12)
hasFlags(flags)View Source
Purpose
Checks whether the active character owns any of the requested flags.
Realm
Shared
Parameters
string flags One or more flag characters to test.
Returns
boolean `true` when any requested flag exists or a hook grants access.
Example Usage
if client:hasFlags("pet") then
print("Flag requirement met.")
end
playTimeGreaterThan(time)View Source
requestOptions(title, subTitle, options, limit, callback, onCancel, Client, Client)View Source
Purpose
Opens a list selection request for the player, or a local Derma dialog on the client.
Realm
Shared
Parameters
string|table title The request title.
string|table subTitle Supporting description text.
table options optional The selectable option list.
number limit optional Maximum number of allowed selections.
function callback optional Runs with the selected result.
function onCancel optional Client-side cancel callback.
unknown Client side cancel callback.
unknown Client side cancel callback.
Example Usage
client:requestOptions("Choose Loadout", "Select one option.", {"Rifle", "SMG"}, 1, function(result)
PrintTable(result)
end)
requestString(title, subTitle, callback, default)View Source
Purpose
Requests a string input from the player and optionally returns a deferred promise-like object.
Realm
Shared
Parameters
string|table title The request title.
string|table subTitle The prompt text.
function|string callback optional The completion callback, or the default value when omitted.
string default optional The initial input value.
Returns
Deferred|nil A deferred handle when no callback function is supplied.
Example Usage
client:requestString("Callsign", "Enter a callsign.", function(value)
print(value)
end)
requestArguments(title, argTypes, callback)View Source
Purpose
Requests typed argument input from the player and optionally returns a deferred handle.
Realm
Shared
Parameters
string|table title The request title.
table argTypes Argument specification data.
function callback optional Runs with the submitted values.
Returns
Deferred|nil A deferred handle when no callback function is supplied.
Example Usage
client:requestArguments("Create Item", {
{"name", "string"},
{"amount", "number"}
}, function(values)
PrintTable(values)
end)
requestBinaryQuestion(question, option1, option2, manualDismiss, callback)View Source
Purpose
Prompts the player with a two-option confirmation dialog.
Realm
Shared
Parameters
string|table question The prompt text or title, depending on the call form.
string|table option1 The first option label or shifted question text.
string|table option2 The second option label or shifted first option label.
boolean|string|function manualDismiss optional Whether dismissal is manual, or shifted arguments for the alternate call form.
function callback optional Runs with the chosen response.
Example Usage
client:requestBinaryQuestion("Delete item?", "Yes", "No", false, function(result)
print(result)
end)
requestPopupQuestion(question, buttons)View Source
Purpose
Shows a popup question with a custom button list.
Realm
Shared
Parameters
string|table question The prompt text.
table buttons Button definitions or labels.
Example Usage
client:requestPopupQuestion("Select a stance", {
{"Aggressive", function() print("Aggressive") end},
{"Defensive", function() print("Defensive") end}
})
getRagdoll()View Source
Purpose
Resolves the player's ragdoll entity from netvars, engine state, or client-side fallbacks.
Realm
Shared
Returns
Entity|nil The ragdoll entity when found.
Example Usage
local ragdoll = client:getRagdoll()
requestButtons(title, buttons)View Source
Purpose
Displays a button-based request to the player.
Realm
Shared
Parameters
string|table title The request title.
table buttons Button definitions containing text and callbacks.
Example Usage
client:requestButtons("Choose Option", {
{text = "Accept", callback = function() print("Accepted") end},
{text = "Decline", callback = function() print("Declined") end}
})
isStuck()View Source
Purpose
Checks whether the player is currently stuck in solid space.
Realm
Shared
Returns
boolean `true` when the player's hull starts inside solid geometry.
Example Usage
if client:isStuck() then print("Player is stuck.") end
requestDropdown(title, subTitle, options, callback)View Source
Purpose
Shows a dropdown request to the player.
Realm
Shared
Parameters
string|table title The request title.
string|table subTitle Supporting prompt text.
table options optional Allowed dropdown options.
function callback optional Runs with the selected result.
Example Usage
client:requestDropdown("Faction", "Choose a faction.", {"Citizen", "Worker"}, function(choice)
print(choice)
end)
restoreStamina(amount)View Source
Purpose
Restores stamina up to the character's maximum and clears the breathing flag when recovery is sufficient.
Realm
Server
Parameters
number amount The amount of stamina to restore.
Example Usage
client:restoreStamina(15)
consumeStamina(amount)View Source
Purpose
Reduces stamina and marks the player as out of breath when it reaches zero.
Realm
Server
Parameters
number amount The amount of stamina to consume.
Example Usage
client:consumeStamina(10)
addMoney(amount)View Source
takeMoney(amount)View Source
Purpose
Removes money from the active character.
Realm
Server
Parameters
number amount The amount to remove.
Example Usage
client:takeMoney(100)
loadLiliaData(callback)View Source
Purpose
Loads persistent Lilia player data from the database or creates a fresh row when none exists.
Realm
Server
Parameters
function callback optional Runs after the data table has been loaded or initialized.
Example Usage
client:loadLiliaData(function(data)
PrintTable(data)
end)
saveLiliaData()View Source
setLiliaData(key, value, noNetworking, noSave)View Source
Purpose
Stores one Lilia profile value, optionally syncing it and optionally saving immediately.
Realm
Server
Parameters
string key The data key to write.
any value The value to store.
boolean noNetworking optional Whether to skip sending the updated value to the player.
boolean noSave optional Whether to skip immediate persistence.
Example Usage
client:setLiliaData("title", "Quartermaster")
banPlayer(reason, duration, banner)View Source
Purpose
Records a ban entry in the database and kicks the player with the localized ban message.
Realm
Server
Parameters
string reason optional The ban reason.
number duration optional The duration value used by the localized message.
Player banner optional The staff member issuing the ban.
Example Usage
client:banPlayer("Mass RDM", 1440, admin)
getPlayTime()View Source
Purpose
Returns the player's total playtime, honoring hook overrides and active session time.
Realm
Server
Returns
number The total playtime in seconds.
Example Usage
print(client:getPlayTime())
createRagdoll(freeze)View Source
setRagdolled(state, time, getUpGrace)View Source
Purpose
Toggles the player's ragdolled state, including weapon storage, movement locking, and timed recovery handling.
Realm
Server
Parameters
boolean state Whether to ragdoll or restore the player.
number time optional Optional duration before automatic recovery.
number getUpGrace optional Optional grace period before the player may stand up again.
Example Usage
client:setRagdolled(true, 10)
syncVars()View Source
setNetVar(key, value)View Source
setLocalVar(key, value)View Source
getLocalVar(key, default)View Source
getLocalVar(key, default)View Source
Purpose
Returns a client-side local netvar cache entry with a fallback default.
Realm
Client
Parameters
Returns
any The cached local value or the default.
Example Usage
local blurAmount = LocalPlayer():getLocalVar("blur", 0)
getPlayTime()View Source
Purpose
Returns the player's total playtime on the client using replicated character and session data.
Realm
Client
Returns
number The total playtime in seconds.
Example Usage
print(LocalPlayer():getPlayTime())