nss_libs - Client Helper

Client helper contains all methods of inherited Shared helper.

Import client helper

lua

---@type NssLibsClientHelper
CLIENT_HELPER = exports.nss_libs:getClientHelper(GetCurrentResourceName())

Methods

`.getUniqueId()`

Returns string — a unique id.

lua

local unique_id = CLIENT_HELPER:getUniqueId()
print(unique_id)

`.getCurrentTimestamp()`

Returns number — the current timestamp from posix time in seconds.

lua

local timestamp = CLIENT_HELPER:getCurrentTimestamp()
print(timestamp) -- 1631533200

`.getCurrentMsTimestamp()`

Returns number — the current timestamp from posix time in milliseconds.

lua

local timestamp = CLIENT_HELPER:getCurrentMsTimestamp()
print(timestamp) -- 1631533200000

`.getCurrentServerTimestamp()`

This method is synchronous and will block the client thread until the server responds.

Asks the server for the current timestamp and returns it.

Important

Use with care as often you call this method, as often the server will be asked for the current timestamp.

Returns number — the current server timestamp in seconds.

lua

local timestamp = CLIENT_HELPER:getCurrentServerTimestamp()
print(timestamp) -- 1631533200

`.getAllActivePlayerIds()`

Returns NssLibsClientHelperPlayerIdItem[] — a list of all active player ids.

lua

local player_ids = CLIENT_HELPER:getAllActivePlayerIds()

for _, player_id in ipairs(player_ids) do
    print(player_id.client, player_id.server)
end

`.getPlayersInRadius(ped, radius)`

Param	Type	Default	Description
`ped`	`number?`	`nil`	The ped id to get the players in radius from. If `nil` the player ped will be used
`radius`	`number?`	`100.0`	The radius in meters (floated values are allowed)

Returns NssLibsClientHelperPlayerIdItem[] | nil — a list of all player ids in the radius or nil if no player is in the radius.

lua

local player_ids = CLIENT_HELPER:getPlayersInRadius(PlayerPedId(), 100.0)

for _, player_id in ipairs(player_ids) do
    print(player_id.client, player_id.server)
end

`.getPlayerClientIdsInRadius(ped, radius)`

Param	Type	Default	Description
`ped`	`number?`	`nil`	The ped id to get the players in radius from. If `nil` the player ped will be used
`radius`	`number?`	`100.0`	The radius in meters (floated values are allowed)

Returns number[] | nil — a list of all player client ids in the radius or nil if no player is in the radius.

lua

local client_player_ids = CLIENT_HELPER:getPlayerClientIdsInRadius(PlayerPedId(), 100.0)

for _, client_player_id in ipairs(client_player_ids) do
    print(client_player_id)
end

`.getPlayerServerIdsInRadius(ped, radius)`

Param	Type	Default	Description
`ped`	`number?`	`nil`	The ped id to get the players in radius from. If `nil` the player ped will be used
`radius`	`number?`	`100.0`	The radius in meters (floated values are allowed)

Returns number[] | nil — a list of all player server ids in the radius or nil if no player is in the radius.

lua

local server_player_ids = CLIENT_HELPER:getPlayerServerIdsInRadius(PlayerPedId(), 100.0)

for _, server_player_id in ipairs(server_player_ids) do
    print(server_player_id)
end

`.getNearestPlayersInRadius(ped, radius)`

Param	Type	Default	Description
`ped`	`number?`	`nil`	The ped id to get the players in radius from. If `nil` the player ped will be used
`radius`	`number?`	`100.0`	The radius in meters (floated values are allowed)

Returns NssLibsClientHelperPlayerIdItem | nil — the nearest player in the radius or nil if no player is in the radius.

lua

local server_player_ids = CLIENT_HELPER:getNearestPlayersInRadius(PlayerPedId(), 100.0)

if server_player_ids then
    print(server_player_ids.client, server_player_ids.server)
end

`.getInGameDate(format?)`

Param	Type	Default	Description
`format`	`string?`	`Config.DefaultDateFormat`	The format of the date string. Placeholders: D (day), M (month), Y (year)

Returns string — the current in-game date.

lua

local in_game_date = CLIENT_HELPER:getInGameDate('Y-M-D')
print(in_game_date) -- 1886-09-13

`.hasPlayers()`

Returns boolean — true if there are active players (including current active player) otherwise false.

lua

local has_players = CLIENT_HELPER:hasPlayers()

if has_players then
    print('There are active players')
else
    print('There are no active players')
end

`.dateToTimestamp(date_str, format?)`

Param	Type	Default	Description
`date_str`	`string`	—	The date string to convert
`format`	`string?`	`Config.DefaultDateFormat`	The format of the date string. Placeholders: D (day), M (month), Y (year)

Returns number — the timestamp derived from the date string in seconds (integer).

