Player Meta

Player management system for the Lilia framework.

---

Overview

The player meta table provides comprehensive functionality for managing player data, interactions, and operations in the Lilia framework. It handles player character access, notification systems, permission checking, data management, interaction systems, and player-specific operations. The meta table operates on both server and client sides, with the server managing player data and validation while the client provides player interaction and display. It includes integration with the character system for character access, notification system for player messages, permission system for access control, data system for player persistence, and interaction system for player actions. The meta table ensures proper player data synchronization, permission validation, notification delivery, and comprehensive player management from connection to disconnection.

---

getChar()

Returns the active character object associated with this player.

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()

Builds a readable name for the player preferring character name.

Use for logging or UI when displaying player identity.

Returns:

string Character name if available, otherwise Steam name.

Example Usage:

    print(ply:tostring())

---

Name()

Returns the display name, falling back to Steam name if no character.

Use wherever Garry's Mod expects Name/Nick/GetName.

Returns:

string Character or Steam name.

Example Usage:

    local name = ply:Name()

---

doGesture(a, b, c)

Restarts a gesture animation and replicates it.

Use to play a gesture on the player and sync to others.

Parameters:

number a Gesture activity.

number b Layer or slot.

number c Playback rate or weight.

Example Usage:

    ply:doGesture(ACT_GMOD_GESTURE_WAVE, 0, 1)

---

setAction(text, time, callback)

Shows an action bar for the player and runs a callback when done.

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)

Runs a callback after the player stares at an entity for a duration.

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)

---

stopAction()

Cancels any active action or stare timers and hides the bar.

Use when an action is interrupted or completed early.

Example Usage:

    ply:stopAction()

---

hasPrivilege(privilegeName)

Checks if the player has a specific admin privilege.

Use before allowing privileged actions.

Parameters:

string privilegeName Permission to query.

Returns:

boolean True if the player has access.

Example Usage:

    if ply:hasPrivilege("canBan") then ...

---

removeRagdoll()

Deletes the player's ragdoll entity and clears the net var.

Use when respawning or cleaning up ragdolls.

Example Usage:

    ply:removeRagdoll()

---

getItemWeapon()

Returns the active weapon and matching inventory item if equipped.

Use when syncing weapon state with inventory data.

Returns:

Weapon|nil, Item|nil Active weapon entity and corresponding item, if found.

Example Usage:

    local wep, itm = ply:getItemWeapon()

---

isFamilySharedAccount()

Detects whether the account is being used via Steam Family Sharing.

Use for restrictions or messaging on shared accounts.

Returns:

boolean True if OwnerSteamID64 differs from SteamID.

Example Usage:

    if ply:isFamilySharedAccount() then warn() end

---

getItemDropPos()

Calculates a suitable position in front of the player to drop items.

Use before spawning a world item.

Returns:

Vector Drop position.

Example Usage:

    local pos = ply:getItemDropPos()

---

getItems()

Retrieves the player's inventory items if a character exists.

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)

Returns the entity the player is aiming at within a distance.

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)

---

notify(message, notifType)

Sends a notification to this player (or locally on client).

Use to display a generic notice.

Parameters:

string message Text to show.

string notifType Optional type key.

Example Usage:

    ply:notify("Hello")

---

notifyLocalized(message, notifType)

Sends a localized notification to this player or locally.

Use when the message is a localization token.

Parameters:

string message Localization key.

string notifType Optional type key.

Example Usage:

    ply:notifyLocalized("itemTaken", "apple")

---

notifyError(message)

Sends an error notification to this player or locally.

Use to display error messages in a consistent style.

Parameters:

string message Error text.

Example Usage:

    ply:notifyError("Invalid action")

---

notifyWarning(message)

Sends a warning notification to this player or locally.

Use for cautionary messages.

Parameters:

string message Text to display.

Example Usage:

    ply:notifyWarning("Low health")

---

notifyInfo(message)

