Developer Preview

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

Server
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))
end

GetNumPlayers

Server
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
end

PlayerId

Client
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

Shared
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

ParameterTypeDescription
playerPlayerServer 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

Server
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

ParameterTypeDescription
playerPlayerServer id of the player.

Returns

table List of identifier strings.

Example

for _, id in ipairs(GetPlayerIdentifiers(source)) do
    print(id)
end

GetPlayerIdentifierByType

Server
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

ParameterTypeDescription
playerPlayerServer id of the player.
idTypestring'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

Server
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

ParameterTypeDescription
playerPlayerServer 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

Server
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

ParameterTypeDescription
playerPlayerServer 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

Server
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

ParameterTypeDescription
playerPlayerServer 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

Server
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

ParameterTypeDescription
playerPlayerServer id of the player.

Returns

int Total seconds played on this server.

Example

if GetPlayerPlaytime(source) < 3600 then
    TriggerClientEvent('rtx_tutorial:start', source)
end

GetPlayerCharacter

Shared
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

ParameterTypeDescription
playerPlayerServer 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)
end

GetPlayerFromSim

Shared
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

ParameterTypeDescription
simSimThe 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!' })
end

GetPlayerLot

Shared
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

ParameterTypeDescription
playerPlayerServer 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
end

IsPlayerAdmin

Server
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

ParameterTypeDescription
playerPlayerServer 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

Server
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

ParameterTypeDescription
playerPlayerServer id of the player.
acestringThe 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)
end

DropPlayer

Server
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

ParameterTypeDescription
playerPlayerServer id of the player.
reasonstringShown 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)

GetMaxPlayers

Shared
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

Client
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))
end

GetPlayerServerId

Client
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

ParameterTypeDescription
playerPlayer?A player id, or nothing for yourself.

Returns

Player The server id.

Example

local me = GetPlayerServerId(PlayerId())

DoesPlayerExist

Server
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

ParameterTypeDescription
playerPlayerServer 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

Server
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

ParameterTypeDescription
accountIdstringAccount 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)