Shared Session State

PlayerState supports a server-wide shared session Replica: temporary state that every client in the current server can read. It is not normal player data and not the per-player session table.

When to use it

Use SharedSession for safe-to-show state that all clients in this server need in sync:

Round or match phase, intermission, victory state
Server-local timers (prefer a server timestamp such as endsAt, not per-frame countdown replication)
Vote tallies, queue position for this server, UI that everyone sees the same way

It is only for the running server. It does not persist and is not global across the universe or other servers.

For per-player temporary fields, use session. For saved secrets or internal per-player fields, use Server.

Configuration

In PlayerStateConfig, under Server, define defaults as SharedSession. There is no nested Template property: SharedSession itself is the template table.

lua

-- PlayerStateConfig.lua (excerpt)
Server = {
    -- ...Profile, DataStore, etc.

    SharedSession = {
        round = {
            phase = "Waiting",
            endsAt = 0,
        },
    },
},

Server API

All functions live on PlayerState (server module). Full signatures and behavior are documented under Server API — Shared Session.

Method	Purpose
`SetShared(key, value)`	Set a top-level key only
`GetShared(key)`	Get a top-level key
`SetSharedPath(path, value)`	Set using dot paths (e.g. `round.phase`)
`GetSharedPath(path)`	Get using dot paths
`SetSharedValues(values)`	Batch set `{ [string]: any }`
`OnSharedChanged(pathOrKey, callback)`	Subscribe to changes
`GetSharedReplica()`	Raw Replica for advanced use
`GetSharedAll()`	Full shared table, if loaded
`IsSharedReady()`	Whether the shared Replica is ready

Path rules: SetShared / GetShared are for root keys only. If the key string would include dot syntax, use SetSharedPath / GetSharedPath.

Example (server)

lua

PlayerState.SetSharedPath("round.phase", "Active")
PlayerState.SetSharedPath("round.endsAt", workspace:GetServerTimeNow() + 120)

For countdown UIs, replicate endsAt and compute remaining time on the client from Workspace:GetServerTimeNow() (or equivalent), rather than pushing a new remaining-seconds value every frame.

Client API

All functions live on PlayerStateClient. Shared reads wait for the shared session Replica to be ready, similar to normal player data reads.

Method	Purpose
`GetShared(key)`	Top-level key
`GetSharedPath(path)`	Dot path
`OnSharedChanged(pathOrKey, callback)`	Subscribe
`GetSharedReplica()`	Raw Replica
`GetSharedAll()`	Full shared table
`IsSharedReady()`	Ready check

See Client API — Shared Session.

Example (client)

lua

local endsAt = PlayerStateClient.GetSharedPath("round.endsAt")

PlayerStateClient.OnSharedChanged("round.phase", function(newPhase)
    print("Round phase:", newPhase)
end)

Shared Session State ​

When to use it ​

Configuration ​

Server API ​

Example (server) ​

Client API ​

Example (client) ​

See also ​