Connection

Connection exposes runtime connection identity and online player roster data.

Error Handling Pattern

• Success: err == nil
• Failure: err contains an error code string

Scope Model

• Server is authoritative for the full online roster.
• Client gets authoritative roster snapshots/events from server and reads local cache.
• Connection metadata is runtime state and may change on reconnect.

Target Selector

APIs that accept a player selector use:

• number -> playerId (session id)
• string prefixed c_ -> clientId
• string prefixed a_ -> accountId

Function List

Function	Description	Scope
Connection.GetPlayerId	Get current session playerId (ephemeral).	S
Connection.GetClientId	Get current/session client id.	S
Connection.GetPlayers	Get online player roster.	S
Connection.GetPlayer	Get one online player by target selector.	S

Event List

Event	Description	Scope
player:connected	Server-authoritative event-bus event emitted when a player session connects.	S
player:disconnected	Server-authoritative event-bus event emitted when a player session disconnects.	S
player:updated	Server-authoritative event-bus event emitted when connection-visible player fields change.	S

Event Payload Contract

Connection/player lifecycle event handlers receive the standard envelope:

• event.name
• event.payload
• event.source
• event.target
• event.timestamp
• event.correlationId
• event.version

event.payload fields by event:

Event	Payload Fields
player:connected	playerId, clientId, accountId, displayName, countryCode, role, connectedAt, loggedIn, ping, fps
player:disconnected	playerId, clientId, accountId, displayName, countryCode, role, connectedAt, loggedIn, ping, fps, reason
player:updated	playerId, clientId, accountId, displayName, countryCode, role, connectedAt, loggedIn, ping, fps, reason

Functions

Connection.GetPlayerId

S Shared (Client & Server)

local playerId, err = Connection.GetPlayerId()

Connection.GetClientId

S Shared (Client & Server)

local clientId, err = Connection.GetClientId(target)

Parameters:

• target (number|string, optional): server can query specific connected player by selector; client uses self context when omitted.

Connection.GetPlayers

S Shared (Client & Server)

local players, err = Connection.GetPlayers(options)

Parameters:

• options (table, optional)
• includeGuests (boolean, default true)

Returns:

• players (table): array of player records.

Player record fields:

• playerId (number)
• clientId (string)
• accountId (string or nil)
• displayName (string)
• countryCode (string or nil): normalized lowercase profile country/catalog code
• role (string)
• connectedAt (number, ms epoch)
• loggedIn (boolean)
• ping (number or nil): last known server-observed round-trip latency in milliseconds
• fps (number or nil): last known client-reported frames-per-second sample
• ipAddress (string or nil)
• clientVersion (string or nil)

Visibility notes:

• Server runtime receives full connection metadata (ipAddress, clientVersion).
• Client runtime should not rely on ipAddress/clientVersion being present.
• ping and fps are live metrics. Treat them as last-known values, not deterministic state.

Connection.GetPlayer

S Shared (Client & Server)

local player, err = Connection.GetPlayer(target)

Events

player:connected

S Shared (Client & Server)

AddEventHandler("player:connected", function(event)
    print(
        "connected pid=" .. tostring(event.payload.playerId) ..
        " cid=" .. tostring(event.payload.clientId) ..
        " aid=" .. tostring(event.payload.accountId)
    )
end)

player:disconnected

S Shared (Client & Server)

AddEventHandler("player:disconnected", function(event)
    print(
        "disconnected pid=" .. tostring(event.payload.playerId) ..
        " cid=" .. tostring(event.payload.clientId) ..
        " aid=" .. tostring(event.payload.accountId) ..
        " reason=" .. tostring(event.payload.reason)
    )
end)

player:updated

S Shared (Client & Server)

AddEventHandler("player:updated", function(event)
    print(
        "updated pid=" .. tostring(event.payload.playerId) ..
        " role=" .. tostring(event.payload.role) ..
        " loggedIn=" .. tostring(event.payload.loggedIn) ..
        " reason=" .. tostring(event.payload.reason)
    )
end)

Identity Notes

• playerId: runtime connection id (changes on reconnect).
• clientId: stable installation/device id (lower trust, useful for anti-abuse/session policy).
• accountId: authenticated persistent identity (nullable for guests).

For persistence and ownership:

• use accountId first,
• fallback to clientId,
• do not persist long-term data by playerId.

NodePlayers Relationship

• Connection gives identity/roster metadata.
• NodePlayers gives live replicated player view state (position/visual fields).
• Use both together:
• target/permissions/moderation by Connection/Auth/Player
• rendering/local UX from NodePlayers (read-only on client)

Determinism Notes

• Connection/roster data is control-plane metadata, not deterministic simulation state.
• Use deterministic streams/snapshots for vehicle physics/state and use Connection data for identity/labels/UI.

Error Codes

• ERR_NOT_FOUND
• ERR_NOT_CONNECTED
• ERR_PERMISSION_DENIED

Quick Examples

Get local identity:

local playerId, playerErr = Connection.GetPlayerId()
local clientId, clientErr = Connection.GetClientId()
local accountId, accountErr = Auth.GetAccountId()

Enumerate online players:

local players, err = Connection.GetPlayers()
if not err then
    for _, p in ipairs(players) do
        print(p.displayName .. " pid=" .. tostring(p.playerId) .. " cid=" .. tostring(p.clientId) .. " aid=" .. tostring(p.accountId))
    end
end

Read player view nodes for local visual logic:

local nodes, err = Node.List("/NodePlayers", {
    recursive = true,
    kind = "player_view"
})

if not err then
    for _, n in ipairs(nodes) do
        local pid = n.playerId
        local pos = n.transform and n.transform.position
        -- local visual-only logic (labels, fade, indicators)
    end
end