Developer Preview

Core natives

Timers, convars, commands and other utilities.

Developer Preview. Scripting is live on Neighborly servers – everything on these pages works today. The API is young, so tell us what you need next on Discord.

Timers, convars, commands and other utilities.

Open in the natives browser Search all 199 natives at once.

GetGameTimer

Shared
int GetGameTimer()

A monotonic timer for cooldowns and measuring time.

Counts milliseconds since the server (or the client) started and never goes backwards – the right clock for cooldowns. It is different on every machine, so don't send it between client and server.

Parameters

This native takes no parameters.

Returns

int Milliseconds since start.

Example

local started = GetGameTimer()
Wait(1500)
print('Took', GetGameTimer() - started, 'ms')

IsServer

Shared
boolean IsServer()

Tells shared scripts which side they run on.

Handy in shared scripts and helper libraries that behave a little differently on each side.

Parameters

This native takes no parameters.

Returns

boolean true on the server.

Example

if IsServer() then
    print('Loaded on the server')
end

GetConvar

Shared
string GetConvar(string name, string default)

Reads a convar. On the server, convars come from convars and replicatedConvars in server.json or the set/setr console commands. Clients only see replicated convars.

Convars are set in convars in server.json. Keep secrets like webhooks in convars and read them only on the server.

Parameters

ParameterTypeDescription
namestringConvar name.
defaultstringValue if not set.

Returns

string The value.

Example

local webhook = GetConvar('rtx_cafe:webhook', '')

RegisterNetEvent('rtx_cafe:bigTip', function(amount)
    if webhook == '' then
        return
    end
    print(('Would post a §%d tip to the staff webhook'):format(amount))
end)

GetConvarInt

Shared
int GetConvarInt(string name, int default)

Reads a number convar.

Returns the default when the convar is missing or isn't a whole number.

Parameters

ParameterTypeDescription
namestringConvar name.
defaultintValue if not set.

Returns

int The value.

Example

local maxStaff = GetConvarInt('rtx_cafe:maxStaff', 4)

RegisterNetEvent('rtx_cafe:clockIn', function()
    local src = source
    local working = 0
    for _, player in ipairs(GetPlayers()) do
        if Player(player).state.onDuty then
            working = working + 1
        end
    end
    if working >= maxStaff then
        return TriggerClientEvent('neighborly:notify', src, { text = 'The café has enough staff right now.' })
    end
    Player(src).state:set('onDuty', true, true)
end)

SetConvar

Server
void SetConvar(string name, string value)

Changes a convar until the server restarts.

The change lasts until the server restarts. Permanent values belong in convars in server.json.

Parameters

ParameterTypeDescription
namestringConvar name.
valuestringNew value.

Returns

Nothing (void).

Example

RegisterCommand('happyhour', function(source, args)
    local on = args[1] == 'on'
    SetConvar('rtx_cafe:happyHour', on and 'true' or 'false')
    GlobalState.happyHour = on
end, true)

ExecuteCommand

Shared
void ExecuteCommand(string command)

Runs a console command. The resource needs the matching ace, for example add_ace resource.rtx_admin command.say allow.

The resource needs the matching ace, for example add_ace resource.rtx_admin command.say allow. Commands run as the console.

Parameters

ParameterTypeDescription
commandstringConsole command line.

Returns

Nothing (void).

Example

AddEventHandler('dayChanged', function(day)
    if day % 7 == 0 then
        ExecuteCommand('say A new week begins in the neighborhood!')
    end
end)

CreateThread

Shared
void CreateThread(function fn)

Runs a function as a thread, so it can Wait without blocking anything else. Citizen.CreateThread is the same function.

The function starts right away and runs until its first Wait. Errors inside a thread are printed with file and line, and only stop that thread.

Parameters

ParameterTypeDescription
fnfunctionThe function to run as a thread.

Returns

Nothing (void).

Example

CreateThread(function()
    while true do
        GlobalState.playerCount = GetNumPlayers()
        Wait(5000)
    end
end)

Wait

Shared
void Wait(int ms)

Pauses the current thread and lets everything else run. Only works inside a thread.

Calling it outside a thread raises an error. On clients, Wait(0) loops run every frame – keep them short and only run them while needed.

Parameters

ParameterTypeDescription
msintMilliseconds. 0 waits exactly one frame on a client or one tick on the server.

Returns

Nothing (void).

Example

RegisterNetEvent('rtx_stage:countdown', function()
    for i = 3, 1, -1 do
        ShowToast(tostring(i), 900)
        PlaySoundFrontend('ui_tick', 0.6)
        Wait(1000)
    end
    ShowToast('Showtime!', 1500)
end)

SetTimeout

Shared
int SetTimeout(int ms, function fn)

Runs a function once after a delay, without blocking the code that set it.

The function runs as a new thread, so it can wait as well. Copy source into a local before setting the timer – it isn't valid any more when the timer fires.

Parameters

ParameterTypeDescription
msintDelay in milliseconds.
fnfunctionRuns once after the delay, as a new thread.

Returns

int A timer id for ClearTimeout.

Example

