ClientEvent

This is a library for sending events to the client in synchronous and asynchronous ways optionally waiting for a response.

Example

Client Listener

-- Gets the client listener api.
---@type ClientListenerApi
client_listener_api = exports.nss_libs:getClientListenerApi(GetCurrentResourceName())

-- Register a listener for the event "test" and return the result.
---@param _source number The identifier of the client that fired the event.
---@param times number Example argument.
client_listener_api:addListener('test', function(_source, times)

    local result = {}

    for _ = 1, times do
        table.insert(result, 'Hello from client')
    end

    print('Client Result', table.unpack(result))

    return result
end)

Server Fire

-- Gets the client event api.
---@type ClientEventApi
client_event_api = exports.nss_libs:getClientEventApi(GetCurrentResourceName())

Citizen.CreateThread(function()

    local player_id = 1
    local times = 3

    -- Example awaits result and blocks the thread as long as no result response is received.
    -- The client event works like a synchronous function call.
    -- It is not allowed to fire this to all players in one call.
    local data = client_event_api:await("test", player_id, times)
    print('Client Result', table.unpack(data))

    -- The callback is executed async on client response.
    -- Example does not await result and does not block the thread.
    -- It is not allowed to fire this to all players in one call.
    ---@param response_data any|table
    client_event_api:async("test", player_id, function(response_data)
        print('Client Result', table.unpack(response_data))
    end, times)

    -- Example fires a global client event and does not wait for a result.
    -- Example does not await result and does not block the thread.
    -- If player_id is nil or -1 the event will be fired to all players.
    client_event_api:fire("test", player_id, times)

    -- Example fires a global client event to all players and does not wait for a result.
    -- Example does not await result and does not block the thread.
    client_event_api:fireToAll("test", times)

end)

---

Methods (Client)

exports.nss_libs:getClientListenerApi(resourceName)

Gets the client listener API instance scoped to the calling resource.

Param	Type	Default	Description
resourceName	string	—	The name of the calling resource

Returns ClientListenerApi — The client listener API

---

:addListener(eventName, callback)

Registers a listener for the given event name.

Param	Type	Default	Description
eventName	string	—	The event name to listen for
callback	function(_source, ...)	—	Handler receiving the source player id and event arguments

---

Methods (Server)

exports.nss_libs:getClientEventApi(resourceName)

Gets the client event API instance scoped to the calling resource.

Param	Type	Default	Description
resourceName	string	—	The name of the calling resource

Returns ClientEventApi — The client event API

---

:await(eventName, playerId, ...)

Fires an event to a specific client and blocks the thread until a response is received.

Param	Type	Default	Description
eventName	string	—	The event name to fire
playerId	number	—	The target player id
...	any	—	Additional arguments passed to the client listener

WARNING

It is not allowed to fire this to all players in one call.

Returns any|table — The response data from the client

---

:async(eventName, playerId, callback, ...)

Fires an event to a specific client and executes the callback asynchronously on response without blocking the thread.

Param	Type	Default	Description
eventName	string	—	The event name to fire
playerId	number	—	The target player id
callback	function(response_data)	—	Called with the response data
...	any	—	Additional arguments passed to the client listener

WARNING

It is not allowed to fire this to all players in one call.

---

:fire(eventName, playerId, ...)

Fires an event to a client without waiting for a result.

Param	Type	Default	Description
eventName	string	—	The event name to fire
playerId	number?	—	The target player id. If nil or -1 the event fires to all players
...	any	—	Additional arguments passed to the client listener

---

:fireToAll(eventName, ...)

Fires an event to all players without waiting for a result.

Param	Type	Default	Description
eventName	string	—	The event name to fire
...	any	—	Additional arguments passed to the client listener