Skip to content

Character Meta

All documented character metatable methods discovered across framework and module source files.

Documented methods: 29  ·  Realm: server, shared

Methods

character:__tostring()

Returns a human-readable string representation of the character.

Format: "Character [id][name]". Useful for debug output and logging.

Realm: shared

Returns

  • string: A formatted string identifying this character.

Source: gamemode/framework/meta/sh_character.lua:19

character:AddCurrency(amount, uniqueID, bNoNetworking, recipients)

Add an amount of currency to this character.

Clamps the result to be non-negative.

Realm: shared

Parameters

Name Type Description
amount number The amount to add (can be negative to subtract)
uniqueID string The unique identifier of the currency (defaults to "default")
bNoNetworking bool Optional flag to disable networking (server only)
recipients table Optional specific recipients for networking (server only)

Returns

  • number: The new total amount of currency

Usage

character:AddCurrency(500, "default")

Source: gamemode/modules/currencies/meta/sh_character.lua:65

character:AddMoney(amount, uniqueID, bNoNetworking, recipients)

Add default (alias for AddCurrency with "default").

Realm: shared

Parameters

Name Type Description
amount number The amount to add
bNoNetworking bool Optional flag to disable networking (server only)
recipients table Optional specific recipients for networking (server only)

Returns

  • number: The new total amount of default

Usage

character:AddMoney(500)

Source: gamemode/modules/currencies/meta/sh_character.lua:159

character:GetBodygroup(index)

Returns the value of a bodygroup index for this character.

Looks up the bodygroup value in the character's data table under "bodygroups" keyed by the index as a string. Returns 0 if no value is set for that index.

Realm: shared

Parameters

Name Type Description
index number The bodygroup index to query.

Returns

  • number: The bodygroup value, or 0 if not set.

Source: gamemode/framework/meta/sh_character.lua:121

character:GetBodygroupName(name)

Returns the value of a bodygroup by name for this character.

Looks up the bodygroup value in the character's data table under "bodygroups" keyed by the name string. Returns 0 if no value is set for that name.

Realm: shared

Parameters

Name Type Description
name string The bodygroup name to query.

Returns

  • number: The bodygroup value, or 0 if not set.

Source: gamemode/framework/meta/sh_character.lua:131

character:GetBodyGroups()

Returns a table of all bodygroup values for this character.

Returns the entire "bodygroups" table from the character's data, or an empty table if none is set. The keys are bodygroup indices as strings or bodygroup names, and the values are the corresponding bodygroup values as numbers. This is useful for iterating all bodygroups or when you need the full set of bodygroup values for saving or transferring to another character.

Realm: shared

Returns

  • table: A table of bodygroup values keyed by index (as strings) and name. Values are numbers. Returns an empty table if no bodygroups are set.

Source: gamemode/framework/meta/sh_character.lua:140

character:GetClassData()

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

Delegates to ax.class:Get using self.vars.class. Returns nil when no class is assigned or the class is not registered.

Realm: shared

Returns

  • table|nil: The class definition, or nil if not found.

Source: gamemode/framework/meta/sh_character.lua:86

character:GetCurrency(uniqueID)

Get the amount of a specific currency this character has.

Realm: shared

Parameters

Name Type Description
uniqueID string\|nil The unique identifier of the currency (defaults to "default")

Returns

  • number: The amount of currency, or 0 if invalid currency or character

Usage

local money = character:GetCurrency("default")

Source: gamemode/modules/currencies/meta/sh_character.lua:19

character:GetFactionData()

Returns the faction definition table for this character's faction.

Delegates to ax.faction:Get using self.vars.faction. Returns nil when the faction index is unset or not registered.

Realm: shared

Returns

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

Source: gamemode/framework/meta/sh_character.lua:78

character:GetID()

Returns the character's unique database ID.

This is the primary key from the ax_characters table. Temporary bot characters use the owner's SteamID64 as their ID instead.

Realm: shared

Returns

  • number: The character's numeric ID.

Source: gamemode/framework/meta/sh_character.lua:27

character:GetInventory()

Returns the inventory instance associated with this character.

Looks up ax.inventory.instances using the character's stored inventory ID.

Returns nil when the inventory has not been loaded or the ID is 0.

Aliased as character.GetInv.

