Skip to main content

Server

Server is the runtime service for server-wide metadata and operational snapshots.

Use Server when you need:

  • server name
  • slot count
  • current player count
  • uptime
  • runtime health/observability state

Do not use Connection for server metadata.

Connection.GetPlayers() can be used to enumerate or count online players, but that is roster access, not server introspection.
For production scripts, server overview logic should use Server.

Error Handling Pattern​

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

Scope Model​

  • Server.GetInfo() is read-only and available to both client and server runtimes.
  • Server.GetStats() and Server.GetHealth() are operational APIs and should be server-only.
  • Clients should consume server-approved snapshots/events, not infer operational state from unrelated APIs.

Function List​

FunctionDescriptionScope
Server.GetInfoGet server identity and public metadata.S
Server.GetStatsGet live runtime counters and capacity data.S
Server.GetHealthGet health-endpoint and observability status.S

Functions​

Server.GetInfo​

S Shared (Client & Server)

local info, err = Server.GetInfo()

Returns:

  • info (table)
  • err (nil | string)

info fields:

  • name (string)
  • slots (number)
  • passwordProtected (boolean)
  • version (string or nil)

Example:

local info, err = Server.GetInfo()
if not err then
    print("Server: " .. tostring(info.name) .. " (" .. tostring(info.slots) .. " slots)")
end

Server.GetStats​

S Server Only

local stats, err = Server.GetStats()

Returns:

  • stats (table)
  • err (nil | string)

stats fields:

  • generatedAtUtc (string)
  • uptimeSeconds (number)
  • uptimeText (string)
  • playerCount (number)
  • maxPlayers (number)
  • freeSlots (number)
  • entityCount (number)
  • resourceCount (number)
  • startedResourceCount (number)
  • pendingReliableEvents (number)
  • storageReads (number)
  • storageWrites (number)
  • storageErrors (number)
  • commandsTotal (number)
  • commandsOk (number)
  • commandsDenied (number)
  • commandsNotFound (number)
  • commandsError (number)
  • eventsPublished (number)
  • eventsAckSent (number)
  • eventsAckReceived (number)
  • eventsRetries (number)
  • eventsTimeouts (number)
  • eventsDenied (number)
  • eventsInboundDuplicates (number)
  • nodeReads (number)
  • nodeWrites (number)
  • moderationKicks (number)
  • moderationBans (number)
  • moderationDenied (number)
  • eventAuditEnabled (boolean)
  • eventAuditPath (string or nil)
  • deterministicTraceEnabled (boolean)
  • deterministicTracePath (string or nil)
  • controlPlaneStatePath (string or nil)

Notes:

  • playerCount is the authoritative online count.
  • This is preferred over #Connection.GetPlayers() for server overview logic.

Example:

local stats, err = Server.GetStats()
if not err then
    print(
        "Players: " .. tostring(stats.playerCount) ..
        "/" .. tostring(stats.maxPlayers) ..
        " | Uptime: " .. tostring(stats.uptimeText)
    )
end

Server.GetHealth​

S Server Only

local health, err = Server.GetHealth()

Returns:

  • health (table)
  • err (nil | string)

health fields:

  • healthEndpointEnabled (boolean)
  • healthEndpointPrefix (string or nil)
  • observabilityStoreEnabled (boolean)
  • observabilityStorePath (string or nil)
  • observabilityStoreWrites (number)
  • observabilityStoreDrops (number)
  • observabilityExportEnabled (boolean)
  • observabilityExportEndpoint (string or nil)
  • observabilityExportActiveEndpoint (string or nil)
  • observabilityExportEndpointCount (number)
  • observabilityExportContractName (string or nil)
  • observabilityExportContractVersion (string or nil)
  • observabilityExportEnqueuedTotal (number)
  • observabilityExportQueue (number)
  • observabilityExportSentTotal (number)
  • observabilityExportFailedTotal (number)
  • observabilityExportRetryTotal (number)
  • observabilityExportDeadLetters (number)

Example:

local health, err = Server.GetHealth()
if not err then
    print("Health endpoint enabled: " .. tostring(health.healthEndpointEnabled))
    print("Observability export enabled: " .. tostring(health.observabilityExportEnabled))
end
  • Connection: runtime roster and identity
  • Player: moderation/control
  • Resource: lifecycle and resource metadata

Design Notes​

  • Connection answers: who is online?
  • Server answers: what server is this, how many slots does it have, and what is its current runtime state?

That split keeps scripting predictable:

  • server metadata stays under Server
  • per-player roster/identity stays under Connection

Quick Examples​

Show public server info:

local info, err = Server.GetInfo()
if not err then
    print(info.name .. " | slots=" .. tostring(info.slots))
end

Get current player count on server:

local stats, err = Server.GetStats()
if not err then
    print("Online players: " .. tostring(stats.playerCount))
end

Check runtime health:

local health, err = Server.GetHealth()
if not err and health.observabilityExportEnabled then
    print("Observability export active: " .. tostring(health.observabilityExportActiveEndpoint))
end