nss_libs - Character

Wraps player characters from the VORP framework and provides a unified API for both server and client side. On the server, it exposes character data, currency management, player identifiers, and event listeners for group/job changes. On the client, it provides a listener for the currently selected character.

---

How to use

Server

local name_of_admin_group = 'admin'
local example_player_id = 99 -- The server player id of a joined player

---@type NssLibsCharacterApi
local character_api = exports.nss_libs:getCharacterApi(GetCurrentResourceName(), name_of_admin_group)

-- Get the character data of a player
---@type NssLibsCharacterItem|nil
local char_data = character_api:getCharData(example_player_id)
if char_data then
    print('Character name: ' .. char_data.full_name)
    print('Job: ' .. char_data.job)
    print('Is admin: ' .. tostring(char_data.is_admin))
end

-- Currency management
character_api:addMoney(example_player_id, 1000)
character_api:subMoney(example_player_id, 999)

if character_api:hasMoney(example_player_id, 1) then
    print('Player has at least $1')
end

character_api:addGold(example_player_id, 5)

-- Player identifiers
print(character_api:getSteamId(example_player_id))
print(character_api:getSteamProfileUrl(example_player_id))
print(character_api:getDiscordProfileUrl(example_player_id))
print(character_api:getRedmCharacterName(example_player_id))

-- Listen for job changes
character_api:onJobChange(function(_source, old_job, new_job)
    print('Player ' .. _source .. ' changed job from ' .. old_job .. ' to ' .. new_job)
end)

Client

---@type NssLibsClientCharacterApi
local char_api = exports.nss_libs:getClientCharacterApi(GetCurrentResourceName())

-- Listen for the currently selected character
char_api:listenSelectedCharacter(
    function(char_data)
        print('Character selected: ' .. tostring(char_data))
    end,
    function()
        print('Character listener destroyed.')
    end
)

---

Methods

exports.nss_libs:getCharacterApi(resource_name, name_of_admin_group)

Returns the server character API NssLibsCharacterApi for the given resource.

Param	Type	Default	Description
resource_name	string	—	The name of the resource that wants to use the API
name_of_admin_group	string	—	The VORP group name that is considered the admin group. Used to populate is_admin on NssLibsCharacterItem

---

NssLibsCharacterApi

getCharData(_source)

Returns the currently used VORP character of the player as a wrapped object.

Param	Type	Default	Description
_source	number	—	The server player ID

Returns NssLibsCharacterItem | nil — The character data, or nil if no character is found.

addGold(_source, amount)

Adds gold to the character.

Param	Type	Default	Description
_source	number	—	The server player ID
amount	number	—	The amount of gold to add

subGold(_source, amount)

Subtracts gold from the character.

Param	Type	Default	Description
_source	number	—	The server player ID
amount	number	—	The amount of gold to subtract

hasGold(_source, amount)

Checks if the character has at least the given amount of gold.

Param	Type	Default	Description
_source	number	—	The server player ID
amount	number	—	The required gold amount

Returns boolean — true if the character has enough gold, otherwise false.

addMoney(_source, amount)

Adds money to the character.

Param	Type	Default	Description
_source	number	—	The server player ID
amount	number	—	The amount of money to add

subMoney(_source, amount)

Subtracts money from the character.

Param	Type	Default	Description
_source	number	—	The server player ID
amount	number	—	The amount of money to subtract

hasMoney(_source, amount)

Checks if the character has at least the given amount of money.

Param	Type	Default	Description
_source	number	—	The server player ID
amount	number	—	The required money amount

Returns boolean — true if the character has enough money, otherwise false.

getIdentifiers(_source, refresh)

Returns all identifiers for the player.

Param	Type	Default	Description
_source	number	—	The server player ID
refresh	boolean?	false	If true, forces a re-read of identifiers instead of using the cached value

Returns NssLibsCharacterIdentifiers — The player identifiers object.

getSteamId(_source)

Returns the Steam ID of the player.

Param	Type	Default	Description
_source	number	—	The server player ID

Returns string — The Steam ID.

getSteamProfileUrl(_source)

Returns the Steam profile URL of the player.

Param	Type	Default	Description
_source	number	—	The server player ID

Returns string — The Steam profile URL.

getDiscordId(_source)

Returns the Discord ID of the player.

Param	Type	Default	Description
_source	number	—	The server player ID

Returns string — The Discord ID.

getDiscordProfileUrl(_source)

Returns the Discord profile URL of the player.

Param	Type	Default	Description
_source	number	—	The server player ID

Returns string — The Discord profile URL.

getIp(_source)

Returns the IP address of the player.

Param	Type	Default	Description
_source	number	—	The server player ID

Returns string — The IP address.

getRedmCharacterName(_source)

Returns the RedM player name as returned by GetPlayerName.

Param	Type	Default	Description
_source	number	—	The server player ID

Returns string — The RedM character name.

getFivmId(_source)

Returns the FiveM ID of the player.

Param	Type	Default	Description
_source	number	—	The server player ID

Returns string — The FiveM ID.

getCharacterByName(character_name)

Finds a character by their full name in the database.

Param	Type	Default	Description
character_name	string	—	The full name of the character (firstname + lastname)

WARNING

This method loads data from the database, not from the VORP cache. Changes to group or job that have not yet been persisted will not be reflected.

Returns NssLibsCharacterItem | nil — The character data, or nil if no character is found.

getCharacterByCharId(char_id)

Finds a character by their VORP charidentifier in the database.

Param	Type	Default	Description
char_id	number	—	The VORP character identifier

