Skip to content

ax.player.meta

Player meta functions

Documented functions: 48  ·  Realm: client, server, shared

Functions

ax.player.meta:CanMaintainEntityAction(entity, allowEyeTrace, maxDistance)

Returns whether the player is still in a position to maintain an entity interaction.

First checks self:GetUseEntity() — if it equals entity the player is actively looking at it and true is returned immediately.

If allowEyeTrace is true, also checks self:GetEyeTrace() and optionally enforces a maximum distance between the player's shoot position and the trace hit position.

Returns false when the player or entity is invalid, the entity is not being looked at, or the distance limit is exceeded.

Realm: shared

Parameters

Name Type Description
entity Entity The entity the action is being performed on.
allowEyeTrace boolean\|nil When true, also accepts the eye trace as a valid look target.
maxDistance number\|nil Maximum allowed distance to the entity (in world units). Ignored when 0 or nil.

Returns

  • boolean: True if the player can maintain the action, false otherwise.

Source: gamemode/framework/meta/sh_player.lua:842

ax.player.meta:ClearRagdollWeapons()

Clears the stored ragdoll weapon state from this player.

Removes axRagdollWeapons and axRagdollActiveWeapon from the player's entity table.

Called automatically by RestoreRagdollWeapons after weapons are given back, and can be called manually to discard weapon state without restoring.

Realm: server

Source: gamemode/framework/meta/sh_player.lua:243

ax.player.meta:DermaMessage(text, title, buttonName, onClosed)

Opens a Derma message dialog on this player's client.

Sends a "player.dermaMessage" net message with the dialog content.

The optional onClosed callback is stored server-side and invoked when the client acknowledges the dialog.

Useful for non-blocking informational prompts.

Realm: server

Parameters

Name Type Description
text string The body text of the message dialog.
title string The window title.
buttonName string\|nil Label for the dismiss button.
onClosed function\|nil Called when the player closes the dialog.

Source: gamemode/framework/meta/sh_player.lua:666

ax.player.meta:DermaStringRequest(title, subtitle, default, confirm, cancel, confirmText, cancelText)

Opens a Derma string input dialog on this player's client.

Sends a "player.dermaStringRequest" net message to the player with the dialog parameters.

The confirm and cancel callbacks are stored on the player's entity table and invoked when the client responds via the corresponding net handler.

Realm: server

Parameters

Name Type Description
title string The dialog window title.
subtitle string The instructional subtitle shown below the title.
default string\|nil Default text pre-filled in the input box.
confirm function\|nil Called with the entered text when the player confirms.
cancel function\|nil Called when the player cancels or closes the dialog.
confirmText string\|nil Label for the confirm button. Defaults to "OK".
cancelText string\|nil Label for the cancel button. Defaults to "Cancel".

Source: gamemode/framework/meta/sh_player.lua:645

ax.player.meta:EnsurePlayer(callback)

Ensures the player has a row in the ax_players database table, creating one if needed.

On the server, issues a SELECT query for the player's SteamID64.

If no row is found, an INSERT is issued with default values for all fields.

In both cases callback(true) is invoked on success; callback(false) is invoked on database error.

If no callback is provided, a debug message is printed instead.

Realm: server

Parameters

Name Type Description
callback function\|nil Called as callback(ok) where ok is true on success, false on error.

Source: gamemode/framework/meta/sh_player.lua:585

ax.player.meta:EnsurePlayer(callback)

Queues a callback to run once this player is ready on the client.

On the client, "ready" means axReady has been set on the player's entity table by the framework initialisation sequence.

If the player is already ready, callback is invoked immediately.

Otherwise it is appended to axEnsureCallbacks and invoked once the ready state is reached.

This is the client-side counterpart to the server's database-backed EnsurePlayer.

Realm: client

Parameters

Name Type Description
callback function\|nil Called as callback(true) when the player is ready.

Source: gamemode/framework/meta/sh_player.lua:684

ax.player.meta:GetCharacter()

Returns the character instance currently active for this player.

Reads axCharacter from the player's entity table, which is set when a character is loaded via ax.character:Load().

Returns nil when the player is in the character selection screen or has no character loaded. Aliased as GetChar.

Realm: shared

Returns

  • table|nil: The active character instance, or nil if none is loaded.

Source: gamemode/framework/meta/sh_player.lua:29

ax.player.meta:GetCharacters()

Returns all character instances associated with this player.

Reads axCharacters from the player's entity table, which is populated when the player's characters are fetched from the database on connect.