Realm: shared

Returns

  • table|nil: The inventory instance, or nil if not loaded.

Source: gamemode/framework/meta/sh_character.lua:45

character:GetInventoryID()

Returns the numeric ID of the character's inventory.

This is the database ID of the associated inventory row. Returns 0 when no inventory has been assigned (e.g. freshly created characters before an inventory is allocated). Aliased as character.GetInvID.

Realm: shared

Returns

  • number: The inventory ID, or 0 if none is set.

Source: gamemode/framework/meta/sh_character.lua:55

character:GetMoney(uniqueID)

Convenience aliases for the default "default" currency

These methods use "default" as the default currency ID

Get default amount (alias for GetCurrency with "default").

Realm: shared

Returns

  • number: The amount of default

Usage

local default = character:GetMoney()

Source: gamemode/modules/currencies/meta/sh_character.lua:138

character:GetOwner()

Returns the player entity that owns this character.

Returns the player stored in self.player at load time. May be nil for offline or bot characters that have been unloaded. Aliased as GetPlayer, GetPly, GetUser, and GetClient.

Realm: shared

Returns

  • Player|nil: The owning player entity, or nil if unloaded.

Source: gamemode/framework/meta/sh_character.lua:65

character:GetRankData()

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

Delegates to ax.rank:Get using self.vars.rank. Returns nil when no rank is assigned or the rank is not registered.

Realm: shared

Returns

  • table|nil: The rank definition, or nil if not found.

Source: gamemode/framework/meta/sh_character.lua:94

character:GetVars()

Returns the character's vars table containing all stored variable values.

The vars table holds every registered character variable (name, faction, model, description, etc.). Modifications to this table are live but not automatically persisted — call Save() to write changes to the database.

Realm: shared

Returns

  • table: The character's vars table.

Source: gamemode/framework/meta/sh_character.lua:35

character:GiveFlags(flags)

Grants one or more flags to the character.

Iterates each letter in flags. For each letter:

  • Skips letters whose flag data is not registered in ax.flag.
  • Skips letters the character already holds (idempotent).
  • Appends the letter to the character's stored flags string.
  • Calls flagData:OnGiven(character) if the flag defines it.
  • Fires the "CharacterFlagGiven" hook with the character and letter.

After all letters are processed, calls Save() if any new flag was added. Returns immediately for empty or non-string input.

Realm: server

Parameters

Name Type Description
flags string A string of single-character flag letters to grant.

Source: gamemode/framework/meta/sh_character.lua:192

character:HasCurrency(amount, uniqueID)

Check if this character has at least the specified amount of currency.

Realm: shared

Parameters

Name Type Description
amount number The amount to check
uniqueID string The unique identifier of the currency (defaults to "default")

Returns

  • bool: True if the character has at least this amount, false otherwise

Usage

if (character:HasCurrency(1000, "default")) then
    print("Character is wealthy")
end

Source: gamemode/modules/currencies/meta/sh_character.lua:119

character:HasFlags(flags)

Returns true if the character holds all of the specified flags.

Iterates each letter in flags and checks whether it appears in the character's stored flags string (via a case-sensitive FindString call).

Returns false as soon as any letter is missing. An empty flags string always returns true.

Realm: shared

Parameters

Name Type Description
flags string A string of single-character flag letters to test for (e.g. "acf" checks for flags a, c, and f).

Returns

  • boolean: True if every flag letter is present, false otherwise.

Source: gamemode/framework/meta/sh_character.lua:104

character:HasMoney(amount, uniqueID)

Check if character has default (alias for HasCurrency with "default").

Realm: shared

Parameters

Name Type Description
amount number The amount to check

Returns

  • bool: True if the character has at least this amount

Usage

if (character:HasMoney(1000)) then
    print("Can afford purchase")
end

Source: gamemode/modules/currencies/meta/sh_character.lua:181

character:Save()

Persists all character variables and data to the database.

Constructs a MySQL UPDATE query targeting the ax_characters table, filtering by the character's ID. All registered character vars that declare a field in their schema are included; table values are serialised to JSON. The data blob (arbitrary key/value store) 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 self.vars that bypasses the standard SetVar / SetData pathway.

Realm: server

Source: gamemode/framework/meta/sh_character.lua:293