WARNING

This method loads data from the database, not from the VORP cache. Changes to group or job that have not yet been persisted will not be reflected.

Returns NssLibsCharacterItem | nil — The character data, or nil if no character is found.

getSteamIdOfChar(char_id)

Returns the Steam ID for a given character ID. Uses a cache to avoid repeated DB lookups.

Param	Type	Default	Description
char_id	string | number	—	The VORP character identifier

Returns string | nil — The Steam ID, or nil if not found.

getSourceOfChar(char_id)

Returns the server player ID for a given character ID by iterating over all active players.

Param	Type	Default	Description
char_id	string | number	—	The VORP character identifier

Returns number | nil — The server player ID, or nil if the character is not currently online.

onGroupChange(cb)

Registers a listener that is called whenever a player's VORP group changes.

Param	Type	Default	Description
cb	NssLibsCharacterOnGroupChangeCallback	—	function(_source, old_group, new_group)

Returns NssLibsSharedHelperEventHandlerApi — The event handler instance.

onJobChange(cb)

Registers a listener that is called whenever a player's job changes.

Param	Type	Default	Description
cb	NssLibsCharacterOnJobChangeCallback	—	function(_source, old_job, new_job)

Returns NssLibsSharedHelperEventHandlerApi — The event handler instance.

onJobGradeChange(cb)

Registers a listener that is called whenever a player's job grade changes.

Param	Type	Default	Description
cb	NssLibsCharacterOnJobGradeChangeCallback	—	function(_source, old_grade, new_grade)

Returns NssLibsSharedHelperEventHandlerApi — The event handler instance.

---

NssLibsCharacterItem

Represents a wrapped VORP character with additional computed properties.

Properties

Param	Type	Default	Description
char_id	number	—	The VORP character identifier
group	string	—	The VORP group of the character (e.g. 'user', 'admin')
job	string	—	The current job of the character
job_grade	number	—	The current job grade of the character
firstname	string	—	The first name of the character
lastname	string	—	The last name of the character
full_name	string	—	The full name of the character (firstname .. ' ' .. lastname)
money	number	—	The current money of the character
is_admin	boolean	—	true if the character's group matches the configured admin group
server_player_id	number | nil	—	The server player ID if the character is currently online, otherwise nil

char_data:hasJob(job)

Checks if the character currently has the given job (exact match).

Param	Type	Default	Description
job	string	—	The job identifier to check

Returns boolean — true if the character has this job, otherwise false.

char_data:hasJobGrade(grade)

Checks if the character's job grade is greater than or equal to the given grade.

Param	Type	Default	Description
grade	number	—	The minimum required job grade

Returns boolean — true if job_grade >= grade, otherwise false.

char_data:hasOneOfTheJobs(jobs)

Checks if the character has one of the given jobs. Supports both a plain array of job names and a map of job names to minimum required grades.

Param	Type	Default	Description
jobs	string[] | table	—	A list of job identifiers, or a table mapping job names to minimum required grades

Array form

-- Any of these jobs qualifies
char_data:hasOneOfTheJobs({ 'sheriff', 'ranger', 'bounty_hunter' })

Map form

-- Job qualifies only if the character also meets the minimum grade
char_data:hasOneOfTheJobs({ sheriff = 2, ranger = 1 })

Returns boolean — true if the character has at least one of the given jobs (respecting grade requirements), otherwise false.

char_data:isEmployed()

Checks if the character currently has any job assigned.

Returns boolean — true if the character has a job, otherwise false.

---

exports.nss_libs:getClientCharacterApi(resource_name)

Returns the client character API NssLibsClientCharacterApi for the given resource.

Param	Type	Default	Description
resource_name	string	—	The name of the resource that wants to use the API

---

NssLibsClientCharacterApi

char_api:listenSelectedCharacter(callback, on_destroy_callback)

Registers a listener that is called when the currently selected character is loaded via the framework bridge. The callback fires immediately with the current character if one is already selected.

Param	Type	Default	Description
callback	function	—	Called with the character data when a character is selected
on_destroy_callback	function	—	Called when the listener is destroyed

Returns NssLibsSharedHelperEventHandlerApi — The event handler instance.

char_api:resetAllSelectedCharacterListener()

Removes all character selection listeners registered by this resource.

Returns NssLibsClientCharacterApi — The API instance for chaining.

char_api:resetApi()

Resets the framework bridge for this resource. Use this if the resource needs to re-initialise its connection to the character system.

Returns NssLibsClientCharacterApi — The API instance for chaining.

---

Objects / Types

NssLibsCharacterIdentifiers

Contains all player identifiers as returned by the RedM identifier system.

Param	Type	Default	Description
steam	string	—	Steam identifier
license	string	—	Rockstar license identifier
discord	string	—	Discord identifier
ip	string	—	IP address
fivem	string	—	FiveM identifier
xbl	string	—	Xbox Live identifier
live	string	—	Microsoft Live identifier
license2	string	—	Secondary Rockstar license identifier

NssLibsCharacterOnGroupChangeCallback

---@alias NssLibsCharacterOnGroupChangeCallback fun(_source: number, old_group: string, new_group: string)

NssLibsCharacterOnJobChangeCallback

---@alias NssLibsCharacterOnJobChangeCallback fun(_source: number, old_job: string, new_job: string)

NssLibsCharacterOnJobGradeChangeCallback

---@alias NssLibsCharacterOnJobGradeChangeCallback fun(_source: number, old_grade: number, new_grade: number)