Every built-in function for Sims, lots, households, sync and more – 199 natives in 17 namespaces on one page.
/
199 natives
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.
How to read a native · types · globals
Every native has a signature, a side and an example. In Lua every native is a global function – the namespaces only group them in these docs.
The signature starts with the return type (void means nothing), then the name and every parameter with its type. Copy call copies a ready-to-paste call.
Client natives exist only in client scripts, Server natives only in server scripts, Shared natives in both.
Natives that change the shared world are server-only. That's what keeps every player's game identical – see Best practices.
Restricted natives only work after the server owner allows your resource: add_ace resource.my_resource neighborly.restricted allow.
The hash next to each name (0x…) is a stable id derived from the name. Search for it, or use it when reporting a problem.
Types
Type
Lua type
Meaning
Player
int
A player's server id. Same as source on the server. -1 means everyone where noted.
Sim
string
A Sim id, as a string because Sim ids are 64-bit numbers. Your own Sims have the same id on the server and every client, so you can send it in events.
ZoneId
string
A lot, identified by its zone id (a string).
HouseholdId
string
A household id (a string).
Object
string
An object on the lot the player is on (a string id).
vector3
table
A position: vector3(x, y, z). Supports +, -, * by a number, .x.y.z and #v for its length – #(a - b) is the distance between two points.
EventHandle
table
What AddEventHandler returns. Only useful for RemoveEventHandler.
{ state }
table
What Player, Lot and Entity return: an object whose state field is a state bag.
table
table
A Lua table. The description says what's inside.
any
any
Any value that can be sent over the network.
...any
any
Any number of values.
type?
A question mark means the parameter is optional, or the return value can be nil.
Returns every player currently connected to the server.
The list is a fresh table every call, ordered by server id. Players who are still on the loading screen (inside playerJoining) are not included yet. For a list that clients can read too, publish it in GlobalState – see the scoreboard example.
Returns the server id of the player running this client script. It is the same id the server sees as source.
Server ids are handed out when a player connects and are reused after they leave, so never save them. Use GetPlayerAccountId on the server for anything persistent.
Parameters
This native takes no parameters.
Returns
PlayerThe local player's server id.
Example
RegisterCommand('myid', function()
local me = PlayerId()
AddChatMessage('You', ('Your server id is %d – share it to receive money.'):format(me))
end, false)
Returns a player's username. Returning nil makes it a handy check whether a player is still online.
On a client it works for every connected player, not just the local one. Names are chosen by players – always show them with textContent in NUI, never as HTML.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
Returns
stringThe player's Neighborly username, or nil if they aren't connected.
Example
AddEventHandler('characterSelected', function()
local src = sourceSendChatMessage(-1, 'Neighborly', GetPlayerName(src) .. ' moved into the neighborhood.', { 61, 220, 151 })
end)
Returns the full identifier including its prefix, like discord:1234567890. For saving data prefer GetPlayerAccountId, which every player has.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
idType
string
'neighborly', 'account' or 'ip'.
Returns
string?The full identifier, or nil.
Example
AddEventHandler('playerJoining', function(name, deferrals)
local src = sourcelocal id = GetPlayerIdentifierByType(src, 'neighborly')
ifConfig.Banned[id] then
deferrals.done('You are banned from this café.')
endend)
Returns nil while the player is on the character picker or loading. Event handlers that run early (playerJoining, the first seconds after joining) should check for nil. characterSelected fires as soon as a Sim is available.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
Returns
Sim?The Sim the player controls, or nil before they picked a character.
On the server this is the most reliable proximity check: before you let two players interact, make sure they are on the same lot. While a Sim travels between lots it returns nil.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
Returns
ZoneId?The lot the player's Sim is on, or nil while travelling.
Checks whether a player is a server admin (made admin with op or the first player on a new server). For finer control use IsPlayerAceAllowed.
A quick yes/no for admin tools. For roles like moderator, police or café manager use IsPlayerAceAllowed with your own ace names – server owners can then grant them however they like.
The player sees the reason on a friendly disconnect screen. playerDropped fires right after, so your cleanup code runs as usual.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
reason
string
Shown to the player.
Returns
Nothing (void).
Example
RegisterCommand('afkcheck', function()
for _, player inipairs(GetPlayers()) doifPlayer(player).state.afkMinutes andPlayer(player).state.afkMinutes > 30thenDropPlayer(player, 'You were away for more than 30 minutes.')
endendend, true)
Returns how many players can be connected at the same time.
Set by the server owner in server.json. Combine it with GetNumPlayers on the server to reserve slots for staff or supporters in playerJoining.
Parameters
This native takes no parameters.
Returns
intThe maxPlayers value from server.json.
Example
AddEventHandler('playerJoining', function(name, deferrals)
local src = sourceifGetNumPlayers() >= GetMaxPlayers() - 2andnotIsPlayerAceAllowed(src, 'queue.priority') then
deferrals.done('The neighborhood is full right now. Try again in a few minutes!')
endend)
Finds the server id of a player by their permanent account id.
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
accountId
string
Account id from GetPlayerAccountId.
Returns
Player?Their server id, or nil if they are offline.
Example
local db = exports.neighborly:db()
CreateThread(function()
whiletruedoWait(60000)
for _, row inipairs(db:find('reminder:')) dolocal player = GetPlayerFromAccountId(row.value.account)
if player thenTriggerClientEvent('neighborly:notify', player, { text = row.value.text })
db:delete(row.key)
endendendend)
Read and change Sims: names, ages, needs, moods, buffs, skills, careers, outfits and interactions. A Sim id is a string. On the server, Sim natives are answered by the game of the player who owns that Sim, so they work for every connected player's Sims and wait for the answer – call them from a thread, an event handler or a command. On a client, they read and change Sims of your own household; for other players' Sims on your lot the client can read the name, age, gender, position and current interaction.
Returns the Sim the local player controls. Same as GetPlayerCharacter(PlayerId()).
Cache it in a local and refresh it in playerSpawned and characterSelected instead of calling it every frame.
Parameters
This native takes no parameters.
Returns
Sim?The local player's Sim.
Example
RegisterCommand('whoami', function()
local sim = GetActiveSim()
ifnot sim thenreturnShowToast('Pick a character first.')
endlocal first, last = GetSimName(sim)
local mood = GetSimMood(sim)
ShowNotification(('You are %s %s and you feel %s.'):format(first, last, mood), { sim = sim })
end, false)
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
Parameter
Type
Description
sim
Sim
The Sim.
Returns
string, stringFirst name and last name.
Example
AddEventHandler('playerSpawned', function(sim)
local first, last = GetSimName(sim)
ShowNotification(('Welcome home, %s %s!'):format(first, last), { title = 'Neighborly', sim = sim })
end)
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
Parameter
Type
Description
sim
Sim
The Sim.
Returns
string'male' or 'female' (the Sim's frame).
Example
localfunctiongreeting(sim)
ifGetSimGender(sim) == 'female'thenreturnConfig.Greetings.female
endreturnConfig.Greetings.male
endRegisterNetEvent('rtx_cafe:hello', function()
local src = sourcelocal sim = GetPlayerCharacter(src)
if sim thenTriggerClientEvent('neighborly:notify', src, { text = greeting(sim) })
endend)
Use #(a - b) to get the distance between two positions. On the server, distance checks are your main defence against players interacting with things across the map.
Parameters
Parameter
Type
Description
sim
Sim
The Sim.
Returns
vector3World position.
Example
local distance = #(GetSimPosition(sim) - Config.Counter)
if distance > 3.0thenreturnend
Returns one need of a Sim. On a client it only works for Sims of your own household.
On the server the value comes from the owner's game, so it is always current. Townies and Sims of players who are offline can't be read.
Parameters
Parameter
Type
Description
sim
Sim
The Sim.
need
string
'hunger', 'energy', 'bladder', 'hygiene', 'social' or 'fun'.
Returns
numberFrom -100 (empty) to 100 (full).
Example
CreateThread(function()
local warned = falsewhiletruedolocal energy = GetSimNeed(GetActiveSim(), 'energy')
if energy < -50andnot warned thenexports.neighborly:notify({ text = 'You look exhausted. Time for bed?', type = 'warning' })
warned = trueelseif energy > 0then
warned = falseendWait(10000)
endend)
Removes a moodlet from a Sim. On a client it only works for your own household.
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.
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
Parameter
Type
Description
sim
Sim
The Sim.
Returns
tableList of { name, mood } for every visible buff.
Example
for _, buff inipairs(GetSimBuffs(sim)) doprint(buff.name, buff.mood, buff.minutesLeft)
end
Sets a skill level. On a client it only works for your own household.
Levels are clamped to the skill's maximum (usually 10, 5 for toddler and child skills). Raising a skill this way does not trigger level-up notifications; send your own with ShowNotification if you want one.
Parameters
Parameter
Type
Description
sim
Sim
The Sim.
skill
string
Skill name.
level
number
New level, up to the skill's maximum.
Returns
intThe new level.
Example
RegisterNetEvent('rtx_cafe:practice', function()
local src = sourcelocal sim = GetPlayerCharacter(src)
ifnot sim ornotPlayer(src).state.onDuty orIsSimBusy(sim) thenreturnendlocal level = GetSimSkillLevel(sim, 'mixology')
SetSimSkillLevel(sim, 'mixology', math.min(level + 0.25, 10))
if math.floor(level + 0.25) > math.floor(level) thenTriggerClientEvent('neighborly:notify', src, { text = 'Your mixology skill went up!', type = 'success' })
endend)
Career names are tuning names like 'culinary' or 'painter'. Combine with Player(id).state.job when your own jobs and game careers should work together.
Parameters
Parameter
Type
Description
sim
Sim
The Sim.
Returns
string?, intCareer name like 'culinary' and level, or nil without a career.
Example
local career, level = GetSimCareer(sim)
if career == 'culinary'and level >= 4thenPlayer(source).state:set('canCook', true, true)
end
Adds an interaction to the Sim's queue, as if the player had clicked it. Only works for Sims of the player's own household – on the server the owner's game runs it.
The interaction goes through the game's normal rules – if the target is in use or the Sim can't reach it, it fails like a player's click would. A partial name like 'sit' is matched against the interactions the target offers; use the full tuning name when you need one exact interaction.
Parameters
Parameter
Type
Description
sim
Sim
The Sim.
interaction
string
Interaction tuning name, or part of one: 'sit' picks the shortest matching interaction the target offers.
target
Sim|Object?
What to interact with. Leave it out for interactions on the Sim itself.
Returns
booleantrue if the interaction was queued.
Example
RegisterNetEvent('rtx_cinema:takeSeat', function(seat)
local src = sourcelocal sim = GetPlayerCharacter(src)
iftype(seat) ~= 'string'ornot sim thenreturnendifnotPushSimInteraction(sim, 'sit', seat) thenTriggerClientEvent('neighborly:notify', src, { text = 'That seat is taken.' })
endend)
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.
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.
RegisterNetEvent('rtx_cafe:clockIn', function()
local src = sourcelocal category = GetSimOutfit(GetPlayerCharacter(src))
if category ~= 'career'thenreturnTriggerClientEvent('neighborly:notify', src, { text = 'Put on your work uniform first.' })
endPlayer(src).state:set('onDuty', true, true)
end)
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
Parameter
Type
Description
sim
Sim
The Sim.
Returns
HouseholdId?The Sim's household.
Example
RegisterNetEvent('rtx_social:visitCard', function(target)
local src = sourcelocal sim = type(target) == 'number'andDoesSimExist(target) and target
local householdId = sim andGetSimHousehold(sim)
ifnot householdId thenreturnendlocal home = GetHouseholdHome(householdId)
TriggerClientEvent('neighborly:notify', src, {
title = 'The ' .. GetHouseholdName(householdId) .. ' household',
text = home and ('They live at ' .. GetLotName(home)) or'They are looking for a home.'
})
end)
Returns all needs of a Sim in one call – cheaper than calling GetSimNeed six times.
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
Parameter
Type
Description
sim
Sim
The Sim.
Returns
table{ hunger, energy, bladder, hygiene, social, fun, ... } from -100 to 100.
Households are the families and roommate groups that live together and share funds and a home. Household natives on the server talk to the game of the player who plays that household.
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.
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.
Sets household funds directly. Prefer AddHouseholdFunds or the economy natives, which keep a transaction log.
Writes the funds directly without a transaction log entry. Prefer AddHouseholdFunds, RemoveHouseholdFunds or the economy natives in gameplay code; keep this one for admin tools.
Parameters
Parameter
Type
Description
householdId
HouseholdId
The household.
amount
int
New amount, 0 or more.
Returns
Nothing (void).
Example
RegisterCommand('setfunds', function(source, args)
local target, amount = tonumber(args[1]), tonumber(args[2])
local householdId = target andGetPlayerHousehold(target)
ifnot householdId ornot amount or amount < 0thenreturnprint('Usage: setfunds <player id> <amount>')
endSetHouseholdFunds(householdId, math.floor(amount))
print(('%s now has %s'):format(GetHouseholdName(householdId), FormatMoney(GetHouseholdFunds(householdId))))
end, true)
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.
Lots are the homes, venues and community spaces of a world, identified by their ZoneId (a string). The server knows every lot and who owns it; clients know the lots of the server they are connected to.
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
Parameter
Type
Description
zoneId
ZoneId
Zone id of the lot.
Returns
stringThe lot's name.
Example
AddEventHandler('lotEntered', function(zoneId)
exports.neighborly:notify({ text = 'Welcome to ' .. GetLotName(zoneId), icon = 'house', duration = 3000 })
end)
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.
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.
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.
Objects are everything placed on a lot – fridges, beds, espresso machines, doors. Objects are identified by their tuning name (find it with GetObjectDefinition on one placed in the world) or definition id. Object natives run on the client, against the lot the player is on. Objects created with CreateObject are local to that player and temporary: they are never saved and disappear when the lot unloads or the resource stops. To show something to everyone on a lot, send a client event to everyone there and let each client create it.
Creates a temporary object for the local player on the current lot. It is never saved, only this player sees it, and it is removed when the resource stops or the lot unloads. Objects from packs the server doesn't use are refused.
Script objects are perfect for props, decorations and effects. Track the ids you create and delete them in onResourceStop – Neighborly also removes them for you when the resource stops.
Parameters
Parameter
Type
Description
definition
string|int
Object tuning name or definition id.
coords
vector3
Where to put it.
heading
number?
Rotation in degrees.
Returns
ObjectThe new object.
Example
local balloon
RegisterNetEvent('rtx_party:balloon', function(coords)
if balloon thenDeleteObject(balloon)
end
balloon = CreateObject(Config.BalloonObject, coords, 90.0)
end)
Removes an object that this player's scripts created with CreateObject. Furniture placed in Build mode can't be deleted by scripts.
The object disappears for every player and its entity state bag is removed. Deleting objects players built themselves should always need their permission.
Parameters
Parameter
Type
Description
object
Object
The object.
Returns
booleantrue if it was removed.
Example
local spawned = {}
RegisterCommand('confetti', function()
local pos = GetSimPosition(GetActiveSim())
spawned[#spawned + 1] = CreateObject(Config.PropObject, pos + vector3(1.0, 0.0, 0.0))
end, false)
RegisterCommand('cleanup', function()
for _, object inipairs(spawned) doDeleteObject(object)
end
spawned = {}
end, false)
Checks whether an object with that id is on the lot you are on.
Object ids only make sense on the lot the player is on. To tell the server about an object, send its position or definition – the server can't look objects up.
Works for lots the side has loaded: on a client that is the current lot. Filtering by definition is much faster than filtering the full list in Lua.
Parameters
Parameter
Type
Description
zoneId
ZoneId?
Must be the lot you are on, or nil.
definition
string|int?
Only objects of this tuning name or definition id.
Returns
tableList of objects.
Example
RegisterCommand('fridges', function()
local fridges = GetObjectsOnLot(nil, Config.FridgeObject)
exports.neighborly:notify({ text = ('%d fridges on this lot.'):format(#fridges) })
end, false)
Searches the lot the coordinates are on. Keep the radius small; on a client it only sees the current lot.
Parameters
Parameter
Type
Description
coords
vector3
Search center.
definition
string|int?
Only this definition.
radius
number?
Max distance, default 5.0.
Returns
Object?Closest match.
Example
RegisterCommand('register', function()
local register = GetClosestObject(GetSimPosition(GetActiveSim()), 'object_register_cafe', 3.0)
ifnot register thenreturnShowToast('Walk up to the cash register first.')
endexports.neighborly:showContext('cafe_register')
end, false)
The tuning name of the object's catalog entry, for example 'object_fridge_basic'. It is the same on every machine, so it is safe to compare in client and server code.
Object ids are only meaningful on the lot they belong to. Send positions to the server, not object ids, when other players need to know where something is.
Returns the time on the neighborhood clock. It is the same for every player.
The neighborhood clock is shared: every player sees the same time. It moves according to the server's game speed, not real time. For cooldowns use GetGameTimer.
Returns the game speed. It exists for compatibility; time never runs faster or pauses on a server.
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
intAlways 1 – Neighborly servers run in real time.
Returns the worlds players can live in, depending on the server's packs.
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.
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.
Shows a Sims 4 style dialog and waits for the answer. Call it in a thread.
The calling thread waits until the player answers. For forms with several fields use exports.neighborly:inputDialog.
Parameters
Parameter
Type
Description
options
table
{ title, text, okLabel, cancelLabel, sim }.
Returns
string'ok' or 'cancel'.
Example
local answer = ShowDialog({
title = 'Job offer',
text = 'Bluejay Café wants to hire you as a barista. Accept?',
okLabel = 'Accept',
cancelLabel = 'Decline'
})
if answer == 'ok'thenTriggerServerEvent('rtx_cafe:acceptJob')
end
Adds a chat suggestion. Same as the chat:addSuggestion event.
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
name
string
Command with slash.
help
string
Description.
params
table?
List of { name, help }.
Returns
Nothing (void).
Example
AddChatSuggestion('/dice', 'Roll a die for everyone on your lot', {
{ name = 'sides', help = 'Number of sides, 2 to 100 (default 6)' }
})
AddChatSuggestion('/tip', 'Tip another player', {
{ name = 'player', help = 'Their server id' },
{ name = 'amount', help = 'Simoleons, 1 to 500' }
})
Creates a bill for a player. Bills are kept by the server; show them in your own UI (see the phone example) and pay them with PayBill. Fires billCreated with the bill on the server.
Bills survive restarts. A bill with a payee pays that player when it is paid.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
bill
table
{ label, amount, dueDays, payee } – payee is an optional player who gets the money.
Only open bills. Paid and cancelled bills are gone from this list; payments show up in GetTransactions.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
Returns
tableList of { id, label, amount, due, payee, from }. due is a Unix time or nil, payee the payee's server id while they are online, from the resource that created it.
Example
for _, bill inipairs(GetBills(source)) doprint(bill.id, bill.label, bill.amount)
end
Pays a bill from the debtor's funds and, if it has a payee, gives the money to them – if the payee is offline they get it the next time they play. Fires billPaid. The debtor must be connected.
Takes the money from the debtor and, if the bill has a payee, gives it to them – in one safe step.
Parameters
Parameter
Type
Description
billId
int
Bill id.
Returns
booleanfalse if not enough funds.
Example
RegisterNetEvent('rtx_phone:payBill', function(billId)
local src = sourcefor _, bill inipairs(GetBills(src)) doif bill.id == billId thenlocal ok = PayBill(billId)
TriggerClientEvent('neighborly:notify', src, {
text = ok and'Bill paid.'or'Not enough simoleons for this bill.',
type = ok and'success'or'error'
})
returnendendend)
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
Parameter
Type
Description
billId
int
Bill id.
Returns
booleantrue if an open bill was cancelled.
Example
RegisterCommand('forgivebills', function(source, args)
local target = tonumber(args[1])
ifnot target ornotGetPlayerName(target) thenreturnprint('Usage: forgivebills <player id>')
endfor _, bill inipairs(GetBills(target)) doCancelBill(bill.id)
endTriggerClientEvent('neighborly:notify', target, { text = 'Your bills were forgiven!', type = 'success' })
end, true)
Includes every change made through GiveMoney, TakeMoney, TransferMoney and PayBill, with your reason texts. The server keeps the last 250 entries per player.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
limit
int?
How many, newest first. Default 20.
Returns
tableList of { amount, reason, time }, newest first. Negative amounts are payments.
Example
for _, t inipairs(GetTransactions(source, 5)) doprint(os.date('%H:%M', t.time), t.amount, t.reason)
end
Returns a pack's name, like 'Get to Work' for EP01.
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
Parameter
Type
Description
pack
string
Pack code.
Returns
stringDisplay name.
Example
AddEventHandler('onResourceStart', function(name)
if name ~= GetCurrentResourceName() thenreturnendlocal names = {}
for _, pack inipairs(GetRequiredPacks()) do
names[#names + 1] = GetPackName(pack)
endprint('Packs on this server: ' .. table.concat(names, ', '))
end)
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.
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
EventHandleA handle for RemoveEventHandler.
Example
AddEventHandler('lotEntered', function(zoneId)
if zoneId == Config.CafeLot thenexports.neighborly:showTextUI('Welcome to Bluejay Café', { icon = 'coffee' })
endend)
AddEventHandler('lotLeft', function(zoneId)
if zoneId == Config.CafeLot thenexports.neighborly:hideTextUI()
endend)
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)
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.
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.
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])
ifnot target ornot amount thenreturnexports.neighborly:notify({ text = 'Usage: /tip <player id> <amount>', type = 'warning' })
endTriggerServerEvent('rtx_cafe:tip', target, amount)
end, false)
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 == ''thenreturnendTriggerClientEvent('neighborly:notify', -1, {
title = 'Announcement',
text = text,
icon = 'megaphone',
duration = 10000
})
end, true)
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 > 300thenCancelEvent()
TriggerClientEvent('neighborly:notify', source, { text = 'That message is too long.', type = 'warning' })
endend)
Move data between the server and clients: callbacks that return an answer, and state bags that replicate on their own. Read Client ↔ server data to choose the right tool.
Answers questions from clients. A client calls TriggerServerCallback and waits for what your handler returns.
The handler runs as its own thread, so it may Wait, use the database or even ask the player something with TriggerClientCallback. Whatever it returns is sent back – several values are fine. If it raises an error, the client receives nothing and the error is printed in the server console.
Treat every argument like the arguments of a net event: check types and ranges, and decide on the server. A popular pattern is returning ok, resultOrError.
Parameters
Parameter
Type
Description
name
string
Callback name, prefixed with your resource name, like 'rtx_bank:getAccount'.
handler
function
function(source, ...) – return any number of values; they are sent back to the client that asked.
Asks the server a question and waits for the answer. Call it inside a thread – event handlers, commands, NUI callbacks and CreateThread all are.
The calling thread waits until the server answers – usually one round trip, a few dozen milliseconds. After 30 seconds without an answer (or when no handler with that name exists), it returns nothing and logs a warning to the launcher log, so always handle nil.
Calling it at the top level of a file raises an error. The Server callbacks guide shows the full round trip, including NUI pages.
Parameters
Parameter
Type
Description
name
string
Callback name, prefixed with your resource name, like 'rtx_bank:getAccount'.
...
any
Arguments for the server handler. The server must validate them.
Returns
...anyWhatever the server handler returned, or nothing (nil) after the timeout.
Example
RegisterCommand('balance', function()
local cash, savings = TriggerServerCallback('rtx_bank:getAccount')
ifnot cash thenreturnexports.neighborly:notify({ text = 'The bank is not answering.', type = 'error' })
endexports.neighborly:notify({
title = 'Simoleon Savings',
text = ('Cash %s · Savings %s'):format(FormatMoney(cash), FormatMoney(savings))
})
end, false)
Asks one player's client a question and waits for the answer. Treat the answer like any other client input – it can be faked.
Waits up to 30 seconds, or until the player leaves, then returns nothing. The answer comes from a PC you don't control: use it for choices and local information (did they accept, where is their camera), never for facts like money or ownership.
Parameters
Parameter
Type
Description
name
string
Callback name, prefixed with your resource name, like 'rtx_bank:getAccount'.
player
Player
The player to ask.
...
any
Arguments for the client handler.
Returns
...anyThe client's return values, or nothing (nil) after the timeout or when the player left.
Example
RegisterNetEvent('rtx_trade:offer', function(target, item, price)
local src = sourceiftype(target) ~= 'number'or target == src ornotGetPlayerName(target) thenreturnendiftype(item) ~= 'string'or #item > 40ortype(price) ~= 'number'or price < 1thenreturnend
price = math.floor(price)
local accepted = TriggerClientCallback('rtx_trade:confirm', target, GetPlayerName(src), item, price)
if accepted == trueandTransferMoney(target, src, price, 'Trade: ' .. item) thenTriggerClientEvent('neighborly:notify', src, { text = 'Trade accepted!', type = 'success' })
elseTriggerClientEvent('neighborly:notify', src, { text = 'No deal this time.' })
endend)
Returns a player's state bag holder. Player(id).state is the bag named player:<id>.
On the server, Player(id).state is the authoritative bag. The only client that may change it is that player, through LocalPlayer.state:set(key, value, true). On a client you can read any connected player's replicated values, and LocalPlayer.state is a shortcut for your own bag. Values set with replicated = false stay on the server.
Parameters
Parameter
Type
Description
player
Player
Server id of the player.
Returns
{ state }An object whose state field is the state bag. Read keys like a table, write with :set(key, value, replicated).
Example
RegisterNetEvent('rtx_jobs:toggleDuty', function()
local src = sourcelocal state = Player(src).state
if state.job ~= 'police'thenreturnend
state:set('onDuty', not state.onDuty, true)
end)
Returns a lot's state bag holder. Lot(zoneId).state is the bag named lot:<zoneId>.
Replicated lot values are sent to every client, so a map UI can show them for lots far away. Players who join later receive the current values before their client scripts start.
Parameters
Parameter
Type
Description
zoneId
ZoneId
Zone id of the lot.
Returns
{ state }An object whose state field is the state bag. Read keys like a table, write with :set(key, value, replicated).
Example
RegisterCommand('partymode', function(source)
local zoneId = GetPlayerLot(source)
ifnot zoneId orGetLotOwner(zoneId) ~= GetPlayerHousehold(source) thenreturnTriggerClientEvent('neighborly:notify', source, { text = 'Only the owners can start a party here.' })
endLot(zoneId).state:set('party', notLot(zoneId).state.party, true)
end, false)
Returns the state bag holder of a Sim or object. Entity(id).state is the bag named entity:<id>.
Entity bags work for Sims and objects. Players may write the bags of their own Sims (with replicated = true); everything else is written by the server.
Parameters
Parameter
Type
Description
entity
Sim|Object
A Sim or object id.
Returns
{ state }An object whose state field is the state bag. Read keys like a table, write with :set(key, value, replicated).
Writes one key of a state bag by its name. The same as :set on GlobalState, Player(id).state, Lot(id).state or Entity(id).state.
Only the server can replicate. A client may set values on any bag, but they stay on that PC and are overwritten by the next change from the server – useful for local UI flags, never trusted by the server.
Tables are copied when you set them. Changing a field of a table you read from a bag does nothing – change the table and set the whole key again.
Parameters
Parameter
Type
Description
bagName
string
Bag name: 'global', 'player:12', 'lot:4821' or 'entity:90031'.
key
string
The key.
value
any
New value, or nil to remove the key.
replicated
boolean
true to send it to clients. On a client the value always stays local.
Calls your handler whenever a state bag key changes on this side.
Fires on the side where the change arrives: on the server when server code sets a value, on clients when a replicated change arrives. It does not fire for values that already existed when the player joined or entered the lot – read the current value once (on start or in lotEntered) and then listen for changes.
The value is already stored when your handler runs, so GetStateBagValue returns the new value. Keep handlers short – they run for every matching change.
Parameters
Parameter
Type
Description
key
string?
Key to watch, or nil for every key.
bagFilter
string?
Bag name to watch, or nil for every bag.
handler
function
function(bagName, key, value, reserved, replicated) – runs after the value changed.
Sends a message to this resource's NUI page. The page receives it as a message event.
The message is turned into JSON, so functions and userdata are dropped and vector3 becomes { x, y, z }. Messages are queued until the page has loaded, so it is safe to send them right after the resource starts.
Runs as a thread, so you may wait – for example for TriggerServerCallback – before calling cb. The page's fetch stays pending until you do. NUI callbacks run on the player's PC: anything that costs money or changes the world must be decided by the server.
Parameters
Parameter
Type
Description
name
string
Callback name – the page POSTs to https://<resource>/<name>.
handler
function
function(data, cb) – data is the decoded JSON body; call cb(response) exactly once.
Returns
Nothing (void).
Example
RegisterNUICallback('deposit', function(data, cb)
local amount = tonumber(data.amount)
ifnot amount thenreturncb({ ok = false, error = 'Enter an amount' })
endlocal ok, result = TriggerServerCallback('rtx_bank:deposit', amount)
cb({ ok = ok == true, savings = ok and result ornil, error = not ok and result ornil })
end)
Resource KVP – a small key/value store saved on disk, separately for every resource. For real server data use the database from the State & storage guide.
Saves a value in this resource's KVP store – on the player's PC in client scripts (per server), in the server's data folder in server scripts.
Writes are saved to disk right away. KVP is perfect for small settings; for data that must survive a reinstall or be shared between servers, use the server database.
Parameters
Parameter
Type
Description
key
string
The key.
value
any
A string, number, boolean or table. Tables are stored as JSON.
Returns
Nothing (void).
Example
RegisterNUICallback('setTheme', function(data, cb)
local theme = data.theme == 'dark'and'dark'or'light'SetResourceKvp('theme', theme)
cb({ ok = true, theme = theme })
end)
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.
Reads a whole number saved with SetResourceKvpInt.
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
Parameter
Type
Description
key
string
The key.
Returns
intThe number, or 0.
Example
print('This server started me', GetResourceKvpInt('boots'), 'times')
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.
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.
Reads a value as a string. Tables come back as JSON text.
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.
Same as SetResourceKvp. Writes are always batched, so it exists for FiveM compatibility.
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.
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.
Writes pending KVP changes to disk now. Neighborly flushes on its own within half a second and when the resource stops.
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.
Starts going through every key that begins with a prefix. Use FindKvp to step and EndFindKvp when done.
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.
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.
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.
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.
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.
Reads a file from a resource. On the client the file must be listed in files.
On a client, only files listed in files in the manifest are available. Server-only data belongs in files that aren't listed, so players never download them.
Parameters
Parameter
Type
Description
resource
string
Resource name.
path
string
File path inside the resource.
Returns
string?File contents.
Example
local recipes = {}
AddEventHandler('onResourceStart', function(name)
if name ~= GetCurrentResourceName() thenreturnendlocal raw = LoadResourceFile(name, 'data/recipes.json')
recipes = raw andjson.decode(raw) or {}
print(('Loaded %d recipes'):format(#recipes))
end)
Writes inside the resource folder. Don't use it for player data – the database is backed up, resource folders usually aren't, and updates may overwrite them.
Parameters
Parameter
Type
Description
resource
string
Resource name.
path
string
File path.
data
string
Contents.
Returns
booleantrue on success.
Example
RegisterCommand('exportsales', function()
local db = exports.neighborly:db()
local report = db:find('sale:', function()
returntrueend)
ifSaveResourceFile(GetCurrentResourceName(), 'data/sales.json', json.encode(report)) thenprint(('Saved %d sales to data/sales.json'):format(#report))
endend, true)
Starting resources can change a server completely, so only trusted resources should do it. The resource must exist in the resources folder – run refresh after adding new ones.
Restricted: the resource needs add_ace resource.<name> neighborly.restricted allow in the server permissions.
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.
Restricted: the resource needs add_ace resource.<name> neighborly.restricted allow in the server permissions.
Counts the values of a manifest key, for example how many client_scripts a resource has.
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.
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.
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
Parameter
Type
Description
name
string
Convar name.
default
string
Value if not set.
Returns
stringThe value.
Example
local webhook = GetConvar('rtx_cafe:webhook', '')
RegisterNetEvent('rtx_cafe:bigTip', function(amount)
if webhook == ''thenreturnendprint(('Would post a §%d tip to the staff webhook'):format(amount))
end)
Returns the default when the convar is missing or isn't a whole number.
Parameters
Parameter
Type
Description
name
string
Convar name.
default
int
Value if not set.
Returns
intThe value.
Example
local maxStaff = GetConvarInt('rtx_cafe:maxStaff', 4)
RegisterNetEvent('rtx_cafe:clockIn', function()
local src = sourcelocal working = 0for _, player inipairs(GetPlayers()) doifPlayer(player).state.onDuty then
working = working + 1endendif working >= maxStaff thenreturnTriggerClientEvent('neighborly:notify', src, { text = 'The café has enough staff right now.' })
endPlayer(src).state:set('onDuty', true, true)
end)
The change lasts until the server restarts. Permanent values belong in convars in server.json.
Parameters
Parameter
Type
Description
name
string
Convar name.
value
string
New 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)
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
Parameter
Type
Description
ms
int
Delay in milliseconds.
fn
function
Runs once after the delay, as a new thread.
Returns
intA timer id for ClearTimeout.
Example
RegisterNetEvent('rtx_cafe:order', function()
local src = sourceTriggerClientEvent('neighborly:notify', src, { text = 'Your order will be ready in a minute.' })
SetTimeout(60000, function()
ifGetPlayerName(src) thenTriggerClientEvent('neighborly:notify', src, { text = 'Your order is ready!', type = 'success' })
endend)
end)
Clearing a timer that already ran or was cleared does nothing.
Parameters
Parameter
Type
Description
timerId
int
What SetTimeout returned.
Returns
Nothing (void).
Example
local reminders = {}
RegisterNetEvent('rtx_cafe:clockIn', function()
local src = source
reminders[src] = SetTimeout(3600000, function()
reminders[src] = nilTriggerClientEvent('neighborly:notify', src, { text = 'You have worked an hour. Time for a break!' })
end)
end)
RegisterNetEvent('rtx_cafe:clockOut', function()
local src = sourceif reminders[src] thenClearTimeout(reminders[src])
reminders[src] = nilendend)
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
Parameter
Type
Description
name
string
The command without the slash. Lowercase, no spaces.
handler
function
function(source, args, raw) – source is the player (0 for the console), args the words after the command, raw the full line.
restricted
boolean
Only 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]) orsourcelocal sim = target ~= 0andGetPlayerCharacter(target)
ifnot sim thenreturnprint('Usage: heal <player id>')
endfor _, need inipairs({ 'hunger', 'energy', 'bladder', 'hygiene', 'social', 'fun' }) doSetSimNeed(sim, need, 100)
endTriggerClientEvent('neighborly:notify', target, { text = 'You feel brand new!', type = 'success' })
end, true)
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.
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.
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
Parameter
Type
Description
text
string
Any text.
Returns
intSigned 32-bit Jenkins one-at-a-time hash, like FiveM.
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
Parameter
Type
Description
fn
function
Thread body.
Returns
Nothing (void).
Example
CreateThreadNow(function()
print('runs before the next line')
Wait(100)
print('runs later')
end)
print('next line')