Skip to content

meta/sh_character

Source: gamemode/framework/meta/sh_character.lua

Returns a human-readable string representation of the character.

Documented functions: 19

Functions

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.