Developer Preview

Events natives

Send and receive events – inside a resource, between resources and across the network.

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.

Send and receive events – inside a resource, between resources and across the network. The Events guide explains the ideas behind them.

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

AddEventHandler

Shared
EventHandle AddEventHandler(string eventName, function handler)

Listens for an event triggered on the same side – by your resource, another resource or Neighborly itself.

Handlers run in the order they were added. A handler only hears events from its own side – to receive events from the network, register them with RegisterNetEvent. Copy source into a local before your first Wait.

Parameters

ParameterTypeDescription
eventNamestringEvent name. Prefix it with your resource name, like 'rtx_cafe:serve'.
handlerfunctionfunction(...) – receives the event's arguments. In server handlers of player events, source is the player.

Returns

EventHandle A handle for RemoveEventHandler.

Example

AddEventHandler('lotEntered', function(zoneId)
    if zoneId == Config.CafeLot then
        exports.neighborly:showTextUI('Welcome to Bluejay Café', { icon = 'coffee' })
    end
end)

AddEventHandler('lotLeft', function(zoneId)
    if zoneId == Config.CafeLot then
        exports.neighborly:hideTextUI()
    end
end)

RemoveEventHandler

Shared
void RemoveEventHandler(EventHandle handle)

Stops a handler from receiving events.

Handlers are removed automatically when your resource stops, so you only need this for handlers that should stop earlier.

Parameters

ParameterTypeDescription
handleEventHandleWhat AddEventHandler or RegisterNetEvent returned.

Returns

Nothing (void).

Example

local handle

handle = AddEventHandler('playerSpawned', function()
    exports.neighborly:notify({ title = 'Welcome!', text = 'Press F10 to open your phone.' })
    RemoveEventHandler(handle)
end)

RegisterNetEvent

Shared
EventHandle? RegisterNetEvent(string eventName, function? handler)

Allows an event to arrive from the other side of the network. Network events that were never registered are dropped.

This is the security gate of your resource: every registered net event is a door that anyone can knock on with any arguments. On the server, validate types, ranges, distance and permissions in every handler. On the client, register only the events the server really sends.

Need an answer back? Use RegisterServerCallback instead of pairing two events by hand.

Parameters

ParameterTypeDescription
eventNamestringEvent name. Prefix it with your resource name, like 'rtx_cafe:serve'.
handlerfunction?Optional handler – the same as calling AddEventHandler right after.

Returns

EventHandle? A handle when a handler was given.

Example

RegisterNetEvent('rtx_cafe:serve', function(customer)
    local src = source
    if type(customer) ~= 'number' or customer == src or not GetPlayerName(customer) then
        return
    end
    if GetPlayerLot(customer) ~= GetPlayerLot(src) then
        return
    end
    TriggerClientEvent('rtx_cafe:served', customer, GetPlayerName(src))
end)

TriggerEvent

Shared
void TriggerEvent(string eventName, any ...)

Fires an event on the same side. Every handler of every resource runs before TriggerEvent returns.

Runs synchronously: when it returns, every handler has run (unless one of them waited). Use it to talk to other resources on the same side, or to let them veto actions with CancelEvent.

Parameters

ParameterTypeDescription
eventNamestringEvent name. Prefix it with your resource name, like 'rtx_cafe:serve'.
...anyAny number of arguments: strings, numbers, booleans, nil, vector3 and tables of those.

Returns

Nothing (void).

Example

local function openCafe()
    TriggerEvent('rtx_cafe:beforeOpen', Config.CafeLot)
    if WasEventCanceled() then
        print('Another resource kept the café closed')
        return false
    end
    GlobalState.cafeOpen = true
    TriggerEvent('rtx_cafe:opened', Config.CafeLot)
    return true
end

TriggerServerEvent

Client
void TriggerServerEvent(string eventName, any ...)

Sends an event from this player to the server. On the server, source is this player.