Sends an info notification to this player or locally.

Use for neutral informational messages.

Parameters:

string message Text to display.

Example Usage:

    ply:notifyInfo("Quest updated")

---

notifySuccess(message)

Sends a success notification to this player or locally.

Use to indicate successful actions.

Parameters:

string message Text to display.

Example Usage:

    ply:notifySuccess("Saved")

---

notifyMoney(message)

Sends a money-themed notification to this player or locally.

Use for currency gain/spend messages.

Parameters:

string message Text to display.

Example Usage:

    ply:notifyMoney("+$50")

---

notifyAdmin(message)

Sends an admin-level notification to this player or locally.

Use for staff-oriented alerts.

Parameters:

string message Text to display.

Example Usage:

    ply:notifyAdmin("Ticket opened")

---

notifyErrorLocalized(key)

Sends a localized error notification to the player or locally.

Use for localized error tokens.

Parameters:

string key Localization key.

Example Usage:

    ply:notifyErrorLocalized("invalidArg")

---

notifyWarningLocalized(key)

Sends a localized warning notification to the player or locally.

Use for localized warnings.

Parameters:

string key Localization key.

Example Usage:

    ply:notifyWarningLocalized("lowHealth")

---

notifyInfoLocalized(key)

Sends a localized info notification to the player or locally.

Use for localized informational messages.

Parameters:

string key Localization key.

Example Usage:

    ply:notifyInfoLocalized("questUpdate")

---

notifySuccessLocalized(key)

Sends a localized success notification to the player or locally.

Use for localized success confirmations.

Parameters:

string key Localization key.

Example Usage:

    ply:notifySuccessLocalized("saved")

---

notifyMoneyLocalized(key)

Sends a localized money notification to the player or locally.

Use for localized currency messages.

Parameters:

string key Localization key.

Example Usage:

    ply:notifyMoneyLocalized("moneyGained", 50)

---

notifyAdminLocalized(key)

Sends a localized admin notification to the player or locally.

Use for staff messages with localization.

Parameters:

string key Localization key.

Example Usage:

    ply:notifyAdminLocalized("ticketOpened")

---

canEditVendor(vendor)

Checks if the player can edit a vendor.

Use before opening vendor edit interfaces.

Parameters:

Entity vendor Vendor entity to check.

Returns:

boolean True if editing is permitted.

Example Usage:

    if ply:canEditVendor(vendor) then ...

---

isStaff()

Determines if the player's user group is marked as Staff.

Use for gating staff-only features.

Returns:

boolean True if their usergroup includes the Staff type.

Example Usage:

    if ply:isStaff() then ...

---

isStaffOnDuty()

Checks if the player is currently on the staff faction.

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 ...

---

hasWhitelist(faction)

Checks if the player has whitelist access to a faction.

Use before allowing faction selection.

Parameters:

number faction Faction ID.

Returns:

boolean True if default or whitelisted.

Example Usage:

    if ply:hasWhitelist(factionID) then ...

---

getClassData()

Retrieves the class table for the player's current character.

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)

Provides DarkRP compatibility for money queries.

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()

Returns the character's money or zero if unavailable.

Use whenever reading player currency.

Returns:

number Current money amount.

Example Usage:

    local cash = ply:getMoney()

---

canAfford(amount)

Returns whether the player can afford a cost.

Use before charging the player.

Parameters:

number amount Cost to check.

Returns:

boolean True if the player has enough money.

Example Usage:

    if ply:canAfford(100) then ...

---

hasSkillLevel(skill, level)

Checks if the player meets a specific skill level requirement.

Use for gating actions behind skills.

Parameters:

string skill Attribute key.

number level Required level.

Returns:

boolean True if the player meets or exceeds the level.

Example Usage:

    if ply:hasSkillLevel("lockpick", 3) then ...

---

meetsRequiredSkills(requiredSkillLevels)

Verifies all required skills meet their target levels.

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)

