ServerEvent

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

Communication Example

Client Fire

-- Gets the server event api.
---@type ServerEventApi
server_event_api = exports.nss_libs:getServerEventApi(GetCurrentResourceName())

Citizen.CreateThread(function()

    local times = 3

    -- Example awaits result and blocks the thread as long as no result response is received.
    -- The server event works like a synchronous function call.
    local data = server_event_api:await("test", times)
    print('Client Result', table.unpack(data))

    -- The callback is executed async on server response.
    -- Example does not await result and does not block the thread.
    ---@param response_data any|table
    server_event_api:async("test", function(response_data)
        print('Client Result', table.unpack(response_data))
    end, times)

    -- Example fires a global server event and does not wait for a result.
    -- Example does not await result and does not block the thread.
    server_event_api:fire("test", times)

end)

Server Listener

-- Gets the server listener api.
---@type ServerListenerApi
client_listener_api = exports.nss_libs:getServerListenerApi(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 server')
    end

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

    return result
end)

---

"On Server Ready" Example

Executes callback on client side if the server triggers that he is ready.

Client

-- Gets the server event api.
---@type ServerEventApi
server_event_api = exports.nss_libs:getServerEventApi(GetCurrentResourceName())

Citizen.CreateThread(function()

    ---@type NssLibServerEventApiOnServerReadyCallback
    local on_server_ready = function(timout, ...)

        if timout == true then
            print('Server is not ready within 10 seconds')
            return
        end

        print('Server is ready')

        -- Do your stuff here. E.g. call the run() function of your main script.
    end

    local interval_in_ms = 1000 -- Optional, checking interval_in_ms in ms. Default is 1000ms (1s).
    local timeout_in_ms = 10000 -- Optional, timeout_in_ms in ms. Default is 30000ms (30s).

    server_event_api:onServerReady(on_server_ready, interval_in_ms, timeout_in_ms)
end)

Server

-- Gets the server listener api.
---@type ServerListenerApi
client_listener_api = exports.nss_libs:getServerListenerApi(GetCurrentResourceName())

Citizen.CreateThread(function()

    -- Example do 5 seconds something and then fires "i am ready" event.
    Citizen.Wait(5000)

    client_listener_api:serverIsReady()

end)

TIP

You can add arguments to serverIsReady(true, false, 'whatever'). The arguments will be passed to the onServerReady callback.

---

Methods (Client)

exports.nss_libs:getServerEventApi(resourceName)

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

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

Returns ServerEventApi — The server event API

---

:await(eventName, ...)

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

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

Returns any|table — The response data from the server

---

:async(eventName, callback, ...)

Fires an event to the server and executes the callback asynchronously on response without blocking the thread.

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

---

:fire(eventName, ...)

Fires an event to the server without waiting for a result.

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

---

:onServerReady(callback, interval_in_ms?, timeout_in_ms?)

Polls the server until it reports ready, then executes the callback.

Param	Type	Default	Description
callback	function(timeout, ...)	—	Called when server is ready or on timeout
interval_in_ms	number?	1000	Polling interval in milliseconds
timeout_in_ms	number?	30000	Timeout in milliseconds

---

Methods (Server)

exports.nss_libs:getServerListenerApi(resourceName)

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

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

Returns ServerListenerApi — The server 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

---

:serverIsReady(...)

Signals to all clients that the server is ready.

Param	Type	Default	Description
...	any	—	Optional arguments passed to the onServerReady callback

---

How it Works

INFO

In client scripts exports.nss_libs:getServerEventApi(GetCurrentResourceName()) returns a client scoped event API.

That API can be used to fire events to the server, but not to listen to server events (see ClientEvent for that case).

If an event is fired to the server, the server will execute the server side registered listener for that event and return the result. Each fired event has a unique request id. The client will wait for the result with that id and process the result. The server sends the response only to the source client that fired the event.