Returns an empty table when no characters have been loaded yet.

Realm: shared

Returns

  • table: An ordered array of character instances, or {} if none are loaded.

Source: gamemode/framework/meta/sh_player.lua:51

ax.player.meta:GetClassData()

Returns the class definition table for this player's active character's class.

Retrieves the character's class ID via character:GetClass() and looks it up in the class registry via ax.class:Get.

Returns nil when the player has no active character or the character has no class assigned.

Realm: shared

Returns

  • table|nil: The class definition table, or nil if no class is set.

Source: gamemode/framework/meta/sh_player.lua:83

ax.player.meta:GetFaction()

Returns the player's current faction index, or nil if not in a valid faction.

Reads the player's team index via self:Team() and validates it against the registered faction registry via ax.faction:IsValid.

Returns nil for spectators, players not yet assigned a faction, or indices that don't map to a registered faction.

Realm: shared

Returns

  • number|nil: The faction index, or nil if not in a valid faction.

Source: gamemode/framework/meta/sh_player.lua:60

ax.player.meta:GetFactionData()

Returns the faction definition table for this player's current faction.

Delegates to ax.faction:Get using the result of GetFaction(). Returns nil when the player is not in a valid faction.

Realm: shared

Returns

  • table|nil: The faction definition table, or nil if not in a faction.

Source: gamemode/framework/meta/sh_player.lua:73

ax.player.meta:GetRankData()

Returns the rank definition table for this player's active character's rank.

Retrieves the character's rank ID via character:GetRank() and looks it up in the rank registry via ax.rank:Get.

Returns nil when the player has no active character or the character has no rank assigned.

Realm: shared

Returns

  • table|nil: The rank definition table, or nil if no rank is set.

Source: gamemode/framework/meta/sh_player.lua:100

ax.player.meta:GetSessionPlayTime()

Returns the number of seconds the player has been connected in this session.

Computes os.time() - axJoinTime where axJoinTime is set when the player joins the server.

Returns 0 when axJoinTime has not been set (e.g. before the player has fully initialised).

Realm: shared

Returns

  • number: The number of seconds in the current session, or 0 if unavailable.

Source: gamemode/framework/meta/sh_player.lua:708

ax.player.meta:HasFactionWhitelist(iFactionID)

Returns whether the player has been whitelisted for a given faction.

Reads the "whitelists" key from the player's data store. Returns true only when the entry for iFactionID is explicitly true.

Returns false when the faction ID is invalid, unregistered, or the player has no whitelist entry for it.

Realm: shared

Parameters

Name Type Description
iFactionID number The numeric faction index to check.

Returns

  • boolean: True if the player is whitelisted for the faction, false otherwise.

Source: gamemode/framework/meta/sh_player.lua:175

ax.player.meta:InNoclip()

Returns whether the player is currently in noclip mode.

Checks if the player's move type is MOVETYPE_NOCLIP and if they are not drawing their model (as a proxy for being hidden in noclip).

This is more reliable than just checking the move type, as some gamemodes (like DarkRP) set MOVETYPE_NOCLIP when the player is arrested but they are still solid and visible.

Realm: shared

Returns

  • boolean: True if the player is in noclip mode, false otherwise.

Source: gamemode/framework/meta/sh_player.lua:195

ax.player.meta:IsRagdolled()

Returns whether the player is currently in a ragdolled state.

Reads the "ragdolled" relay key set by SetRagdolled. Returns false when the relay has not been set or has been cleared.

Realm: shared

Returns

  • boolean: True if the player is currently ragdolled, false otherwise.

Source: gamemode/framework/meta/sh_player.lua:203

ax.player.meta:Notify(text, type, length)

Sends a toast notification to this player.

On the server, delegates to ax.notification:Send.

On the client, delegates to ax.notification:Add.

The type parameter controls the notification style (e.g. "error", "success", "info").

length controls display duration in seconds; the notification system applies a default when omitted.

Realm: shared

Parameters

Name Type Description
text string The notification message to display.
type string\|nil The notification type (e.g. "error", "success", "info").
length number\|nil Display duration in seconds.

Source: gamemode/framework/meta/sh_player.lua:751

ax.player.meta:PerformAction(label, duration, onComplete, onCancel, bAllowRagdolled)

Starts or stops a progress action bar for this player.

When label is nil, cancels any running action bar: invokes onCancel if stored, clears the action bar timer, and sends "player.actionbar.stop" to the client.