Forces the player to play a sequence and freezes movement if needed.

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)

---

leaveSequence()

Stops the forced sequence, unfreezes movement, and runs callbacks.

Use when a sequence finishes or must be cancelled.

Example Usage:

    ply:leaveSequence()

---

getFlags()

Returns the flag string from the player's character.

Use when checking player permissions.

Returns:

string Concatenated flags or empty string.

Example Usage:

    local flags = ply:getFlags()

---

giveFlags(flags)

Grants one or more flags to the player's character.

Use when adding privileges.

Parameters:

string flags Flags to give.

Example Usage:

    ply:giveFlags("z")

---

takeFlags(flags)

Removes flags from the player's character.

Use when revoking privileges.

Parameters:

string flags Flags to remove.

Example Usage:

    ply:takeFlags("z")

---

networkAnimation(active, boneData)

Synchronizes or applies a bone animation state across server/client.

Use when enabling or disabling custom bone angles.

Parameters:

boolean active Whether the animation is active.

table boneData Map of bone names to Angle values.

Example Usage:

    ply:networkAnimation(true, bones)

---

getAllLiliaData()

Returns the table storing Lilia-specific player data.

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)

Sets a waypoint for the player and draws HUD guidance clientside.

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)

Reads stored Lilia player data, returning a default when missing.

Use for persistent per-player data such as settings or cooldowns.

Parameters:

string key Data key to fetch.

any default Value to return when unset.

Returns:

any Stored value or default.

Example Usage:

    local last = ply:getLiliaData("lastIP", "")

---

getMainCharacter()

Returns the player's recorded main character ID, if set.

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)

Sets the player's main character, applying cooldown rules server-side.

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)

---

hasFlags(flags)

Checks if the player (via their character) has any of the given flags.

Use when gating actions behind flag permissions.

Parameters:

string flags One or more flag characters to test.

Returns:

boolean True if at least one flag is present.

Example Usage:

    if ply:hasFlags("z") then ...

---

playTimeGreaterThan(time)

Returns true if the player's recorded playtime exceeds a value.

Use for requirements based on time played.

Parameters:

number time Threshold in seconds.

Returns:

boolean True if playtime is greater than the threshold.

Example Usage:

    if ply:playTimeGreaterThan(3600) then ...

---

requestOptions(title, subTitle, options, limit, callback)

Presents a list of options to the player and returns selected values.

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)

Prompts the player for a string value and returns it.

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)

Requests typed arguments from the player based on a specification.

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)

Shows a binary (two-button) question to the player and returns choice.

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)

Displays a popup question with arbitrary buttons and handles responses.

Use for multi-button confirmations or admin prompts.

Parameters:

string question Prompt text.

table buttons Array of strings or {label, callback} pairs.

Example Usage:

    ply:requestPopupQuestion("Choose", {{"A", cbA}, {"B", cbB}})

---

requestButtons(title, buttons)

Sends a button list prompt to the player and routes callbacks.

Use when a simple list of actions is needed.

Parameters:

string title Dialog title.

table buttons Array of {text=, callback=} entries.

Example Usage:

    ply:requestButtons("Actions", {{text="A", callback=cb}})

---

requestDropdown(title, subTitle, options, callback)

Presents a dropdown selection dialog to the player.

Use for single-choice option selection.

Parameters:

string title

string subTitle

table options Available options.

function callback Invoked with chosen option.

Example Usage:

    ply:requestDropdown("Pick class", "Choose", opts, cb)

---

restoreStamina(amount)

Restores stamina by an amount, clamping to the character's maximum.

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)

Reduces stamina by an amount and handles exhaustion state.

Use when sprinting or performing actions that consume stamina.

Parameters:

number amount Stamina to subtract.

Example Usage:

    ply:consumeStamina(5)

---

addMoney(amount)

Adds money to the player's character and logs the change.

Use when rewarding currency server-side.

Parameters:

number amount Amount to add (can be negative via takeMoney).

