Callbacks

Callbacks let one side ask the other side for data and get an answer back. The client asks the server with ESX.TriggerServerCallback or ESX.AwaitServerCallback, and the server answers through a handler registered with ESX.RegisterServerCallback. The reverse direction works the same way with client callbacks.

OverviewCopy Anchor Link

In ESX Legacy 1.16 the ESX callback functions are thin wrappers around xLib.callback from esx_lib. The ESX signatures (cb as first or second argument) still work, so old scripts do not need changes.

Client functionsCopy Anchor Link

ESX.TriggerServerCallbackCopy Anchor Link

ESX.TriggerServerCallback(eventName, callback, ...)

Calls a server callback and passes the response to callback. Does not block.

Returns: nothing

ESX.TriggerServerCallback('garage:getVehicles', function(vehicles)
    for i = 1, #vehicles do
        print(vehicles[i].plate)
    end
end, 'pillbox')

ESX.AwaitServerCallbackCopy Anchor Link

ESX.AwaitServerCallback(eventName, ...)

Calls a server callback and waits for the answer. Must run inside a thread (command handler, CreateThread, event handler).

Returns: every value the server passed to cb.

RegisterCommand('mygarage', function()
    local vehicles = ESX.AwaitServerCallback('garage:getVehicles', 'pillbox')
    print(('You own %d vehicles here'):format(#vehicles))
end, false)

ESX.RegisterClientCallbackCopy Anchor Link

ESX.RegisterClientCallback(eventName, callback)

Registers a callback the server can call on this client. The handler gets cb first, then the server's arguments. It is removed when your resource stops.

Returns: nothing

ESX.RegisterClientCallback('police:getStreetName', function(cb)
    local coords = GetEntityCoords(ESX.PlayerData.ped)
    local street = GetStreetNameFromHashKey(GetStreetNameAtCoord(coords.x, coords.y, coords.z))
    cb(street)
end)

ESX.DoesClientCallbackExistCopy Anchor Link

ESX.DoesClientCallbackExist(eventName)

Returns: boolean, whether a callback with this name is registered in the local esx_lib registry.

Server functionsCopy Anchor Link

These are listed here so both halves are in one place. The full server reference is in Server functions.

ESX.RegisterServerCallbackCopy Anchor Link

ESX.RegisterServerCallback(eventName, callback)

Returns: nothing

ESX.RegisterServerCallback('garage:getVehicles', function(source, cb, garage)
    local xPlayer = ESX.GetPlayerFromId(source)
    if not xPlayer or type(garage) ~= 'string' then
        return cb({})
    end

    local vehicles = MySQL.query.await(
        'SELECT plate, vehicle FROM owned_vehicles WHERE owner = ? AND parking = ?',
        { xPlayer.identifier, garage }
    )
    cb(vehicles or {})
end)

ESX.TriggerClientCallbackCopy Anchor Link

ESX.TriggerClientCallback(player, eventName, callback, ...)

Returns: nothing

ESX.TriggerClientCallback(source, 'police:getStreetName', function(street)
    print(('Player %s is on %s'):format(source, street))
end)

ESX.AwaitClientCallbackCopy Anchor Link

ESX.AwaitClientCallback(player, eventName, ...)

Blocking version of ESX.TriggerClientCallback. Returns: the values the client passed to cb.

ESX.DoesServerCallbackExistCopy Anchor Link

ESX.DoesServerCallbackExist(eventName)

Returns: boolean

Timeouts and limitsCopy Anchor Link

setr esx:callbackTimeout 30000

If a client exceeds the rate limit or payload size, or a server handler takes longer than the receiver timeout (30 s unless esx:callbackTimeout is set), the client gets false as the response.

Built-in callbacksCopy Anchor Link

local isAdmin = ESX.AwaitServerCallback('esx:isUserAdmin')

SecurityCopy Anchor Link

Common issuesCopy Anchor Link

• Old code calls cb twice. Only the first call is used.
• Server handler never calls cb. After the receiver timeout (30 s by default) the server answers with false, so the client gets false instead of your data.
• "callback 'x' is already owned by resource 'y'". Two resources use the same name. Prefix names with your resource name.

RelatedCopy Anchor Link

• Server functions
• Callbacks guide
• esx_lib
• Client functions

Frequently asked questions