Character

Contains information about a player's current game state.

Characters are a fundamental object type in Helix. They are distinct from players, where players are the representation of a person's existence in the server that owns a character, and their character is their currently selected persona. All the characters that a player owns will be loaded into memory once they connect to the server. Characters are saved during a regular interval, and during specific events (e.g when the owning player switches away from one character to another).

They contain all information that is not persistent with the player; names, descriptions, model, currency, etc. For the most part, you'll want to keep all information stored on the character since it will probably be different or change if the player switches to another character. An easy way to do this is to use ix.char.RegisterVar to easily create accessor functions for variables that automatically save to the character object.

Functions

Character:AddBoost(boostID, attribID, boostAmount)

Temporarily increments one of this character's attributes. Useful for things like consumable items.

Parameters

boostID string
Unique ID to use for the boost to remove it later

attribID string
Name of the attribute to boost

boostAmount number
Amount to increase the attribute by

Character:Ban(time)

Forces a player off their current character, and prevents them from using the character for the specified amount of time.

Parameters

time number optional
Amount of seconds to ban the character for. If left as nil, the character will be banned permanently

Character:GetAttribute(key, default)

Returns the current value of an attribute. This is only valid on the server and owning client.

Parameters

key string
Name of the attribute to get

default number
Value to return if the attribute doesn't exist

Returns

number
Value of the attribute

Character:GetBoost(attribID)

Returns all boosts that this character has for the given attribute. This is only valid on the server and owning client.

Parameters

attribID string
Name of the attribute to find boosts for

Returns

table
Table of boosts that this character has for the attribute

OR

nil
If the character has no boosts for the given attribute

Character:GetBoosts()

Returns all boosts that this character has. This is only valid on the server and owning client.

Returns

table
Table of boosts this character has

Character:GetClass()

Returns this character's current class.

Returns

number
Index of the class this character is in

Character:GetCreateTime()

Returns the Unix timestamp of when this character was created (i.e the value of os.time() at the time of creation).

Returns

number
Unix timestamp of when this character was created

Character:GetData(key, default)

Returns a data field set on this character. If it doesn't exist, it will return the given default or nil. This is only valid on the server and the owning client.

Parameters

key string
Name of the field that's holding the data

default
Value to return if the given key doesn't exist, or is nil

Returns

any
Data stored in the field

OR

nil
If the data doesn't exist, or is nil

Character:GetDescription()

Returns this character's physical description.

Returns

string
This character's current description

Character:GetFaction()

Returns this character's faction.

Returns

number
Index of the faction this character is currently in

Character:GetFlags()

Returns all of the flags this character has.

Returns

string
Flags this character has represented as one string. You can access individual flags by iterating through the string letter by letter

Character:GetID()

Returns this character's database ID. This is guaranteed to be unique.

Returns

number
Unique ID of character

Character:GetInventory()

Returns this character's associated Inventory object.

Returns

Inventory
This character's inventory

Character:GetLastJoinTime()

Returns the Unix timestamp of when this character was last used by its owning player.

Returns

number
Unix timestamp of when this character was last used

Character:GetModel()

Returns this character's model.

Returns

string
This character's current model

Character:GetMoney()

Returns this character's money. This is only valid on the server and the owning client.

Returns

number
Current money of this character

Character:GetName()

Returns this character's name

Returns

string
This character's current name

Character:GetPlayer()

Returns the player that owns this character.

Returns

player
Player that owns this character

Character:GetSchema()

Returns the schema that this character belongs to. This is useful if you are running multiple schemas off of the same database, and need to differentiate between them.

Returns

string
Schema this character belongs to

Character:GetSteamID()

Returns the 64-bit Steam ID of the player that owns this character.

Returns

string
Owning player's Steam ID

Character:GiveFlags(flags)

Adds a flag to the list of this character's accessible flags. This does not overwrite existing flags.

Parameters

flags string
Flag(s) this character should be given

Example Usage

character:GiveFlags("pet")
 -- gives p, e, and t flags to the character

See Also

HasFlags

Character:HasFlags(flags)

Returns true if the character has the given flag(s).

Parameters

flags string
Flag(s) to check access for

Returns

bool
Whether or not this character has access to the given flag(s)

Character:JoinClass(class)

Makes this character join a class. This automatically calls KickClass for you.

Parameters

class number
Index of the class to join

Returns

bool
Whether or not the character has successfully joined the class

Character:Kick()

Forces a player off their current character, and sends them to the character menu to select a character.

Character:KickClass()

Kicks this character out of the class they are currently in.

Character:RemoveBoost(boostID, attribID)

Removes a temporary boost from this character.

Parameters

boostID string
Unique ID of the boost to remove

attribID string
Name of the attribute that was boosted

Character:Save(callback)

Saves this character's info to the database.

Parameters

callback function default: nil
Function to call when the save has completed.

Example Usage

ix.char.loaded[1]:Save(function()
	print("done!")
end)
> done! -- after a moment

Character:SetAttrib(key, value)

Sets the value of an attribute for this character.

Parameters

key string
Name of the attribute to update

value number
New value for the attribute

Character:SetData(key, value)

Sets a data field on this character. This is useful for storing small bits of data that you need persisted on this character. This is networked only to the owning client. If you are going to be accessing this data field frequently with a getter/setter, consider using ix.char.RegisterVar instead.

Parameters

key string
Name of the field that holds the data

value
Any value to store in the field, as long as it's supported by GMod's JSON parser

Character:SetDescription(description)

Sets this character's physical description. This is automatically networked.

Parameters

description string
New description for this character

Character:SetFaction(faction)

Sets this character's faction. Note that this doesn't do the initial setup for the player after the faction has been changed, so you'll have to update some character vars manually.

Parameters

faction number
Index of the faction to transfer this character to

Character:SetFlags(flags)

Sets this character's accessible flags. Note that this method overwrites all flags instead of adding them.

Parameters

flags string
Flag(s) this charater is allowed to have

See Also

GiveFlags

Character:SetModel(model)

Sets this character's model. This sets the player's current model to the given one, and saves it to the character. It is automatically networked.

Parameters

model string
New model for the character

Character:SetMoney(money)

Sets this character's current money. Money is only networked to the player that owns this character.

Parameters

money number
New amount of money this character should have

Character:SetName(name)

Sets this character's name. This is automatically networked.

Parameters

name string
New name for the character

Character:Sync(receiver)

Internal

This is an internal function! You are able to use it, but you risk unintended side effects if used incorrectly.

Networks this character's information to make the given player aware of this character's existence. If the receiver is not the owner of this character, it will only be sent a limited amount of data (as it does not need anything else). This is done automatically by the framework.

Parameters

receiver Player default: nil
Player to send the information to. This will sync to all connected players if set to nil.

Character:TakeFlags(flags)

Removes this character's access to the given flags.

Parameters

flags string
Flag(s) to remove from this character

Example Usage

-- for a character with "pet" flags
character:TakeFlags("p")
-- character now has e, and t flags

Character:UpdateAttrib(key, value)

Increments one of this character's attributes by the given amount.

Parameters

key string
Name of the attribute to update

value number
Amount to add to the attribute

Character:__eq(other)

Returns true if this character is equal to another character. Internally, this checks character IDs.

Parameters

other Character
Character to compare to

Returns

bool
Whether or not this character is equal to the given character

Example Usage

print(ix.char.loaded[1] == ix.char.loaded[2])
 > false

Character:__tostring()

Returns a string representation of this character

Returns

string
String representation

Example Usage

print(ix.char.loaded[1])
 > "character[1]"