lua

local date_string = '2021-12-24'
local format = 'Y-M-D'

local timestamp = CLIENT_HELPER:dateToTimestamp(date_string, format)
print(timestamp)

`.getInGameDateTimestamp(format?)`

Param	Type	Default	Description
`format`	`string?`	`Config.DefaultDateFormat`	The format of the date string. Placeholders: D (day), M (month), Y (year)

Returns number — the current in-game date as timestamp in seconds (integer).

lua

local in_game_date_timestamp = CLIENT_HELPER:getInGameDateTimestamp('Y-M-D') -- Example in game date 1896-09-13
print(in_game_date_timestamp) -- 1631533200

`.getClientPlayerIdFromServer(server_player_id)`

This is a shorthand.

Param	Type	Default	Description
`server_player_id`	`number`	—	The server id of the player

Returns number — the client id of the player.

lua

local server_player_id = 1
local client_player_id = CLIENT_HELPER:getClientPlayerIdFromServer(server_player_id)
print(client_player_id)

`.getServerPlayerId()`

This is a shorthand.

Returns number — the server id of the current player.

lua

local server_player_id = CLIENT_HELPER:getServerPlayerId()
print(server_player_id)

`.timeout(callback, interval_in_ms)`

This method is asynchronous and will not block the client thread.

Param	Type	Default	Description
`callback`	`function`	—	The function to call after the interval
`interval_in_ms`	`number`	—	The interval in milliseconds

Returns function — a function to clear the timeout.

SimpleWith Clear

lua

-- Example: Timeout with 1000ms interval
CLIENT_HELPER:timeout(function()
    print('Timeout')
end, 1000)

-- Output after 1000ms: Timeout

lua

-- Example: Timeout with clear timeout
local clear_timeout = CLIENT_HELPER:timeout(function()
    print('Timeout')
end, 1000)

clear_timeout() -- Clear the timeout

-- Output after 1000ms: (nothing)

`.addEventHandler(event_name, callback, resource_name, on_destroy_callback?)`

Important

If the related resource is stopped, the event will be removed automatically.

Param	Type	Default	Description
`event_name`	`string`	—	The name of the event
`callback`	`function`	—	The function to call when the event is triggered. If it returns `false`, subsequent callbacks will not be called
`resource_name`	`string`	—	The name of the resource that is listening to the event
`on_destroy_callback`	`function?`	—	Called before the event handler is destroyed. If it returns `false` the handler will not be destroyed

Returns NssLibsSharedHelperEventHandlerApi — the event handler instance.

lua

local event_name = 'your_event_name'
local resource_name = GetCurrentResourceName()

local callback = function(...)
    print('Event ' .. tostring(event_name) .. ' for ' .. tostring(resource_name) .. 'is triggered:', ...)
end

---@type NssLibsSharedHelperEventHandlerApi
local event_handler_item = CLIENT_HELPER:addEventHandler(event_name, callback, resource_name)

TriggerEvent('your_event_name', 'Hello World')
-- Output: "Event your_event_name for your_resource_name is triggered: Hello World"

event_handler_item:disable()
TriggerEvent('your_event_name', 'Hello World 2')
-- Output: No output because the event handler is disabled

event_handler_item:destroy()
TriggerEvent('your_event_name', 'Hello World 3')
-- Output: No output because the event handler is destroyed

`.waitUntilLoadingsScreenEnds()`

This method is synchronous and will block the client thread until the loading screen ends.

Returns nothing.

lua

CLIENT_HELPER:waitUntilLoadingsScreenEnds()
print('Loading screen ends')
-- Continue here with the code after the loading screen ends

`.playAnimation(ped, dict, name, flag?)`

Plays the given animation on given ped.

Important

This method is asynchronous and will not block the client thread.

Param	Type	Default	Description
`ped`	`number`	—	The player ped id
`dict`	`string`	—	The animation dictionary
`name`	`string`	—	The animation name
`flag`	`number?`	`0`	The flag of the animation

Returns nothing.

lua

local ped = PlayerPedId()
local anim_dict = 'amb_misc@world_human_wash_face_bucket@table@female_a@idle_d'
local anim_name = 'idle_j'
local anim_flag = 0

CLIENT_HELPER:playAnimation(ped, anim_dict, anim_name, anim_flag)

`.requestAnimDict(dict)`

Requests the given animation dictionary.

Param	Type	Default	Description
`dict`	`string`	—	The animation dictionary

Returns boolean — true if the animation dict is requested successfully otherwise false.

lua

local anim_dict = 'amb_misc@world_human_wash_face_bucket@table@female_a@idle_d'

if not CLIENT_HELPER:requestAnimDict(anim_dict) then
  print('Failed to request animation dict')
else
  print('Animation dict requested successfully')
end

Objects