When label is provided, starts a new action bar by sending "player.actionbar.start" to the client with the label and duration, and stores onComplete/onCancel on the player's entity table.

On the client, delegates to ax.actionBar:Start or ax.actionBar:Stop.

If the player is ragdolled and bAllowRagdolled is not true, a localised error notification is sent and false is returned.

Realm: shared

Parameters

Name Type Description
label string\|nil The action bar label. Pass nil to cancel the active bar.
duration number\|nil The bar duration in seconds. Defaults to 5.
onComplete function\|nil Called when the bar completes without cancellation.
onCancel function\|nil Called when the bar is cancelled before completion.
bAllowRagdolled boolean\|nil When true, allows the action bar while ragdolled.

Returns

  • false|nil: Returns false if blocked due to ragdoll state; nil otherwise.

Source: gamemode/framework/meta/sh_player.lua:793

ax.player.meta:PerformEntityAction(entity, label, duration, onComplete, onCancel, allowEyeTrace, maxDistance)

Starts an action bar that automatically cancels if the player stops looking at an entity.

Creates a repeating 0.1-second timer that calls CanMaintainEntityAction each tick.

If the entity becomes invalid or the player stops meeting the look/distance requirements, the timer is removed and PerformAction(nil) is called to cancel the bar.

The action bar itself is started via PerformAction with the provided parameters.

Realm: shared

Parameters

Name Type Description
entity Entity The entity the player must keep looking at.
label string The action bar label displayed to the player.
duration number The bar duration in seconds.
onComplete function\|nil Called when the bar completes without cancellation.
onCancel function\|nil Called when the bar is cancelled.
allowEyeTrace boolean\|nil When true, the eye trace is also accepted (see CanMaintainEntityAction).
maxDistance number\|nil Maximum allowed distance to the entity. Ignored when nil.

Source: gamemode/framework/meta/sh_player.lua:884

ax.player.meta:PlayGesture(slot, sequence)

Plays a gesture animation in the given layer slot on this player.

On the server, broadcasts a PVS net message so nearby clients execute the gesture.

On the client, resolves a string sequence name to a numeric ID via LookupSequence, caching the result keyed by "modelPath:sequenceName" to avoid repeated lookups on the same model.

The numeric ID is then passed to AddVCDSequenceToGestureSlot.

Returns nil and prints an error when the slot is out of range (0–6) or the player has no active character.

Realm: shared

Parameters

Name Type Description
slot number The gesture layer slot (0–6) to play the animation in.
sequence string\|number The sequence name (string) or sequence ID (number) to play.

Returns

  • nil: Always returns nil on the server (result via net message); nil on error.

Source: gamemode/framework/meta/sh_player.lua:124

ax.player.meta:RestoreRagdollWeapons()

Restores all weapons stripped by StripWeaponsForRagdoll.

Iterates the stored weapon data in axRagdollWeapons.

For inventory-backed items that define an Equip method, Equip is called to re-equip them; otherwise the weapon is re-given via self:Give.

Clip sizes and ammo counts are restored after giving.

After all weapons are restored, re-selects the previously active weapon (or ax_hands as a fallback).

Calls ClearRagdollWeapons when done.

Realm: server

Source: gamemode/framework/meta/sh_player.lua:308

ax.player.meta:Save()

Persists all player variables and data to the database.

Constructs a MySQL UPDATE query targeting the ax_players table, filtered by steamid64.

All registered player vars that declare a field in their schema are included; table values are serialised to JSON.

The data blob is always written as JSON.

Falls back to the registered default when a var has no value set.

Call this after any direct modification to axVars that bypasses the standard SetVar / SetData pathway.

Realm: server

Source: gamemode/framework/meta/sh_player.lua:538

ax.player.meta:SetFactionWhitelisted(iFactionID, bStatus)

Sets or clears the player's whitelist status for a given faction.

Updates the "whitelists" key in the player's data store.

Setting bStatus to true grants whitelist access; false removes it (the entry is set to nil).

Validates that iFactionID is a registered faction and that bStatus is a boolean before writing.

Prints an error and returns early on invalid input.

Realm: server

Parameters

Name Type Description
iFactionID number The numeric faction index to whitelist or un-whitelist.
bStatus boolean True to grant whitelist access, false to revoke it.

Source: gamemode/framework/meta/sh_player.lua:511

ax.player.meta:SetRagdolled(bRagdolled, bForced)