Returns:

boolean False if no character exists.

Example Usage:

    ply:addMoney(50)

---

takeMoney(amount)

Removes money from the player's character by delegating to giveMoney.

Use when charging the player server-side.

Parameters:

number amount Amount to deduct.

Example Usage:

    ply:takeMoney(20)

---

loadLiliaData(callback)

Loads persistent Lilia player data from the database.

Use during player initial spawn to hydrate data.

Parameters:

function callback optional Invoked with loaded data table.

Example Usage:

    ply:loadLiliaData()

---

saveLiliaData()

Persists the player's Lilia data back to the database.

Use on disconnect or after updating persistent data.

Example Usage:

    ply:saveLiliaData()

---

setLiliaData(key, value, noNetworking, noSave)

Sets a key in the player's Lilia data, optionally syncing and saving.

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)

Records a ban entry and kicks the player with a ban message.

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()

Returns the player's total playtime in seconds (server calculation).

Use for server-side playtime checks.

Returns:

number Playtime in seconds.

Example Usage:

    local t = ply:getPlayTime()

---

setRagdolled(state, baseTime, getUpGrace, getUpMessage)

Toggles ragdoll state for the player, handling weapons, timers, and get-up.

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)

---

syncVars()

Sends all known net variables to this player.

Use when a player joins or needs a full resync.

Example Usage:

    ply:syncVars()

---

setNetVar(key, value)

Sets a networked variable for this player and broadcasts it.

Use when updating shared player state.

Parameters:

string key Variable name.

any value Value to store.

Example Usage:

    ply:setNetVar("hasKey", true)

---

setLocalVar(key, value)

Sets a server-local variable for this player and sends it only to them.

Use for per-player state that should not broadcast.

Parameters:

string key Variable name.

any value Value to store.

Example Usage:

    ply:setLocalVar("stamina", 80)

---

getLocalVar(key, default)

Reads a server-local variable for this player.

Use when accessing non-networked state.

Parameters:

string key Variable name.

any default Fallback when unset.

Returns:

any Stored value or default.

Example Usage:

    local stamina = ply:getLocalVar("stamina", 100)

---

getLocalVar(key, default)

Reads a networked variable for this player on the client.

Use clientside when accessing shared netvars.

Parameters:

string key Variable name.

any default Fallback when unset.

Returns:

any Stored value or default.

Example Usage:

    local val = ply:getLocalVar("stamina", 0)

---

getPlayTime()

Returns the player's playtime (client-calculated fallback).

Use on the client when server data is unavailable.

Returns:

number Playtime in seconds.

Example Usage:

    local t = ply:getPlayTime()

---

getParts()

Returns the player's active PAC parts.

Use to check which PAC parts are currently equipped on the player.

Returns:

table Table of active PAC part IDs.

Example Usage:

    local parts = ply:getParts()
    if parts["helmet"] then
        print("Player has helmet equipped")
    end

---

syncParts()

Synchronizes the player's PAC parts with the client.

Use to ensure the client has the correct PAC parts data.

Returns:

None.

Example Usage:

    ply:syncParts()

---

addPart(partID)

Adds a PAC part to the player.

Use when equipping PAC parts on a player.

Parameters:

string partID The unique ID of the PAC part to add.

Returns:

None.

Example Usage:

    ply:addPart("helmet_model")

---

removePart(partID)

Removes a PAC part from the player.

Use when unequipping PAC parts from a player.

Parameters:

string partID The unique ID of the PAC part to remove.

Returns:

None.

Example Usage:

    ply:removePart("helmet_model")

---

resetParts()

Removes all PAC parts from the player.

Use to clear all equipped PAC parts from a player.

Returns:

None.

Example Usage:

    ply:resetParts()

---

IsAvailable()

Removes all PAC parts from the player.

Use to clear all equipped PAC parts from a player.

Returns:

None.

Example Usage:

    ply:resetParts()

---