Skip to content

ax.player.meta

Source: gamemode/framework/meta/sh_player.lua

Player meta functions

Documented functions: 28

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.

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

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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

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

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.