Presence

Presence is the transient collaboration API.

Use it for:

• editor camera transforms
• current tool/mode
• current inspector target
• selected ids
• hovered ids
• other session-local, non-persistent collaboration state

Do not use it for:

• authored map objects
• saved document state
• undo/redo state
• deterministic gameplay state

Scope

• client can explicitly join or leave one transient collaboration session
• client can publish its own presence
• client and server can read known presence for a session
• server mediates session membership and broadcasts updates to joined members

Function List

Function	Description	Scope
Presence.Join	Join one transient collaboration session and receive its current presence snapshot.	C
Presence.Leave	Leave one transient collaboration session.	C
Presence.Set	Publish current client presence for one session.	C
Presence.Clear	Clear current client presence for one session.	C
Presence.GetMembers	Read the current known joined members for one session.	S
Presence.GetSession	Read the current known presence snapshot for one session.	S

Events

Event	Description	Scope
presence:joined	One player joined the transient collaboration session.	S
presence:updated	One player's latest presence for a session was updated.	S
presence:left	One player's presence for a session was cleared or removed.	S

Presence.Join

C Client Only

local ok, err = Presence.Join("map:editor_smoke_01", {
  reliable = true
})

Notes:

• joining a session is the explicit way to receive live presence for that session
• the server replays the current presence:updated snapshot for that session to the joining client
• reliable = true is the recommended default for join/leave

Presence.Leave

C Client Only

local ok, err = Presence.Leave("map:editor_smoke_01", {
  reliable = true
})

Leaves the current client's session membership and clears that client's live presence for the session.

Presence.Set

C Client Only

local ok, err = Presence.Set("map:editor_smoke_01", {
  camera = {
    x = 120.0,
    y = 15.0,
    z = 88.0,
    yaw = 90.0,
    pitch = -12.0,
    roll = 0.0,
    mode = "freecam"
  },
  tool = "select",
  selectedIds = { "prim_3", "prim_7" },
  hoveredId = "prim_8"
}, {
  reliable = false
})

Notes:

• presence is scoped by the calling resource by default
• presence is transient and latest-wins
• joined-session membership controls the live audience
• reliable = false is the recommended default for live camera/tool presence

Presence.Clear

C Client Only

local ok, err = Presence.Clear("map:editor_smoke_01")

Clears the current client's presence entry for the given session.

Presence.GetSession

S Shared

local entries, err = Presence.GetSession("map:editor_smoke_01")

Returns an array of records:

• resource
• sessionId
• playerId
• payload
• updatedAt

Presence.GetMembers

S Shared

local members, err = Presence.GetMembers("map:editor_smoke_01")

Returns an array of records:

• resource
• sessionId
• playerId

Event Payloads

presence:joined

{
  resource = "map-editor",
  sessionId = "map:editor_smoke_01",
  playerId = 2,
  updatedAt = 1770000000000
}

presence:updated

{
  resource = "map-editor",
  sessionId = "map:editor_smoke_01",
  playerId = 1,
  payload = {
    tool = "select",
    selectedIds = { "prim_3" }
  },
  updatedAt = 1770000000000
}

presence:left

{
  resource = "map-editor",
  sessionId = "map:editor_smoke_01",
  playerId = 1,
  updatedAt = 1770000000000
}

Design Rules

• Presence is not persisted.
• Presence is not deterministic.
• Presence does not participate in undo/redo.
• Presence is separate from authored shared map/document state.
• Session membership and live relay should be scoped to the relevant resource/session audience, not treated as saved document state broadcast.