Sets the player's ragdoll state, creating or destroying a ragdoll dummy.

When bRagdolled is true, creates a prop_ragdoll entity at the player's position inheriting the player's model, skin, bodygroups, and materials.

The player is hidden and made non-solid while a repeating timer keeps their position synced to the ragdoll.

Weapons are stripped via StripWeaponsForRagdoll and stored for later restoration.

When bRagdolled is false (or any non-true value), the ragdoll dummy is removed, the player is restored to MOVETYPE_WALK, and RestoreRagdollWeapons is called.

Fires "CanPlayerRagdoll" before creating the ragdoll unless bForced is true;

returning false from the hook prevents ragdolling. Fires "OnPlayerRagdollCreated" after the dummy is spawned.

Returns the ragdoll entity on creation, false if blocked by the hook, or nil on error.

Realm: server

Parameters

Name Type Description
bRagdolled boolean True to ragdoll the player, false (or any non-true value) to un-ragdoll.
bForced boolean\|nil When true, skips the "CanPlayerRagdoll" hook check.

Returns

  • Entity|false|nil: The ragdoll entity, false if blocked by hook, or nil on failure.

Source: gamemode/framework/meta/sh_player.lua:384

ax.player.meta:SteamName()

Player meta functions

Returns the player's actual Steam display name, bypassing the character name override.

Delegates directly to GetNickInternal (the original GMod Nick method saved before the Parallax override).

Use this when you specifically need the Steam name rather than the in-character name.

Realm: shared

Returns

  • string: The player's Steam display name.

Source: gamemode/framework/meta/sh_player.lua:20

ax.player.meta:StripWeaponsForRagdoll()

Strips all weapons from the player and saves their state for later restoration.

Records each weapon's class, clip counts, ammo counts, and linked inventory item (resolved via GetWeaponInventoryItem).

For inventory-backed weapons that define an Unequip method, that method is called to mark the item as unequipped.

The active weapon class is stored in axRagdollActiveWeapon.

After recording, all weapons are removed via StripWeapons.

Call RestoreRagdollWeapons to re-give them.

Intended to be called as part of the ragdoll creation flow.

Realm: server

Source: gamemode/framework/meta/sh_player.lua:256

ax.player.meta:SyncRelay()

Syncs all relay data to this player.

Iterates ax.relay.data and calls SetRelay for every key/value pair in the "global" scope, then for every per-entity scope whose entity is still valid.

The false third argument to SetRelay suppresses the normal broadcast so each value is sent only to this player rather than all receivers.

Called when the player becomes ready to ensure they receive the full relay state.

Realm: shared

Source: gamemode/framework/meta/sh_player.lua:764

ax.player.meta:ToggleRagdoll(bForced)

Toggles the player's ragdoll state between ragdolled and un-ragdolled.

Reads the current "ragdolled" relay value and calls SetRagdolled with the inverse.

Passes bForced through to skip the "CanPlayerRagdoll" hook check.

Realm: server

Parameters

Name Type Description
bForced boolean\|nil When true, bypasses the "CanPlayerRagdoll" hook.

Source: gamemode/framework/meta/sh_player.lua:499

ax.player.meta:CanSeeZone(identifier)

Check if the player can see a specific zone (PVS/trace).

Realm: shared

Returns

  • boolean: True if player can see the zone

Usage

if client:CanSeeZone("Tower Overlook") then

Source: gamemode/modules/zones/meta/sh_player.lua:92

ax.player.meta:DominantZoneHasFlag(flagName, flagValue)

Check if the player's dominant zone has a specific flag.

Realm: shared

Returns

  • boolean: True if dominant zone has the flag

Usage

if client:DominantZoneHasFlag("safe", true) then

Source: gamemode/modules/zones/meta/sh_player.lua:152

ax.player.meta:GetCurrentZoneName()

Returns the player's dominant zone name.

Includes physical zones and visible PVS/trace zones.

Realm: shared

Returns

  • string|nil: Zone name or nil

Usage

local zoneName = client:GetCurrentZoneName()

Source: gamemode/modules/zones/meta/sh_player.lua:318

ax.player.meta:GetDistanceToZone(identifier)

Get distance to a specific zone's center/origin.

Realm: shared

Returns

  • number|nil: Distance or nil if zone not found

Usage

local dist = client:GetDistanceToZone("Safe Zone")

Source: gamemode/modules/zones/meta/sh_player.lua:293

ax.player.meta:GetDominantZone()

Get the dominant zone for the player.

