Player
Player management system for the Lilia framework.
Overview
getChar()
Purpose
Returns the active character object associated with this player.
When Called
Use whenever you need the player's character state.
Returns
table|nil Character instance or nil if none is selected.
Example Usage
local char = ply:getChar()
tostring()
Purpose
Builds a readable name for the player preferring character name.
When Called
Use for logging or UI when displaying player identity.
Returns
string Character name if available, otherwise Steam name.
Example Usage
print(ply:tostring())
Name()
Purpose
Returns the display name, falling back to Steam name if no character.
When Called
Use wherever Garry's Mod expects Name/Nick/GetName.
Returns
string Character or Steam name.
Example Usage
local name = ply:Name()
setAction(text, time, callback)
Purpose
Shows an action bar for the player and runs a callback when done.
When Called
Use to gate actions behind a timed progress bar.
Parameters
string text optional Message to display; nil cancels the bar.
number time Duration in seconds.
function callback optional Invoked when the timer completes.
Example Usage
ply:setAction("Lockpicking", 5, onFinish)
doStaredAction(entity, callback, time, onCancel, distance)
Purpose
Runs a callback after the player stares at an entity for a duration.
When Called
Use for interactions requiring sustained aim on a target.
Parameters
Entity entity Target entity to watch.
function callback Function called after staring completes.
number time Duration in seconds required.
function onCancel optional Called if the stare is interrupted.
number distance optional Max distance trace length.
Example Usage
ply:doStaredAction(door, onComplete, 3)
getItemDropPos()
Purpose
Calculates a suitable position in front of the player to drop items.
When Called
Use before spawning a world item.
Returns
Vector Drop position.
Example Usage
local pos = ply:getItemDropPos()
getItems()
Purpose
Retrieves the player's inventory items if a character exists.
When Called
Use when accessing a player's item list directly.
Returns
table|nil Items table or nil if no inventory.
Example Usage
local items = ply:getItems()
getTracedEntity(distance)
Purpose
Returns the entity the player is aiming at within a distance.
When Called
Use for interaction traces.
Parameters
number distance Max trace length; default 96.
Returns
Entity|nil Hit entity or nil.
Example Usage
local ent = ply:getTracedEntity(128)
notifyError(message)
Purpose
Sends an error notification to this player or locally.
When Called
Use to display error messages in a consistent style.
Parameters
string message Error text.
Example Usage
ply:notifyError("Invalid action")
notifyWarning(message)
Purpose
Sends a warning notification to this player or locally.
When Called
Use for cautionary messages.
Parameters
string message Text to display.
Example Usage
ply:notifyWarning("Low health")
notifyInfo(message)
Purpose
Sends an info notification to this player or locally.
When Called
Use for neutral informational messages.
Parameters
string message Text to display.
Example Usage
ply:notifyInfo("Quest updated")
notifySuccess(message)
Purpose
Sends a success notification to this player or locally.
When Called
Use to indicate successful actions.
Parameters
string message Text to display.
Example Usage
ply:notifySuccess("Saved")
notifyMoney(message)
Purpose
Sends a money-themed notification to this player or locally.
When Called
Use for currency gain/spend messages.
Parameters
string message Text to display.
Example Usage
ply:notifyMoney("+$50")
notifyAdmin(message)
Purpose
Sends an admin-level notification to this player or locally.
When Called
Use for staff-oriented alerts.
Parameters
string message Text to display.
Example Usage
ply:notifyAdmin("Ticket opened")
notifyErrorLocalized(key)
Purpose
Sends a localized error notification to the player or locally.
When Called
Use for localized error tokens.
Parameters
string key Localization key.
Example Usage
ply:notifyErrorLocalized("invalidArg")
notifyWarningLocalized(key)
Purpose
Sends a localized warning notification to the player or locally.
When Called
Use for localized warnings.
Parameters
string key Localization key.
Example Usage
ply:notifyWarningLocalized("lowHealth")
notifyInfoLocalized(key)
Purpose
Sends a localized info notification to the player or locally.
When Called
Use for localized informational messages.
Parameters
string key Localization key.
Example Usage
ply:notifyInfoLocalized("questUpdate")
notifySuccessLocalized(key)
Purpose
Sends a localized success notification to the player or locally.
When Called
Use for localized success confirmations.
Parameters
string key Localization key.
Example Usage
ply:notifySuccessLocalized("saved")
notifyMoneyLocalized(key)
Purpose
Sends a localized money notification to the player or locally.
When Called
Use for localized currency messages.
Parameters
string key Localization key.
Example Usage
ply:notifyMoneyLocalized("moneyGained", 50)
notifyAdminLocalized(key)
Purpose
Sends a localized admin notification to the player or locally.
When Called
Use for staff messages with localization.
Parameters
string key Localization key.
Example Usage
ply:notifyAdminLocalized("ticketOpened")
isStaff()
Purpose
Determines if the player's user group is marked as Staff.
When Called
Use for gating staff-only features.
Returns
boolean True if their usergroup includes the Staff type.
Example Usage
if ply:isStaff() then ...
isStaffOnDuty()
Purpose
Checks if the player is currently on the staff faction.
When Called
Use when features apply only to on-duty staff.
Returns
boolean True if the player is in FACTION_STAFF.
Example Usage
if ply:isStaffOnDuty() then ...
getClassData()
Purpose
Retrieves the class table for the player's current character.
When Called
Use when needing class metadata like limits or permissions.
Returns
table|nil Class definition or nil if unavailable.
Example Usage
local classData = ply:getClassData()
getDarkRPVar(var)
Purpose
Provides DarkRP compatibility for money queries.
When Called
Use when DarkRP expects getDarkRPVar("money").
Parameters
string var Variable name, only "money" supported.
Returns
number|nil Character money or nil if unsupported var.
Example Usage
local cash = ply:getDarkRPVar("money")
getMoney()
Purpose
Returns the character's money or zero if unavailable.
When Called
Use whenever reading player currency.
Returns
number Current money amount.
Example Usage
local cash = ply:getMoney()
hasSkillLevel(skill, level)
Purpose
Checks if the player meets a specific skill level requirement.
When Called
Use for gating actions behind skills.
Parameters
Returns
boolean True if the player meets or exceeds the level.
Example Usage
if ply:hasSkillLevel("lockpick", 3) then ...
meetsRequiredSkills(requiredSkillLevels)
Purpose
Verifies all required skills meet their target levels.
When Called
Use when checking multiple skill prerequisites.
Parameters
table requiredSkillLevels Map of skill keys to required levels.
Returns
boolean True if all requirements pass.
Example Usage
if ply:meetsRequiredSkills(reqs) then ...
forceSequence(sequenceName, callback, time, noFreeze)
Purpose
Forces the player to play a sequence and freezes movement if needed.
When Called
Use for scripted animations like sit or interact sequences.
Parameters
string sequenceName optional Sequence to play; nil clears the current sequence.
function callback optional Called when the sequence ends.
number time optional Override duration.
boolean noFreeze Prevent movement freeze when true.
Returns
number|boolean|nil Duration when started, false on failure, or nil when clearing.
Example Usage
ply:forceSequence("sit", nil, 5)
getFlags()
Purpose
Returns the flag string from the player's character.
When Called
Use when checking player permissions.
Returns
string Concatenated flags or empty string.
Example Usage
local flags = ply:getFlags()
giveFlags(flags)
Purpose
Grants one or more flags to the player's character.
When Called
Use when adding privileges.
Parameters
string flags Flags to give.
Example Usage
ply:giveFlags("z")
takeFlags(flags)
Purpose
Removes flags from the player's character.
When Called
Use when revoking privileges.
Parameters
string flags Flags to remove.
Example Usage
ply:takeFlags("z")
getAllLiliaData()
Purpose
Returns the table storing Lilia-specific player data.
When Called
Use when reading or writing persistent player data.
Returns
table Data table per realm.
Example Usage
local data = ply:getAllLiliaData()
setWaypoint(name, vector, logo, onReach)
Purpose
Sets a waypoint for the player and draws HUD guidance clientside.
When Called
Use when directing a player to a position or objective.
Parameters
string name Label shown on the HUD.
Vector vector Target world position.
string logo optional Optional material path for the icon.
function onReach optional Callback fired when the waypoint is reached.
Example Usage
ply:setWaypoint("Stash", pos)
getLiliaData(key, default)
Purpose
Reads stored Lilia player data, returning a default when missing.
When Called
Use for persistent per-player data such as settings or cooldowns.
Parameters
Returns
any Stored value or default.
Example Usage
local last = ply:getLiliaData("lastIP", "")
getMainCharacter()
Purpose
Returns the player's recorded main character ID, if set.
When Called
Use to highlight or auto-select the main character.
Returns
number|nil Character ID or nil when unset.
Example Usage
local main = ply:getMainCharacter()
setMainCharacter(charID)
Purpose
Sets the player's main character, applying cooldown rules server-side.
When Called
Use when a player picks or clears their main character.
Parameters
number charID optional Character ID to set, or nil/0 to clear.
Returns
boolean, string|nil True on success, or false with a reason.
Example Usage
ply:setMainCharacter(charID)
requestOptions(title, subTitle, options, limit, callback)
Purpose
Presents a list of options to the player and returns selected values.
When Called
Use for multi-choice prompts that may return multiple selections.
Parameters
string title Dialog title.
string subTitle Subtitle/description.
table options Array of option labels.
number limit Max selections allowed.
function callback Called with selections when chosen.
Returns
deferred|nil Promise when callback omitted, otherwise nil.
Example Usage
ply:requestOptions("Pick", "Choose one", {"A","B"}, 1, cb)
requestString(title, subTitle, callback, default)
Purpose
Prompts the player for a string value and returns it.
When Called
Use when collecting free-form text input.
Parameters
string title
string subTitle
function callback optional Receives the string result; optional if using deferred.
string default optional Prefilled value.
Returns
deferred|nil Promise when callback omitted, otherwise nil.
Example Usage
ply:requestString("Name", "Enter name", onDone)
requestArguments(title, argTypes, callback)
Purpose
Requests typed arguments from the player based on a specification.
When Called
Use for admin commands requiring typed input.
Parameters
string title Dialog title.
table argTypes Schema describing required arguments.
function callback optional Receives parsed values; optional if using deferred.
Returns
deferred|nil Promise when callback omitted.
Example Usage
ply:requestArguments("Teleport", spec, cb)
requestBinaryQuestion(question, option1, option2, manualDismiss, callback)
Purpose
Shows a binary (two-button) question to the player and returns choice.
When Called
Use for yes/no confirmations.
Parameters
string question Prompt text.
string option1 Label for first option.
string option2 Label for second option.
boolean manualDismiss Require manual close; optional.
function callback Receives 0/1 result.
Example Usage
ply:requestBinaryQuestion("Proceed?", "Yes", "No", false, cb)
requestPopupQuestion(question, buttons)
restoreStamina(amount)
Purpose
Restores stamina by an amount, clamping to the character's maximum.
When Called
Use when giving the player stamina back (e.g., resting or items).
Parameters
number amount Stamina to add.
Example Usage
ply:restoreStamina(10)
consumeStamina(amount)
Purpose
Reduces stamina by an amount and handles exhaustion state.
When Called
Use when sprinting or performing actions that consume stamina.
Parameters
number amount Stamina to subtract.
Example Usage
ply:consumeStamina(5)
takeMoney(amount)
Purpose
Removes money from the player's character by delegating to giveMoney.
When Called
Use when charging the player server-side.
Parameters
number amount Amount to deduct.
Example Usage
ply:takeMoney(20)
loadLiliaData(callback)
Purpose
Loads persistent Lilia player data from the database.
When Called
Use during player initial spawn to hydrate data.
Parameters
function callback optional Invoked with loaded data table.
Example Usage
ply:loadLiliaData()
setLiliaData(key, value, noNetworking, noSave)
Purpose
Sets a key in the player's Lilia data, optionally syncing and saving.
When Called
Use when updating persistent player-specific values.
Parameters
string key Data key.
any value Value to store.
boolean noNetworking Skip net sync when true.
boolean noSave Skip immediate DB save when true.
Example Usage
ply:setLiliaData("lastIP", ip)
banPlayer(reason, duration, banner)
Purpose
Records a ban entry and kicks the player with a ban message.
When Called
Use when banning a player via scripts.
Parameters
string reason Ban reason.
number duration Duration in minutes; 0 or nil for perm.
Player banner optional Staff issuing the ban.
Example Usage
ply:banPlayer("RDM", 60, admin)
getPlayTime()
Purpose
Returns the player's total playtime in seconds (server calculation).
When Called
Use for server-side playtime checks.
Returns
number Playtime in seconds.
Example Usage
local t = ply:getPlayTime()
setRagdolled(state, baseTime, getUpGrace, getUpMessage)
Purpose
Toggles ragdoll state for the player, handling weapons, timers, and get-up.
When Called
Use when knocking out or reviving a player.
Parameters
boolean state True to ragdoll, false to restore.
number baseTime optional Duration to stay ragdolled.
number getUpGrace optional Additional grace time before getting up.
string getUpMessage optional Action bar text while ragdolled.
Example Usage
ply:setRagdolled(true, 10)
getPlayTime()
Purpose
Returns the player's playtime (client-calculated fallback).
When Called
Use on the client when server data is unavailable.
Returns
number Playtime in seconds.
Example Usage
local t = ply:getPlayTime()