multiplayer

The multiplayer namespace — 24 functions.

globals/multiplayer/beginOperation

globals/multiplayer/beginOperation(description: string)

Begin recording an undoable operation. All mutations until commitOperation() are grouped into one undo entry.

globals/multiplayer/canRedo

globals/multiplayer/canRedo() -> boolean

Check if this client has any redoable operations.

globals/multiplayer/canUndo

globals/multiplayer/canUndo() -> boolean

Check if this client has any undoable operations.

globals/multiplayer/cancelOperation

globals/multiplayer/cancelOperation()

Cancel the current operation and restore all properties to their values at begin time.

globals/multiplayer/claimOwnership

globals/multiplayer/claimOwnership(entityId: string?) -> boolean

Request ownership of an entity. Returns true if the claim was tentatively granted (relay confirmation pending).

globals/multiplayer/commitOperation

globals/multiplayer/commitOperation()

Finalize the current operation and push it onto the undo stack. Only changes that actually differ from the start state are recorded.

globals/multiplayer/connect

globals/multiplayer/connect(relayUrl: string)

Connect to a multiplayer relay server for the current world. Uses the loaded world's world_id as the room prefix for scene isolation. A world must be loaded before connecting.

globals/multiplayer/disconnect

globals/multiplayer/disconnect()

Disconnect from the multiplayer relay server.

globals/multiplayer/getDiagnostics

globals/multiplayer/getDiagnostics() -> SyncDiagnostics

Get sync diagnostics — bandwidth, latency, peer count, top consumers.

globals/multiplayer/getPeerId

globals/multiplayer/getPeerId() -> number?

Get this client's peer ID in the current session.

globals/multiplayer/getPeers

globals/multiplayer/getPeers() -> { PeerInfo }

Get a list of all connected peers in the current session.

globals/multiplayer/getTickRate

globals/multiplayer/getTickRate() -> number

Get the current sync tick rate (network updates per second).

globals/multiplayer/isConnected

globals/multiplayer/isConnected() -> boolean

Check if a multiplayer session is active and connected to a relay.

globals/multiplayer/isHost

globals/multiplayer/isHost() -> boolean

Whether THIS client is the host (authoritative owner) of the current scene's play room — the relay room CREATOR, or offline / single-player. Host code spawns the shared synced world (via entity.spawnSynced or a scene's onHostLoad) and runs authoritative simulation; a non-host (JOINER) receives that content from the relay snapshot and must NOT re-create it. Gate ANY code that spawns synced entities or owns shared state with this so it runs on exactly one client — running it on every peer is the double-spawn 'explosion'.

globals/multiplayer/isOwner

globals/multiplayer/isOwner(entityId: string?) -> boolean

Check if the local client owns the given entity (or the current entity if called from a component). Only the owner can modify synced properties directly.

globals/multiplayer/isRoomCreator

globals/multiplayer/isRoomCreator(roomKey: string) -> boolean?

Whether this client created the given room — it was the FIRST peer to join it (race-free; the relay assigns it on join). In play mode the creator instantiates the scene's entities (synced) and every other joiner receives them from the relay snapshot, so the scene is never double-instantiated.

globals/multiplayer/joinRoom

globals/multiplayer/joinRoom(roomKey: string)

Join a relay room. Room keys are built as {worldGuid}/{mode}/{sceneGuid} and partition the relay's fan-out — only peers in the same room receive each other's broadcasts. No-op when not connected or already joined.

globals/multiplayer/leaveRoom

globals/multiplayer/leaveRoom(roomKey: string)

Leave a relay room. No-op when not connected or not joined.

globals/multiplayer/loopback

globals/multiplayer/loopback() -> { [string]: any }

Loopback testing harness. Returns a table with enable(), disable(), flush(), receive() methods for testing sync without a relay server.

globals/multiplayer/on

globals/multiplayer/on(channel: string, callback: (number, ...any) -> ())

Subscribe to a custom message channel. The callback runs as callback(fromPeerId, ...args) whenever another peer calls multiplayer.send(channel, ...). Multiple callbacks per channel fire in registration order.

globals/multiplayer/redo

globals/multiplayer/redo() -> boolean

Redo this client's last undone operation.

globals/multiplayer/releaseOwnership

globals/multiplayer/releaseOwnership(entityId: string?) -> boolean

Release ownership of an entity.

globals/multiplayer/send

globals/multiplayer/send(channel: string, ...: any)

Broadcast a message on a named channel to every OTHER peer in the room. The relay forwards it transparently; peers receive it via multiplayer.on. Arguments may be any synced value (nil, boolean, number, string, Vec3, entity/component proxy, or table) and are delivered to listeners in order. No-op when not connected.

globals/multiplayer/undo

globals/multiplayer/undo() -> boolean

Undo this client's last edit-mode operation.