Fire-and-forget: it returns immediately and gives you no answer. Send ids rather than whole data sets and stay well below 64 KB per event. If you need a result, use TriggerServerCallback.

Parameters

ParameterTypeDescription
eventNamestringEvent name. Prefix it with your resource name, like 'rtx_cafe:serve'.
...anyAny number of arguments: strings, numbers, booleans, nil, vector3 and tables of those.

Returns

Nothing (void).

Example

RegisterCommand('tip', function(_, args)
    local target = tonumber(args[1])
    local amount = tonumber(args[2])
    if not target or not amount then
        return exports.neighborly:notify({ text = 'Usage: /tip <player id> <amount>', type = 'warning' })
    end
    TriggerServerEvent('rtx_cafe:tip', target, amount)
end, false)

TriggerClientEvent

Server
void TriggerClientEvent(string eventName, Player target, any ...)

Sends an event from the server to one player or to everyone.

Events only reach players who are connected right now. Anything a player who joins later must also know belongs in a state bag – see Client ↔ server data. Events to one player arrive in the order you send them, also relative to state bag changes.

Parameters

ParameterTypeDescription
eventNamestringEvent name. Prefix it with your resource name, like 'rtx_cafe:serve'.
targetPlayerOne player's server id, or -1 for everyone.
...anyAny number of arguments: strings, numbers, booleans, nil, vector3 and tables of those.

Returns

Nothing (void).

Example

RegisterCommand('announce', function(source, args)
    local text = table.concat(args, ' ')
    if text == '' then
        return
    end
    TriggerClientEvent('neighborly:notify', -1, {
        title = 'Announcement',
        text = text,
        icon = 'megaphone',
        duration = 10000
    })
end, true)

CancelEvent

Shared
void CancelEvent()

Cancels the event that is being handled right now. Call it inside a handler.

Only built-in events marked as cancellable stop something in the game (chatMessage, buildModeEntered, simInteraction). For your own events it simply sets the flag that WasEventCanceled reads.

Parameters

This native takes no parameters.

Returns

Nothing (void).

Example

AddEventHandler('chatMessage', function(author, text)
    if #text > 300 then
        CancelEvent()
        TriggerClientEvent('neighborly:notify', source, { text = 'That message is too long.', type = 'warning' })
    end
end)

WasEventCanceled

Shared
boolean WasEventCanceled()

Checks whether the event you just fired with TriggerEvent was cancelled.

Only meaningful right after TriggerEvent returns, before your code waits.

Parameters

This native takes no parameters.

Returns

boolean true if a handler called CancelEvent.

Example

RegisterNetEvent('rtx_cafe:openShop', function()
    local src = source
    TriggerEvent('rtx_cafe:beforeShop', src)
    if WasEventCanceled() then
        return TriggerClientEvent('neighborly:notify', src, { text = 'The shop is closed right now.' })
    end
    TriggerClientEvent('rtx_cafe:shop', src, Config.Drinks)
end)

TriggerLatentClientEvent

Server
void TriggerLatentClientEvent(string eventName, Player target, int bytesPerSecond, any ...)

Same as TriggerClientEvent. Neighborly batches and compresses events on its own, so the rate argument is ignored.

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
eventNamestringEvent name.
targetPlayerPlayer, or -1 for everyone.
bytesPerSecondintAccepted for FiveM compatibility.
...anyArguments.

Returns

Nothing (void).

Example

TriggerLatentClientEvent('rtx_maps:data', source, 50000, Config.BigMap)

TriggerLatentServerEvent

Client
void TriggerLatentServerEvent(string eventName, int bytesPerSecond, any ...)

Same as TriggerServerEvent; the rate argument is ignored.

Client only: it runs on the local player's PC and affects only their game. Other players don't see the result unless you tell the server.

Parameters

ParameterTypeDescription
eventNamestringEvent name.
bytesPerSecondintAccepted for FiveM compatibility.
...anyArguments.

Returns

Nothing (void).

Example

TriggerLatentServerEvent('rtx_photos:upload', 20000, photoData)