Player Meta
Lilia extends Garry's Mod players with characters, inventories, and permission checks.
This reference details the meta functions enabling that integration.
Overview
Player-meta functions provide quick access to the active character, networking helpers for messaging or data transfer, and utility checks such as admin status.
Players are entity objects that hold at most one Character
instance, so these helpers unify player-related logic across the framework.
getChar
Purpose
Returns the currently loaded character object for this player.
Parameters
- None
Realm
Shared
Returns
Character|nil
: The player's active character.
Example Usage
Name
Purpose
Returns either the character's role-play name or the player's Steam name.
Parameters
- None
Realm
Shared
Returns
string
: Display name.
Example Usage
steamName
Purpose
Returns the player's Steam name without considering character data.
Parameters
- None
Realm
Shared
Returns
string
: Steam community display name.
Example Usage
SteamName
Purpose
Alias of steamName
.
Parameters
- None
Realm
Shared
Returns
string
: Steam community display name.
Example Usage
GetCharacter
Purpose
Alias of getChar
.
Parameters
- None
Realm
Shared
Returns
Character|nil
: The player's active character.
Example Usage
Nick
Purpose
Alias of Name
.
Parameters
- None
Realm
Shared
Returns
string
: Display name.
Example Usage
GetName
Purpose
Alias of Name
.
Parameters
- None
Realm
Shared
Returns
string
: Display name.
Example Usage
hasPrivilege
Purpose
Wrapper for CAMI privilege checks.
Parameters
privilegeName
(string
): Privilege identifier.
Realm
Shared
Returns
boolean
: Result fromCAMI.PlayerHasAccess
.
Example Usage
-- Deny access if the player lacks a privilege
if not player:hasPrivilege("Manage") then
return false
end
getCurrentVehicle
Purpose
Safely returns the vehicle the player is currently using.
Parameters
- None
Realm
Shared
Returns
Entity|nil
: Vehicle entity ornil
.
Example Usage
-- Attach a camera to the vehicle the player is in
local veh = player:getCurrentVehicle()
if IsValid(veh) then
AttachCamera(veh)
end
hasValidVehicle
Purpose
Determines if the player is currently inside a valid vehicle.
Parameters
- None
Realm
Shared
Returns
boolean
:true
if a vehicle entity is valid.
Example Usage
-- Allow honking only when in a valid vehicle
if player:hasValidVehicle() then
player:GetVehicle():EmitSound("Horn")
end
isNoClipping
Purpose
Returns true
if the player is in noclip mode and not inside a vehicle.
Parameters
- None
Realm
Shared
Returns
boolean
: Whether the player is noclipping.
Example Usage
hasRagdoll
Purpose
Checks if the player currently has an active ragdoll entity.
Parameters
- None
Realm
Shared
Returns
boolean
:true
when a ragdoll entity exists.
Example Usage
CanOverrideView
Purpose
Checks if the player is allowed to override the camera view.
A valid character must be loaded and the player cannot be in a vehicle or ragdoll.
The thirdPersonEnabled
option must be enabled both client and server side and the ShouldDisableThirdperson
hook must not return true
.
Parameters
- None
Realm
Client
Returns
boolean
:true
when a third-person view may be used.
Example Usage
IsInThirdPerson
Purpose
Returns whether third-person view is enabled for this player according to the thirdPersonEnabled
option and configuration.
Parameters
- None
Realm
Client
Returns
boolean
:true
if third-person mode is enabled.
Example Usage
removeRagdoll
Purpose
Safely removes the player's ragdoll entity if present.
Parameters
- None
Realm
Shared
Returns
nil
: This function does not return a value.
Example Usage
getRagdoll
Purpose
Retrieves the ragdoll entity associated with the player.
Parameters
- None
Realm
Shared
Returns
Entity|nil
: The ragdoll entity ornil
.
Example Usage
isStuck
Purpose
Determines whether the player's position is stuck in the world.
Parameters
- None
Realm
Shared
Returns
boolean
:true
if the trace detects a stuck state.
Example Usage
isNearPlayer
Purpose
Checks if an entity is within the given radius of the player.
Parameters
-
radius
(number
): Distance in units. -
entity
(Entity
): Entity to compare.
Realm
Shared
Returns
boolean
:true
if the entity is close enough.
Example Usage
entitiesNearPlayer
Purpose
Returns a table of entities within radius of the player.
Parameters
-
radius
(number
): Search distance in units. -
playerOnly
(boolean|nil
): Only include players whentrue
.
Realm
Shared
Returns
table
: List of nearby entities.
Example Usage
for _, ent in ipairs(player:entitiesNearPlayer(256)) do
if ent:IsPlayer() then
ent:ChatPrint("Someone is close to you!")
else
DebugDrawBox(ent:GetPos(), ent:OBBMins(), ent:OBBMaxs(), 0, 255, 0, 0, 5)
end
end
getItemWeapon
Purpose
Returns the active weapon entity and associated item if equipped.
Parameters
- None
Realm
Shared
Returns
-
Entity|nil
: Weapon entity when matched. -
Item|nil
: Inventory item associated with the weapon.
Example Usage
isRunning
Purpose
Checks whether the player is moving faster than walking speed.
Parameters
- None
Realm
Shared
Returns
boolean
:true
if the player is running.
Example Usage
isFemale
Purpose
Returns true
if the player's model is considered female.
Parameters
- None
Realm
Shared
Returns
boolean
: Whether a female model is detected.
Example Usage
IsFamilySharedAccount
Purpose
Checks if the player is using a Steam Family Share account.
Parameters
- None
Realm
Shared
Returns
boolean
:true
when the account is shared.
Example Usage
getItemDropPos
Purpose
Finds a safe position in front of the player to drop items.
Parameters
- None
Realm
Shared
Returns
Vector
: World position for dropping items.
Example Usage
getItems
Purpose
Returns the player's inventory item list if a character is loaded.
Parameters
- None
Realm
Shared
Returns
table|nil
: Table of items ornil
if absent.
Example Usage
-- Iterate player's items to calculate total weight
local total = 0
for _, it in pairs(player:getItems() or {}) do
total = total + it.weight
end
getTracedEntity
Purpose
Performs a simple trace from the player's shoot position.
Parameters
distance
(number|nil
): Trace length in units. Default is96
.
Realm
Shared
Returns
Entity|nil
: The entity hit ornil
.
Example Usage
getTrace
Purpose
Returns a hull trace in front of the player.
Parameters
distance
(number|nil
): Hull length in units. Default is200
.
Realm
Shared
Returns
table
: Trace result.
Example Usage
getEyeEnt
Purpose
Returns the entity the player is looking at within a distance.
Parameters
distance
(number|nil
): Maximum distance. Default is150
.
Realm
Shared
Returns
Entity|nil
: The entity ornil
if too far.
Example Usage
-- Show the name of the object being looked at
local target = player:getEyeEnt(128)
if IsValid(target) then
player:ChatPrint(string.format("Class: %s", target:GetClass()))
end
notify
Purpose
Sends a plain notification message to the player.
Parameters
message
(string
): Text to display.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
-- Send a welcome notification and log the join event
player:notify("Welcome to the server!")
file.Append("welcome.txt", player:SteamID() .. " joined\n")
notifyLocalized
Purpose
Sends a localized notification to the player.
Parameters
-
message
(string
): Translation key. -
...
: Additional parameters for localization.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
-- Send a localized message including the player's name and score
local score = player:GetFrags()
player:notifyLocalized("greeting_key", player:Name(), score)
CanEditVendor
Purpose
Determines whether the player can edit the given vendor.
Parameters
vendor
(Entity
): Vendor entity to check.
Realm
Server
Returns
boolean
:true
if allowed to edit.
Example Usage
isUser
Purpose
Convenience wrapper to check if the player is in the "user"
group.
Parameters
- None
Realm
Shared
Returns
boolean
: Whether usergroup is"user"
.
Example Usage
isStaff
Purpose
Returns true
if the player belongs to a staff group.
Parameters
- None
Realm
Shared
Returns
boolean
: Result from the privilege check.
Example Usage
isVIP
Purpose
Checks whether the player is in the VIP group.
Parameters
- None
Realm
Shared
Returns
boolean
: Result from privilege check.
Example Usage
isStaffOnDuty
Purpose
Determines if the player is currently in the staff faction.
Parameters
- None
Realm
Shared
Returns
boolean
:true
if staff faction is active.
Example Usage
isFaction
Purpose
Checks if the player's character belongs to the given faction.
Parameters
faction
(number
): Faction index to compare.
Realm
Shared
Returns
boolean
:true
if the factions match.
Example Usage
isClass
Purpose
Returns true
if the player's character is of the given class.
Parameters
class
(number
): Class index to compare.
Realm
Shared
Returns
boolean
: Whether the character matches the class.
Example Usage
hasWhitelist
Purpose
Determines if the player has whitelist access for a faction.
Parameters
faction
(number
): Faction index.
Realm
Shared
Returns
boolean
: True if whitelisted.
Example Usage
getClass
Purpose
Retrieves the class index of the player's character.
Parameters
- None
Realm
Shared
Returns
number|nil
: Class index or nil.
Example Usage
hasClassWhitelist
Purpose
Checks if the player's character is whitelisted for a class.
Parameters
class
(number
): Class index.
Realm
Shared
Returns
boolean
: True if class whitelist exists.
Example Usage
-- Verify the player is approved for a specific class
local result = player:hasClassWhitelist(class)
getClassData
Purpose
Returns the class table of the player's current class.
Parameters
- None
Realm
Shared
Returns
table|nil
: Class definition table.
Example Usage
getDarkRPVar
Purpose
Compatibility helper for retrieving money with DarkRP-style calls.
Parameters
var
(string
): Currently only supports"money"
.
Realm
Shared
Returns
number|nil
: Money amount or nil.
Example Usage
getMoney
Purpose
Convenience function to get the character's money amount.
Parameters
- None
Realm
Shared
Returns
number
: Current funds or0
.
Example Usage
canAfford
Purpose
Checks if the player has enough money for a purchase.
Parameters
amount
(number
): Cost to test.
Realm
Shared
Returns
boolean
: True if funds are sufficient.
Example Usage
hasSkillLevel
Purpose
Verifies the player's character meets an attribute level.
Parameters
-
skill
(string
): Attribute ID. -
level
(number
): Required level.
Realm
Shared
Returns
boolean
: Whether the character satisfies the requirement.
Example Usage
-- Ensure the player meets a single skill requirement
local result = player:hasSkillLevel(skill, level)
meetsRequiredSkills
Purpose
Checks a table of skill requirements against the player.
Parameters
requiredSkillLevels
(table
): Mapping of attribute IDs to levels.
Realm
Shared
Returns
boolean
: True if all requirements are met.
Example Usage
-- Validate multiple skill requirements at once
local result = player:meetsRequiredSkills(requiredSkillLevels)
forceSequence
Purpose
Plays an animation sequence and optionally freezes the player.
Parameters
-
sequenceName
(string
): Sequence to play. -
callback
(function|nil
): Called when finished. -
time
(number|nil
): Duration override. -
noFreeze
(boolean
): Don't freeze movement when true.
Realm
Shared
Returns
number|boolean
: Duration orfalse
on failure.
Example Usage
-- Play an animation while freezing the player
local result = player:forceSequence(sequenceName, callback, time, noFreeze)
leaveSequence
Purpose
Stops any forced sequence and restores player movement.
Parameters
- None
Realm
Shared
Returns
nil
: This function does not return a value.
Example Usage
restoreStamina
Purpose
Increases the player's stamina value.
Parameters
amount
(number
): Amount to restore.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
consumeStamina
Purpose
Reduces the player's stamina value.
Parameters
amount
(number
): Amount to subtract.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
addMoney
Purpose
Adds funds to the player's character, clamping to limits.
Parameters
amount
(number
): Money to add.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
-- Reward the player and announce the payout
player:addMoney(100)
player:notifyLocalized("questReward", lia.currency.get(100))
takeMoney
Purpose
Removes money from the player's character.
Parameters
amount
(number
): Amount to subtract.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
WhitelistAllClasses
Purpose
Grants whitelist access to every registered class.
Parameters
- None
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
WhitelistAllFactions
Purpose
Whitelists the player for all factions.
Parameters
- None
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
WhitelistEverything
Purpose
Convenience method to whitelist all factions and classes.
Parameters
- None
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
classWhitelist
Purpose
Adds a single class to the character's whitelist table.
Parameters
class
(number
): Class index to whitelist.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
classUnWhitelist
Purpose
Removes a class from the character's whitelist table.
Parameters
class
(number
): Class index to remove.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
setWhitelisted
Purpose
Sets or clears whitelist permission for a faction.
Parameters
-
faction
(number
): Faction index. -
whitelisted
(boolean|nil
): Enable when true, disable when false/nil.
Realm
Server
Returns
boolean
: True if the faction exists.
Example Usage
loadLiliaData
Purpose
Loads persistent Lilia data for the player from the database.
Parameters
callback
(function|nil
): Invoked with the loaded table.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
saveLiliaData
Purpose
Saves the player's Lilia data back to the database.
Parameters
- None
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
setLiliaData
Purpose
Stores a value in the player's persistent data table.
Parameters
-
key
(string
): Data key. -
value
(any
): Value to store. -
noNetworking
(boolean|nil
): Skip network update when true.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
setWaypoint
Purpose
Sends a waypoint to the client at the specified position.
Parameters
-
name
(string
): Display label. -
vector
(Vector
): World position.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
setWeighPoint
Purpose
Alias of setWaypoint()
for backwards compatibility.
Parameters
-
name
(string
): Display label. -
vector
(Vector
): World position.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
setWaypointWithLogo
Purpose
Creates a waypoint using a custom logo material.
Parameters
-
name
(string
): Display label. -
vector
(Vector
): World position. -
logo
(string
): Material path for the icon.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
getLiliaData
Purpose
Retrieves a stored value from the player's data table.
Parameters
-
key
(string
): Data key. -
default
(any
): Returned if the key is nil.
Realm
Server
Returns
any
: Stored value or default.
Example Usage
getData
Purpose
Alias of getLiliaData
.
Parameters
-
key
(string
): Data key. -
default
(any
): Returned if the key is nil.
Realm
Server
Returns
any
: Stored value or default.
Example Usage
getAllLiliaData
Purpose
Returns the entire table of persistent data for the player.
Parameters
- None
Realm
Server
Returns
table
: Player data table.
Example Usage
setRagdoll
Purpose
Associates a ragdoll entity with the player for later retrieval.
Parameters
entity
(Entity
): The ragdoll entity.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
NetworkAnimation
Purpose
Broadcasts animation bone data to all clients.
Parameters
-
active
(boolean
): Enable or disable manipulation. -
boneData
(table
): Map of bone names to angles.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
banPlayer
Purpose
Bans the player for a given reason and duration then kicks them.
Parameters
-
reason
(string|nil
): Message shown to the player. -
duration
(number|nil
): Length in minutes, ornil
for permanent.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
setAction
Purpose
Displays an action bar for a set duration and optionally runs a callback.
Parameters
-
text
(string|nil
): Text to display, or nil to clear. -
time
(number|nil
): How long to show it for. -
callback
(function|nil
): Executed when time elapses.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
doStaredAction
Purpose
Runs an action only while the player stares at the entity.
Parameters
-
entity
(Entity
): Target entity. -
callback
(function
): Called when the timer finishes. -
time
(number
): Duration in seconds. -
onCancel
(function|nil
): Called if gaze breaks. -
distance
(number|nil
): Max distance to maintain.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
stopAction
Purpose
Cancels any running action bar on the player.
Parameters
- None
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
requestDropdown
Purpose
Prompts the client with a dropdown selection dialog.
Parameters
-
title
(string
): Window title. -
subTitle
(string
): Description text. -
options
(table
): Table of options. -
callback
(function|nil
): Receives the chosen value.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
requestOptions
Purpose
Asks the client to select one or more options from a list.
Parameters
-
title
(string
): Window title. -
subTitle
(string
): Description text. -
options
(table
): Available options. -
limit
(number
): Maximum selections allowed. -
callback
(function|nil
): Receives the chosen values.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
requestString
Purpose
Requests a string from the client.
Parameters
-
title
(string
): Prompt title. -
subTitle
(string
): Prompt description. -
callback
(function|nil
): Called with the string. -
default
(string|nil
): Default value.
Realm
Server
Returns
Deferred|nil
: Deferred object when no callback supplied.
Example Usage
requestArguments
Purpose
Prompts the client for multiple typed values.
Parameters
-
title
(string
): Window title. -
argTypes
(table
): Field definitions. -
callback
(function|nil
): Called with a table of values.
Realm
Server
Returns
Deferred|nil
: Deferred object when no callback supplied.
Example Usage
binaryQuestion
Purpose
Displays a yes/no style question to the player.
Parameters
-
question
(string
): Main text. -
option1
(string
): Text for the first option. -
option2
(string
): Text for the second option. -
manualDismiss
(boolean
): Require manual closing. -
callback
(function
): Called with chosen value.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
requestButtons
Purpose
Prompts the player with multiple buttons that each trigger a server callback.
Parameters
-
title
(string
): Window title. -
buttons
(table
): Array where each element contains button text and a callback.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
player:requestButtons("Select one", {
{"A", function(client) print("Chose A") end},
{"B", function(client) print("Chose B") end}
})
getPlayTime
Purpose
Calculates how long the player has been on the server.
Parameters
- None
Realm
Server
Returns
number
: Total seconds of play-time.
Example Usage
getTotalOnlineTime
Purpose
Returns the player's total online time across all sessions.
Parameters
- None
Realm
Server
Returns
number
: Seconds spent online in total.
Example Usage
getLastOnline
Purpose
Returns how long ago the player was last seen online.
Parameters
- None
Realm
Server
Returns
string
: Human readable time description.
Example Usage
getLastOnlineTime
Purpose
Provides the timestamp of the player's last connection.
Parameters
- None
Realm
Server
Returns
number
: Unix time of the last session end.
Example Usage
createRagdoll
Purpose
Spawns a ragdoll copy of the player and optionally freezes it.
Parameters
-
freeze
(boolean|nil
): Disable physics whentrue
. -
isDead
(boolean|nil
): Mark as a death ragdoll.
Realm
Server
Returns
Entity
: The created ragdoll.
Example Usage
setRagdolled
Purpose
Toggles the player's ragdoll state for a duration.
Parameters
-
state
(boolean
): Enable or disable ragdoll. -
time
(number|nil
): Duration before standing up. -
getUpGrace
(number|nil
): Extra time to prevent early stand. -
getUpMessage
(string|nil
): Message while downed.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
syncVars
Purpose
Sends all networked variables to the player.
Parameters
- None
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
setLocalVar
Purpose
Sets a networked local variable on the player and triggers the LocalVarChanged hook.
Parameters
-
key
(string
): Variable name. -
value
(any
): Value to set.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
getLocalVar
Purpose
Retrieves a networked local variable stored on the player.
Parameters
-
key
(string
): Variable name. -
default
(any
): Value returned if not set.
Realm
Shared
Returns
any
: Stored value or default.
Example Usage
getPlayTime
Purpose
Returns play-time calculated client-side when called on a client.
Parameters
- None
Realm
Client
Returns
number
: Seconds of play-time.
Example Usage
getTotalOnlineTime
Purpose
Returns the player's total online time on the client side.
Parameters
- None
Realm
Client
Returns
number
: Accumulated seconds of play-time.
Example Usage
getLastOnline
Purpose
Reports how long it has been since the player was last online.
Parameters
- None
Realm
Client
Returns
string
: Friendly time string.
Example Usage
getLastOnlineTime
Purpose
Gives the Unix timestamp of the player's last session end.
Parameters
- None
Realm
Client
Returns
number
: Time value in seconds.
Example Usage
setWaypoint
Purpose
Displays a waypoint on the HUD until the player reaches it.
Parameters
-
name
(string
): Display label. -
vector
(Vector
): World position. -
onReach
(function|nil
): Called when reached.
Realm
Client
Returns
nil
: This function does not return a value.
Example Usage
setWeighPoint
Purpose
Alias of the client version of setWaypoint
.
Parameters
-
name
(string
): Display label. -
vector
(Vector
): World position. -
onReach
(function|nil
): Called when reached.
Realm
Client
Returns
nil
: This function does not return a value.
Example Usage
setWaypointWithLogo
Purpose
Places a waypoint using a logo material on the client HUD.
Parameters
-
name
(string
): Display label. -
vector
(Vector
): Position to navigate to. -
logo
(string
): Material path for the icon. -
onReach
(function|nil
): Called when reached.
Realm
Client
Returns
nil
: This function does not return a value.
Example Usage
getLiliaData
Purpose
Client-side accessor for stored player data.
Parameters
-
key
(string
): Data key. -
default
(any
): Fallback value.
Realm
Client
Returns
any
: Stored value or default.
Example Usage
getData
Purpose
Alias of getLiliaData
.
Parameters
-
key
(string
): Data key. -
default
(any
): Fallback value.
Realm
Client
Returns
any
: Stored value or default.
Example Usage
getAllLiliaData
Purpose
Returns the entire local data table for the player.
Parameters
- None
Realm
Client
Returns
table
: Local data table.
Example Usage
NetworkAnimation
Purpose
Applies or clears client-side bone angles based on animation data.
Parameters
-
active
(boolean
): Enable or disable animation. -
boneData
(table
): Bones and angles to apply.
Realm
Client
Returns
nil
: This function does not return a value.
Example Usage
getParts
Purpose
Returns the table of PAC3 part IDs currently attached to the player.
Parameters
- None
Realm
Shared
Returns
table
: Mapping of active part IDs.
Example Usage
syncParts
Purpose
Sends the player's PAC3 part data to their client.
Parameters
- None
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
addPart
Purpose
Adds the given PAC3 part to the player and broadcasts it.
Parameters
partID
(string
): Identifier of the part to attach.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
removePart
Purpose
Removes a previously added PAC3 part from the player.
Parameters
partID
(string
): Identifier of the part to remove.
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage
resetParts
Purpose
Clears all PAC3 parts that are currently attached to the player.
Parameters
- None
Realm
Server
Returns
nil
: This function does not return a value.
Example Usage