Skip to content

Client

Base class for players.

The client, aka the Player, represents the base entity controlled by the physical player. A client can have more than one character attached, but a character can have no more and no less than 1 client attached.

Functions and meta-methods defined in Gmod outside of NutScript typically target the client.

Methods

Client:steamName ()
Client:steamName

Returns the players Steam name.

Returns:

string The player's Steam name.

See also:

Client:SteamName ()
Client:SteamName

Returns the players Steam name. Alias to Player:steamName().

Returns:

string The player's Steam name.

See also:

Client:Nick ()
Client:Nick

Returns the name of the player's character, or the player's Steam name if the character is not available. Alias to Player:Name().

Returns:

string The name of the player's character or the player's Steam name if no character is available.

See also:

Client:GetName ()
Client:GetName

Returns the name of the player's character, or the player's Steam name if the character is not available. Alias to Player:Name().

Returns:

string The name of the player's character or the player's Steam name if no character is available.

See also:

Client:forceSequence (sequence, callback, time, noFreeze)
Client:forceSequence

Forces the player to play a specific animation sequence.

Parameters:

string sequence Name of the sequence to play

function callback optional Function to call when sequence ends

number time optional Duration to play the sequence (defaults to sequence duration)

boolean noFreeze optional. default: false Whether to keep player movable during animation

Returns:

number or bool Duration of sequence if valid, false otherwise

Client:leaveSequence ()
Client:leaveSequence

Stops the player's current forced animation sequence.

Client:doGesture (a, b, c)
Client:doGesture

Performs a gesture animation and syncs it to other players.

Parameters:

integer a Gesture slot or activity

integer b Gesture animation ID

boolean c Whether to auto-restart the gesture

Client:getChar ()
Client:getChar

Returns the character associated with the player.

Returns:

table The character object associated with the player, or nil if no character is associated.

Client:Name ()
Client:Name

Returns the name of the player's character, or the player's Steam name if the character is not available.

Returns:

string The name of the player's character or the player's Steam name if no character is available.

Client:getClass ()
Client:getClass

Gets player's current class ID

Returns:

int Class ID if has character

Or

nil If no character

Client:getClassData ()
Client:getClassData

Gets player's current class data

Returns:

table Class definition table if has character and class

Or

nil If no character or class

Client:addMoney (amt)
Client:addMoney

Adds money to the player's character.

Parameters:

number amt Amount to add

Client:takeMoney (amt)
Client:takeMoney

Removes money from the player's character.

Parameters:

number amt Amount to subtract

Client:getMoney ()
Client:getMoney

Gets the amount of money the player's character has.

Returns:

int Amount of money

Client:canAfford (amount)
Client:canAfford

Checks if the player's character can afford a given amount.

Parameters:

number amount Amount to check

Returns:

bool True if the character has enough money

Player data methods

Client:getNutData (key, default)
Client:getNutData

Gets NutScript-specific player data

Parameters:

string key optional Specific data key to retrieve

vararg default Default value if key not found

Returns:

table All player data when key is true

Or

any Specific data value when key provided

Or

any Default value when key not found

Usage:

    1
2
    local playTime = client:getNutData("playTime", 0)
local allData = client:getNutData(true)

Client:syncVars ()
Client:syncVars

Synchronizes all networked variables to this client. Called when a player first spawns.

Client:setLocalVar (key, value)
Client:setLocalVar

Sets a networked variable that is only visible to this client.

Parameters:

string key Variable name

vararg value Variable value

Client:getLocalVar (key, default)
Client:getLocalVar

Retrieves a networked variable from a client. The clientside version of the function can only return data that was previously networked to the client. Returns a default value if the variable is not set.

Parameters:

string key The variable name

vararg default optional A fallback value to return if the key is not present

Returns:

vararg The stored value or the default

Client:loadNutData (callback)
Client:loadNutData

Loads persistent NutScript-specific data for the player from the database. If no data exists, inserts a new entry. Calls the callback with the result.

Parameters:

