Client Helper

Client helper contains all methods of inherited Shared helper.

---

Import client helper

client.lua

---@type boolean
local DEBUG_ENABLED = true -- Set to true to enable debug logs

---@type NssGtaLibsClientHelper
CLIENT_HELPER = exports.nss_gta_libs:getClientHelper(GetCurrentResourceName(), DEBUG_ENABLED)

---

Methods

getUniqueId()

Returns a unique id as string.

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

---

getCurrentTimestamp()

Returns the current timestamp from posix time in seconds.

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

---

getCurrentMsTimestamp()

Returns the current timestamp from posix time in milliseconds.

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 the current server timestamp in seconds.

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

---

getAllActivePlayerIds()

Returns a list of all active player ids NssGtaLibsClientHelperPlayerIdItem[].

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)

• ped (number or nil) - The ped id to get the players in radius from. If nil the player ped will be used.

• radius (number or nil) - The radius in meters (floated values are allowed). If nil the default radius of 100.0 meters will be used.

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

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)

• ped (number or nil) - The ped id to get the players in radius from. If nil the player ped will be used.

• radius (number or nil) - The radius in meters (floated values are allowed). If nil the default radius of 100.0 meters will be used.

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

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)

• ped (number or nil) - The ped id to get the players in radius from. If nil the player ped will be used.

• radius (number or nil) - The radius in meters (floated values are allowed). If nil the default radius of 100.0 meters will be used.

• ignore_dead (boolean, optional) - If true dead players will be ignored. Default is false.

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

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

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

---

getNearestPlayersInRadius(ped, radius)

• ped (number or nil) - The ped id to get the players in radius from. If nil the player ped will be used.

• radius (number or nil) - The radius in meters (floated values are allowed). If nil the default radius of 100.0 meters will be used.

Returns the nearest player in the radius NssGtaLibsClientHelperPlayerIdItem or nil if no player is in the radius.

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)

• format (string, optional) - The format of the date string. Available placeholders are D (day), M (month), Y ( year). Default see Config.DefaultDateFormat.

Returns the current in-game date as string.

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

---

hasPlayers()

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

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)

• date_str (string) - The date string to convert.

• format (string, optional) - The format of the date string. Available placeholders are D (day), M (month), Y ( year). Default see Config.DefaultDateFormat.

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

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

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

---

getInGameDateTimestamp(format)

• format (string, optional) - The format of the date string. Available placeholders are D (day), M (month), Y ( year). Default see Config.DefaultDateFormat.

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

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.

• server_player_id (number) - The server id of the player.

Returns the client id of the player as number.

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 the server id of the current player as number.

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.

• callback (function) - The function to call after the interval.

• interval_in_ms (number) - The interval in milliseconds.

Returns a function to clear the timeout.

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

-- Output after 1000ms: Timeout

-- 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)

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

• event_name (string) - The name of the event.

• callback (function) - The function to call when the event is triggered.

  • If the callback returns false other additional callbacks registered after this callback will not be called.

• resource_name (string) - The name of the resource that is listening to the event.

• on_destroy_callback (function, optional) - Called before the event handler is destroyed. If the callback returns false the event handler will not be destroyed.

Returns a NssGtaLibsSharedHelperEventHandlerApi instance.

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 NssGtaLibsSharedHelperEventHandlerApi
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.

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.

• ped (number) - The player ped id.

• dict (string) - The animation dictionary.

• name (string) - The animation name.

• flag (number, optional) - The flag of the animation. Default is 0.

Returns nothing.

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.

• dict (string) - The animation dictionary.

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

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

NssGtaLibsClientHelperPlayerIdItem

• client (number) - The client id of the player.

• server (number) - The server id of the player.

• players(NssGtaLibsClientHelperPlayerIdItem[]) - The list of players in radius.

• nearest_player (NssGtaLibsClientHelperPlayerIdItem|nil) - The nearest player in radius.

---