multiplayer Module

Public Luau surface over the __multiplayer Internal FFI namespace — runtime multiplayer sync state and operations.

Purpose

Wrap the raw __multiplayer.* FFI namespace in a typed Luau table that gets auto-injected as _G.multiplayer via the prelude. Covers connection, peers, ownership, rooms, edit-mode undo/redo, and sync mode.

Note: the top-level sync {} declaration helper (used inside a component to declare synced properties) is a separate global function registered in ffi_callbacks.rs; this module covers the runtime multiplayer.* namespace only.

Usage

-- Connection
multiplayer.connect("https://relay.example.com")
multiplayer.joinRoom(worldGuid .. "/" .. engine.profile .. "/play/" .. sceneGuid)

-- Peers
print("me:", multiplayer.getPeerId())
-- `latency` is the round trip to that peer, nil until one is measured (which
-- is what this client's own row reads); `rttMs` below is the relay link alone.
for _, p in ipairs(multiplayer.getPeers()) do print(p.name, p.latency) end
print("relay:", multiplayer.getDiagnostics().rttMs)

-- Ownership
if not multiplayer.isOwner(entityId) then
    multiplayer.claimOwnership(entityId)
end

-- What is this entity replicating, and why is a property not arriving?
-- observeEntity is nil when the session holds no record for the entity;
-- explain answers either way.
local record = multiplayer.observeEntity(entityId)
if record then print(record.room, record.roomPeers, #record.components) end
local verdict = multiplayer.explain(entityId, "Health", "hp")
if not verdict.arriving then print(verdict.reason) end

-- Edit-mode operations (atomic undo entries)
multiplayer.beginOperation("move cube")
moveCube()
multiplayer.commitOperation()
multiplayer.undo()

Exports

• Connection: connect, disconnect, isConnected, getPeerId, getPeers, getTickRate, getDiagnostics.
• Rooms: joinRoom, leaveRoom, getRooms, roomFor. Room keys carry four segments: {worldGuid}/{profile}/{mode}/{sceneGuid}.
• Replication observation: observe, observeEntity, observeComponent, explain, syncTotals, heldMessages. The same document is served at /zero/runtime/sync/replication, /zero/runtime/sync/entities/<id> and /zero/runtime/sync/rooms.
• Ownership: isOwner, claimOwnership, releaseOwnership.
• Edit-mode operations: beginOperation, commitOperation, cancelOperation, undo, redo, canUndo, canRedo.
• Loopback (test harness): loopback.
• Mode: engine-level state, read and written via engine.mode.