RegisterNetEvent('rtx_cafe:order', function()
    local src = source
    TriggerClientEvent('neighborly:notify', src, { text = 'Your order will be ready in a minute.' })
    SetTimeout(60000, function()
        if GetPlayerName(src) then
            TriggerClientEvent('neighborly:notify', src, { text = 'Your order is ready!', type = 'success' })
        end
    end)
end)

ClearTimeout

Shared
void ClearTimeout(int timerId)

Cancels a timer before it runs.

Clearing a timer that already ran or was cleared does nothing.

Parameters

ParameterTypeDescription
timerIdintWhat SetTimeout returned.

Returns

Nothing (void).

Example

local reminders = {}

RegisterNetEvent('rtx_cafe:clockIn', function()
    local src = source
    reminders[src] = SetTimeout(3600000, function()
        reminders[src] = nil
        TriggerClientEvent('neighborly:notify', src, { text = 'You have worked an hour. Time for a break!' })
    end)
end)

RegisterNetEvent('rtx_cafe:clockOut', function()
    local src = source
    if reminders[src] then
        ClearTimeout(reminders[src])
        reminders[src] = nil
    end
end)

RegisterCommand

Shared
void RegisterCommand(string name, function handler, boolean restricted)

Creates a chat and console command. See Commands & key mappings.

Server commands work in chat and the server console; client commands only on that player's PC, where restricted is ignored. Pair client commands with RegisterKeyMapping for key bindings.

Parameters

ParameterTypeDescription
namestringThe command without the slash. Lowercase, no spaces.
handlerfunctionfunction(source, args, raw) – source is the player (0 for the console), args the words after the command, raw the full line.
restrictedbooleanOnly players with the ace command.<name> may use it. Ignored for client commands.

Returns

Nothing (void).

Example

RegisterCommand('heal', function(source, args)
    local target = tonumber(args[1]) or source
    local sim = target ~= 0 and GetPlayerCharacter(target)
    if not sim then
        return print('Usage: heal <player id>')
    end
    for _, need in ipairs({ 'hunger', 'energy', 'bladder', 'hygiene', 'social', 'fun' }) do
        SetSimNeed(sim, need, 100)
    end
    TriggerClientEvent('neighborly:notify', target, { text = 'You feel brand new!', type = 'success' })
end, true)

RegisterKeyMapping

Client
void RegisterKeyMapping(string command, string description, string device, string defaultKey)

Binds a client command to a key that players can change in their settings.

The player's chosen key is remembered per server. Pick a default that the game and Neighborly don't use (F10, F11, Home).

Parameters

ParameterTypeDescription
commandstringA client command. Start it with + to also get a - command on release.
descriptionstringShown in Settings → Key bindings → Resources.
devicestring'keyboard' or 'mouse'.
defaultKeystringDefault key, for example 'F10'. Players can rebind it.

Returns

Nothing (void).

Example

RegisterCommand('+scoreboard', function()
    TriggerEvent('nb_scoreboard:show', true)
end, false)

RegisterCommand('-scoreboard', function()
    TriggerEvent('nb_scoreboard:show', false)
end, false)

RegisterKeyMapping('+scoreboard', 'Show the player list (hold)', 'keyboard', 'HOME')

SetConvarReplicated

Server
void SetConvarReplicated(string name, string value)

Sets a convar that clients can read with GetConvar too. Same as setr in the console.

Server only: the change happens on the server and Neighborly syncs it to every player who can see it. Validate anything that came from a client before you call it.

Parameters

ParameterTypeDescription
namestringConvar name.
valuestringNew value.

Returns

Nothing (void).

Example

SetConvarReplicated('rtx_cafe:open', 'true')

IsPrincipalAceAllowed

Server
boolean IsPrincipalAceAllowed(string principal, string ace)

Checks a permission of a group or resource instead of a player.

Server only. To show the result in a client UI, return it from a server callback or publish it in a state bag.

Parameters

ParameterTypeDescription
principalstringFor example 'group.admin' or 'resource.rtx_cafe'.
acestringPermission name.

Returns

boolean Whether the principal has it.

Example

if not IsPrincipalAceAllowed('resource.' .. GetCurrentResourceName(), 'command.say') then
    print('Add this to server.json permissions: add_ace resource.' .. GetCurrentResourceName() .. ' command.say allow')
end

IsDuplicityVersion

Shared
boolean IsDuplicityVersion()

FiveM's way to ask whether code runs on the server. Handy in shared scripts.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

This native takes no parameters.

Returns

boolean true on the server.

Example

if IsDuplicityVersion() then
    RegisterNetEvent('rtx_cafe:order')
end

GetHashKey

Shared
int GetHashKey(string text)

Hashes a string. Also available as joaat.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
textstringAny text.

Returns

int Signed 32-bit Jenkins one-at-a-time hash, like FiveM.

Example

local key = GetHashKey('rtx_cafe:latte')

CreateThreadNow

Shared
void CreateThreadNow(function fn)

Starts a thread and runs it right away until its first Wait, instead of on the next tick.

Available in client and server scripts. On a client it reads the synced copy of the world, which can trail the server by a moment – make gameplay decisions on the server.

Parameters

ParameterTypeDescription
fnfunctionThread body.

Returns

Nothing (void).

Example

CreateThreadNow(function()
    print('runs before the next line')
    Wait(100)
    print('runs later')
end)
print('next line')