Realm: shared

Returns

  • table|nil: The dominant zone spec or nil

Usage

local zone = client:GetDominantZone()

Source: gamemode/modules/zones/meta/sh_player.lua:51

ax.player.meta:GetDominantZoneData(key)

Get a specific data value from the player's dominant zone.

Realm: shared

Returns

  • any: The data value or nil

Usage

local music = client:GetDominantZoneData("music_track")

Source: gamemode/modules/zones/meta/sh_player.lua:184

ax.player.meta:GetHighestPriorityZone()

Get the highest priority zone the player is in.

This is the first zone returned by GetZones() since they're sorted by priority.

Realm: shared

Returns

  • table|nil: The highest priority zone or nil

Usage

local topZone = client:GetHighestPriorityZone()

Source: gamemode/modules/zones/meta/sh_player.lua:249

ax.player.meta:GetVisibleZones()

Get all visible (PVS/trace) zones for the player.

Realm: shared

Returns

  • table: Array of zone specs with weight field

Usage

local visible = client:GetVisibleZones()

Source: gamemode/modules/zones/meta/sh_player.lua:26

ax.player.meta:GetZoneBlend()

Get the full zone blend state for the player.

Realm: shared

Returns

  • table: Blend state with physical, visible, and dominant fields

Usage

local blend = client:GetZoneBlend()

Source: gamemode/modules/zones/meta/sh_player.lua:34

ax.player.meta:GetZoneCount()

Get the number of zones the player is currently in.

Realm: shared

Returns

  • number: Number of zones

Usage

local count = client:GetZoneCount()

Source: gamemode/modules/zones/meta/sh_player.lua:267

ax.player.meta:GetZoneData(key)

Get a specific data value from any zone the player is in (highest priority).

Realm: shared

Returns

  • any: The data value or nil

Usage

local spawn = client:GetZoneData("spawn_point")

Source: gamemode/modules/zones/meta/sh_player.lua:196

ax.player.meta:GetZoneNames()

Get all zone names the player is currently in.

Realm: shared

Returns

  • table: Array of zone names

Usage

local names = client:GetZoneNames()

Source: gamemode/modules/zones/meta/sh_player.lua:276

ax.player.meta:GetZones()

Get all physical zones the player is currently in.

Realm: shared

Returns

  • table: Array of zone specs, sorted by priority

Usage

local zones = client:GetZones()

Source: gamemode/modules/zones/meta/sh_player.lua:18

ax.player.meta:GetZonesByType(zoneType)

Get all zones of a specific type the player is in.

Realm: shared

Returns

  • table: Array of zone specs

Usage

local boxes = client:GetZonesByType("box")

Source: gamemode/modules/zones/meta/sh_player.lua:230

ax.player.meta:GetZonesWithFlag(flagName, flagValue)

Get all zones the player is in that have a specific flag.

Realm: shared

Returns

  • table: Array of zone specs

Usage

local pvpZones = client:GetZonesWithFlag("pvp", true)

Source: gamemode/modules/zones/meta/sh_player.lua:132

ax.player.meta:GetZoneTracking()

Get the player's zone tracking state.

Realm: shared

Returns

  • table|nil: Tracking state or nil

Usage

local state = client:GetZoneTracking()

Source: gamemode/modules/zones/meta/sh_player.lua:167

ax.player.meta:IsInMultipleZones()

Check if the player is in multiple zones.

Realm: shared

Returns

  • boolean: True if in more than one zone

Usage

if client:IsInMultipleZones() then

Source: gamemode/modules/zones/meta/sh_player.lua:258

ax.player.meta:IsInZone(identifier)

Check if the player is in a specific zone.

Realm: shared

Returns

  • boolean: True if player is in the zone

Usage

if client:IsInZone("Safe Zone") then

Source: gamemode/modules/zones/meta/sh_player.lua:72

ax.player.meta:IsInZoneType(zoneType)

Check if the player is in any zone of a specific type.

Realm: shared

Returns

  • boolean: True if in a zone of that type

Usage

if client:IsInZoneType("box") then

Source: gamemode/modules/zones/meta/sh_player.lua:213

ax.player.meta:IsInZoneWithFlag(flagName, flagValue)

Check if the player is in a zone with a specific flag.

Realm: shared

Returns

  • boolean: True if in a zone with the flag

Usage

if client:IsInZoneWithFlag("pvp", true) then

Source: gamemode/modules/zones/meta/sh_player.lua:114