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
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
| Parameter | Type | Description |
|---|---|---|
eventName | string | Event name. Prefix it with your resource name, like 'rtx_cafe:serve'. |
handler | function | function(...) – 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
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
| Parameter | Type | Description |
|---|---|---|
handle | EventHandle | What 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
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
| Parameter | Type | Description |
|---|---|---|
eventName | string | Event name. Prefix it with your resource name, like 'rtx_cafe:serve'. |
handler | function? | 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
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
| Parameter | Type | Description |
|---|---|---|
eventName | string | Event name. Prefix it with your resource name, like 'rtx_cafe:serve'. |
... | any | Any 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
endTriggerServerEvent
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
| Parameter | Type | Description |
|---|---|---|
eventName | string | Event name. Prefix it with your resource name, like 'rtx_cafe:serve'. |
... | any | Any 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
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
| Parameter | Type | Description |
|---|---|---|
eventName | string | Event name. Prefix it with your resource name, like 'rtx_cafe:serve'. |
target | Player | One player's server id, or -1 for everyone. |
... | any | Any 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
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
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
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
| Parameter | Type | Description |
|---|---|---|
eventName | string | Event name. |
target | Player | Player, or -1 for everyone. |
bytesPerSecond | int | Accepted for FiveM compatibility. |
... | any | Arguments. |
Returns
Nothing (void).
Example
TriggerLatentClientEvent('rtx_maps:data', source, 50000, Config.BigMap)TriggerLatentServerEvent
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
| Parameter | Type | Description |
|---|---|---|
eventName | string | Event name. |
bytesPerSecond | int | Accepted for FiveM compatibility. |
... | any | Arguments. |
Returns
Nothing (void).
Example
TriggerLatentServerEvent('rtx_photos:upload', 20000, photoData)