character:SetBodygroup(index, value)

Sets a bodygroup on the character's player model and persists it.

Immediately applies the bodygroup to the owning player (if online) via Player:SetBodygroup, then stores the value in the character's data under "bodygroups" keyed by the numeric index (as a string) and saves via SetData. The stored value is reapplied when the character loads.

Realm: server

Parameters

Name Type Description
index number The bodygroup index to set.
value number The bodygroup value to apply.

Source: gamemode/framework/meta/sh_character.lua:150

character:SetBodygroupName(name, value)

Sets a bodygroup by name on the character's player model and persists it.

Resolves the bodygroup name to an index via Player:FindBodygroupByName and applies it on the owning player if online. Stores the value in the character's data under "bodygroups" keyed by the name string, so it can be reapplied by name on model load. Prefer this over SetBodygroup when working with named bodygroups to avoid hardcoding indices.

Realm: server

Parameters

Name Type Description
name string The bodygroup name as defined in the model.
value number The bodygroup value to apply.

Source: gamemode/framework/meta/sh_character.lua:167

character:SetCurrency(amount, uniqueID, bNoNetworking, recipients)

Set the amount of a specific currency for this character.

Clamps the value to be non-negative. Use AddCurrency or TakeCurrency for modifications.

Realm: shared

Parameters

Name Type Description
amount number The amount to set
uniqueID string The unique identifier of the currency (defaults to "default")
bNoNetworking bool Optional flag to disable networking (server only)
recipients table Optional specific recipients for networking (server only)

Usage

character:SetCurrency(1000, "default")

Source: gamemode/modules/currencies/meta/sh_character.lua:38

character:SetFlags(flags)

Replaces the character's entire flag set with the given flags.

Diffs the current flags against flags: letters present in the current set but absent from flags are removed via TakeFlags (triggering their OnTaken callbacks). The stored flags are then set to the new string and saved. Finally, GiveFlags is called for each letter in flags to trigger OnGiven callbacks for newly granted flags. Returns immediately for non-string input.

Realm: server

Parameters

Name Type Description
flags string The complete new flag string to assign to the character. Letters not currently held will be granted; letters held but not present in this string will be revoked.

Source: gamemode/framework/meta/sh_character.lua:268

character:SetMoney(amount, uniqueID, bNoNetworking, recipients)

Set default amount (alias for SetCurrency with "default").

Realm: shared

Parameters

Name Type Description
amount number The amount to set
bNoNetworking bool Optional flag to disable networking (server only)
recipients table Optional specific recipients for networking (server only)

Usage

character:SetMoney(1000)

Source: gamemode/modules/currencies/meta/sh_character.lua:148

character:TakeCurrency(amount, uniqueID)

Remove an amount of currency from this character.

Will not go below zero. Returns false if the character doesn't have enough.

Realm: shared

Parameters

Name Type Description
amount number The amount to remove (must be positive)
uniqueID string The unique identifier of the currency (defaults to "default")

Returns

  • bool: True if the full amount was taken, false if insufficient funds

Usage

if (character:TakeCurrency(100, "default")) then
    print("Purchased item")
else
    print("Not enough default")
end

Source: gamemode/modules/currencies/meta/sh_character.lua:93

character:TakeFlags(flags)

Removes one or more flags from the character.

Iterates each letter in flags. For each letter:

  • Skips letters whose flag data is not registered in ax.flag.
  • Skips letters the character does not currently hold (idempotent).
  • Removes the letter from the character's stored flags string via string.Replace.
  • Calls flagData:OnTaken(character) if the flag defines it.
  • Fires the "CharacterFlagTaken" hook with the character and letter.

After all letters are processed, calls Save() if any flag was removed.

Returns immediately for empty or non-string input.

Realm: server

Parameters

Name Type Description
flags string A string of single-character flag letters to remove.

Source: gamemode/framework/meta/sh_character.lua:233

character:TakeMoney(amount, uniqueID)

Remove default (alias for TakeCurrency with "default").

Realm: shared

Parameters

Name Type Description
amount number The amount to remove

Returns

  • bool: True if successful, false if insufficient funds

Usage

if (character:TakeMoney(100)) then
    print("Purchase successful")
end

Source: gamemode/modules/currencies/meta/sh_character.lua:170