Callbacks

A callback lets a client ask the server for something and get an answer. UgCore validates every request before your handler sees it.

Register on the server

server.lua

local S = UgCore.Schema

UgCore.Callback.Register('GetBalance', {
    schema = S.Define({ S.Enum({ 'cash', 'bank' }) }),
    rate = { max = 5, per = 1000 },
    requirePlayer = true,
}, function(source, account)
    return UgCore.Accounts.GetBalance(source, account)
end)

The name is prefixed with your resource: clients call my-bank:GetBalance.

Options

UgSchema

required

Arguments, from UgCore.Schema.Define. No schema, no registration.

{ max: integer, per: integer }

required

Per-player token bucket: max calls burst, refilled over per ms.

boolean

Rejects players whose ug-core:Loaded statebag is not true, with not_loaded.

boolean

Rejects downed and dead players with no_permission. They are not flagged.

string

ACE the player MUST have, such as ug.admin.

Handler

The handler gets the player’s source and the validated arguments, and returns one value. It runs in a thread, so it can wait on the database. If it raises, the client gets internal_error and the error is logged on the server. Clients never see stack traces.

Call from the client

client.lua

CreateThread(function()
    local ok, balance, errorCode = UgCore.Callback.Await('my-bank:GetBalance', 'bank')

    if ok then
        print('Balance: ' .. balance)
    else
        print('Failed: ' .. errorCode)
    end
end)

Await MUST run in a thread. It times out after 10 seconds. Late answers are ignored. Use Trigger to avoid blocking:

client.lua

UgCore.Callback.Trigger('my-bank:GetBalance', function(ok, balance, errorCode)
    -- ...
end, 'bank')

The pipeline

Every request goes through these checks, in order. The first failure answers with an error code and, for most checks, adds to the player’s Guard score. Malformed requests, such as a missing request id, are flagged and get no answer at all.

Server to client

The server can ask a client too. The answer is untrusted input, so it MUST match a schema:

UgCore.Callback.Register('GetSettings', function(key)
    return GetResourceKvpString(key)
end)

local ok, value, errorCode = UgCore.Callback.Await(source, 'my-hud:GetSettings', {
    schema = UgCore.Schema.String({ max = 64 }),
    timeout = 5000,
}, 'theme')

Answers from another player are ignored. A request resolves with timeout when the player drops.

Getting started

For server owners

For developers

Concepts

Register on the server

Options

Handler

Call from the client

The pipeline

Server to client

​Register on the server

​Options

​Handler

​Call from the client

​The pipeline

​Server to client

Register on the server

Options

Handler

Call from the client

The pipeline

Server to client