function callback A function to call with the loaded data table

Client:saveNutData ()
Client:saveNutData

Saves the player's NutScript-specific data to the database. Updates name, last join timestamp, and data blob.

Client:setNutData (key, value, noNetworking)
Client:setNutData

Sets a specific key in the player's persistent data and optionally sends it to the client.

Parameters:

string key The key to set

vararg value The value to store

boolean noNetworking optional. default: false If true, skip sending the value to the client

Client:hasWhitelist (faction)
Client:hasWhitelist

Checks if player has whitelist for a faction

Parameters:

number faction Faction ID to check

Returns:

bool Whether player is whitelisted

Usage:

    1
    if client:hasWhitelist(FACTION_OTA) then print("Whitelisted") end

Client:setWhitelisted (faction, whitelisted)
Client:setWhitelisted

Sets the player's whitelist status for a given faction. Stores whitelist info under the current schema namespace.

Parameters:

integer faction The faction index

boolean whitelisted Whether the player is whitelisted

Returns:

bool True if the faction was valid and updated, false otherwise

Client:getItems ()
Client:getItems

Gets all items from player's inventory

Returns:

table List of item objects if has character

Or

nil If no character or inventory

General Utility Methods

Provides various helper methods for player state, model analysis, weapon restrictions, and spatial queries.

Client:getPlayTime ()
Client:getPlayTime

Returns how many seconds the player has spent on the server.

Returns:

int Total play time in seconds

Client:isRunning ()
Client:isRunning

Checks if the player is moving faster than their walking speed.

Returns:

bool True if running

Client:isFemale ()
Client:isFemale

Checks if the player has a female model. Uses model name patterns and animation class.

Returns:

bool True if player model is recognized as female

Client:getItemDropPos ()
Client:getItemDropPos

Returns a good position in front of the player for an entity. Uses a forward trace and surface offset to avoid intersections.

Returns:

vector Position to drop item

Client:setRestricted (state, noMessage)
Client:setRestricted

Restricts or unrestricts the player from interaction and weapons. Removes weapons and disables input if restricted. Restores state on unrestrict.

Parameters:

boolean state True to restrict, false to unrestrict

boolean noMessage optional. default: false If true, disables restriction messages

Player Action Utilities

Provides helper functions for performing timed and conditional actions on players, such as progress bars and stare-based interactions.

Client:setAction (text, time, callback, startTime, finishTime)
Client:setAction

Sets a timed action for the player with a visual progress bar. Cancels any existing action timer if text is false.

Parameters:

vararg text Text (string) to display or false (bool) to cancel

number time optional. default: 5 Duration of the action in seconds

function callback optional Called when the action completes

number startTime optional Custom start time (default is CurTime())

number finishTime optional Custom finish time (default is start + time)

Client:doStaredAction (entity, callback, time, onCancel, distance)
Client:doStaredAction

Performs a timed action while the player stares at an entity. Cancels if the player looks away or either entity becomes invalid.

Parameters:

Entity entity The entity the player must look at

function callback Called on successful completion

number time Duration to stare

function onCancel optional Called if the stare is interrupted or cancelled

number distance optional. default: 96 Maximum trace distance the player may be from the entity

Ragdoll and Position Utilities

Adds ragdolling, stuck detection, and spatial logic for positioning and restoring players.

Client:isStuck ()
Client:isStuck

Checks if the player is stuck in geometry.

Returns:

bool True if the player is inside solid geometry

Client:createRagdoll (freeze)
Client:createRagdoll

Creates a ragdoll copy of the player at their current position.

Parameters:

boolean freeze optional. default: false Whether to freeze ragdoll physics

Returns:

entity The created ragdoll entity

Client:setRagdolled (state, time, getUpGrace)
Client:setRagdolled

Ragdolls or un-ragdolls the player. Handles weapon storing/restoring, positioning, and state.

Parameters:

boolean state True to ragdoll, false to unragdoll

number time optional Duration in seconds to stay ragdolled

number getUpGrace optional Grace period before reactivating player