Player natives
Players are the people connected to your server, identified by their server id (Player).
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.
Players are the people connected to your server, identified by their server id (Player). A player controls one Sim at a time – their character.
Open in the natives browser Search all 199 natives at once.
GetPlayers
table GetPlayers()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.
Parameters
This native takes no parameters.
Returns
table List of server ids of all connected players.
Example
for _, player in ipairs(GetPlayers()) do
print(player, GetPlayerName(player))
endGetNumPlayers
int GetNumPlayers()Returns how many players are connected right now.
Cheaper than #GetPlayers() when you only need the count. Clients can't call it – publish the number in GlobalState if a UI needs it.
Parameters
This native takes no parameters.
Returns
int Number of connected players.
Example
if GetNumPlayers() >= 20 then
GlobalState.busyHour = true
endPlayerId
Player PlayerId()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
Player The 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)GetPlayerName
string GetPlayerName(Player player)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
string The player's Neighborly username, or nil if they aren't connected.
Example
AddEventHandler('characterSelected', function()
local src = source
SendChatMessage(-1, 'Neighborly', GetPlayerName(src) .. ' moved into the neighborhood.', { 61, 220, 151 })
end)GetPlayerIdentifiers
table GetPlayerIdentifiers(Player player)Returns all identifiers of a player: neighborly: (their Neighborly account), account: (their account on this server) and ip:.
Identifiers are strings in the form type:value. For saved data use GetPlayerAccountId; the ip: identifier can change.
Parameters
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
Returns
table List of identifier strings.
Example
for _, id in ipairs(GetPlayerIdentifiers(source)) do
print(id)
endGetPlayerIdentifierByType
string? GetPlayerIdentifierByType(Player player, string idType)Returns one identifier of the given type.
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 = source
local id = GetPlayerIdentifierByType(src, 'neighborly')
if Config.Banned[id] then
deferrals.done('You are banned from this café.')
end
end)GetPlayerAccountId
string GetPlayerAccountId(Player player)Returns the player's Neighborly account id without the prefix. It never changes, which makes it the best key for saved data.
This is the id to use for every key in the database or KVP. It stays the same across sessions, characters, name changes and servers.
Parameters
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
Returns
string The permanent Neighborly account id.
Example
local db = exports.neighborly:db()
AddEventHandler('characterSelected', function()
local src = source
local key = 'profile:' .. GetPlayerAccountId(src)
local profile = db:get(key) or { visits = 0, firstSeen = os.time() }
profile.visits = profile.visits + 1
profile.lastName = GetPlayerName(src)
db:set(key, profile)
end)GetPlayerEndpoint
string GetPlayerEndpoint(Player player)Returns the player's IP address. Handle it with care and never show it to other players.
Only use it for moderation and logging. Never send it to clients or store it longer than you need to.
Parameters
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
Returns
string IP address of the player.
Example
AddEventHandler('playerJoining', function(name)
local src = source
print(('%s is connecting from %s'):format(name, GetPlayerEndpoint(src)))
end)GetPlayerPing
int GetPlayerPing(Player player)Returns the player's current ping.
Updated every few seconds. High ping makes TriggerServerCallback take longer, so keep UIs responsive while waiting.
Parameters
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
Returns
int Round-trip time in milliseconds.
Example
RegisterCommand('ping', function(source)
TriggerClientEvent('neighborly:notify', source, { text = ('Your ping: %d ms'):format(GetPlayerPing(source)) })
end, false)GetPlayerPlaytime
int GetPlayerPlaytime(Player player)Returns how long the player has played on this server in total, across all sessions.
Counts every session on this server, so it is a fair way to unlock things for regulars or to skip tutorials for veterans.
Parameters
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
Returns
int Total seconds played on this server.
Example
if GetPlayerPlaytime(source) < 3600 then
TriggerClientEvent('rtx_tutorial:start', source)
endGetPlayerCharacter
Sim? GetPlayerCharacter(Player player)Returns the Sim a player is currently playing.
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.
Example
local sim = GetPlayerCharacter(source)
if sim then
AddSimBuff(sim, 'warm_welcome', 120)
endGetPlayerFromSim
Player? GetPlayerFromSim(Sim sim)Finds the player who is playing a Sim right now.
The usual way to turn a Sim id into a player you can send events to. Townies, offline household members and NPCs return nil.
Parameters
| Parameter | Type | Description |
|---|---|---|
sim | Sim | The Sim. |
Returns
Player? The controlling player, or nil for townies and offline Sims.
Example
local player = GetPlayerFromSim(targetSim)
if player then
TriggerClientEvent('neighborly:notify', player, { text = 'Someone waved at you!' })
endGetPlayerLot
ZoneId? GetPlayerLot(Player player)Returns the lot a player is currently on.
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.
Example
if GetPlayerLot(source) ~= Config.CafeLot then
return
endIsPlayerAdmin
boolean IsPlayerAdmin(Player player)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.
Parameters
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
Returns
boolean true for server admins.
Example
RegisterNetEvent('rtx_admin:openPanel', function()
if IsPlayerAdmin(source) then
TriggerClientEvent('rtx_admin:panel', source)
end
end)IsPlayerAceAllowed
boolean IsPlayerAceAllowed(Player player, string ace)Checks an ACE permission. See Permissions.
Aces are hierarchical: allowing rtx_cafe also allows rtx_cafe.manage. Checks are cheap, so check on every server event instead of caching the result.
Parameters
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
ace | string | The permission, for example 'command.kick'. |
Returns
boolean Whether the player has the permission.
Example
if IsPlayerAceAllowed(source, 'rtx_cafe.manage') then
TriggerClientEvent('rtx_cafe:openManager', source)
endDropPlayer
void DropPlayer(Player player, string reason)Disconnects a player with a reason.
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 in ipairs(GetPlayers()) do
if Player(player).state.afkMinutes and Player(player).state.afkMinutes > 30 then
DropPlayer(player, 'You were away for more than 30 minutes.')
end
end
end, true)See also
GetMaxPlayers
int GetMaxPlayers()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
int The maxPlayers value from server.json.
Example
AddEventHandler('playerJoining', function(name, deferrals)
local src = source
if GetNumPlayers() >= GetMaxPlayers() - 2 and not IsPlayerAceAllowed(src, 'queue.priority') then
deferrals.done('The neighborhood is full right now. Try again in a few minutes!')
end
end)GetActivePlayers
table GetActivePlayers()Returns every connected player, including yourself.
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
This native takes no parameters.
Returns
table Server ids of everyone connected.
Example
for _, player in ipairs(GetActivePlayers()) do
print(player, GetPlayerName(player), GetPlayerLot(player))
endGetPlayerServerId
Player GetPlayerServerId(Player? player)Returns a player's server id. Player ids on clients already are server ids, so this mostly exists for code ported from FiveM.
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 |
|---|---|---|
player | Player? | A player id, or nothing for yourself. |
Returns
Player The server id.
Example
local me = GetPlayerServerId(PlayerId())DoesPlayerExist
boolean DoesPlayerExist(Player player)Checks whether a server id belongs to a connected 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
| Parameter | Type | Description |
|---|---|---|
player | Player | Server id of the player. |
Returns
boolean Whether that player is connected.
Example
RegisterCommand('slap', function(source, args)
local target = tonumber(args[1])
if not target or not DoesPlayerExist(target) then
return print('No such player')
end
TriggerClientEvent('rtx_fun:slap', target)
end, true)GetPlayerFromAccountId
Player? GetPlayerFromAccountId(string accountId)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()
while true do
Wait(60000)
for _, row in ipairs(db:find('reminder:')) do
local player = GetPlayerFromAccountId(row.value.account)
if player then
TriggerClientEvent('neighborly:notify', player, { text = row.value.text })
db:delete(row.key)
end
end
end
end)