Networking ​

The WebSG Networking API gives you access to low latency messaging between peers in a world. Third Room's networking is built on top of WebRTC data channels. It is peer-to-peer, so messages are sent directly between peers without going through a server.

A host is a peer connected to the world which can be given additional responsibilities for controlling certain objects in the world. The host may change over time, for example if the current host leaves the world or if the host is disconnected from the network.

Broadcasting messages ​

The network.broadcast function sends a message to all peers in the world. The message can be a string, a binary buffer. The message can be sent reliably or unreliably. Reliable messages are guaranteed to be delivered in order, but may be delayed if the network is congested. Unreliable messages may be dropped or delivered out of order, but can be a useful tool for sending things like positions where you want the lowest latency and don't care as much about receiving every message.

// Send a string message to all peers in the world
network.broadcast("Hello World");

// Send a binary message to all peers in the world
const buffer = new ArrayBuffer(4);
const view = new Float32Array(buffer);
view[0] = 1.0;
network.broadcast(buffer);

// Send a unreliable message to all peers in the world
network.broadcast("Hello World?", false);

Tracking Peers ​

To send a message to a specific peer or get properties such as their position and rotation you'll need to keep track of their peer object. The network.local property is the local peer which will be set before world.onenter is called. The network.host property is the current host peer which may change over time.

network.onpeerentered and network.onpeerexited are called any time a peer enters or exits the world and you can use to store your own map of peers.

network.local; // The local peer

network.host; // The current host peer

network.onpeerentered = (peer) => {
  // Called any time a peer enters the world
};

network.onpeerexited = (peer) => {
  // Called any time a peer exits the world
};

Sending messages to a specific peer ​

The peer.send function sends a message to a specific peer. The message can be a string, a binary buffer, just like the network.broadcast method.

// Send a string message to the peer
peer.send(`Hey ${peer.id}`);

// Send a binary message to the peer
const buffer = new ArrayBuffer(4);
const view = new Float32Array(buffer);
view[0] = 1.0;
peer.send(buffer);

// Send a unreliable message to the peer
peer.send(`Hey ${peer.id}`, false);

Peer Transforms ​

You can use the readonly peer translation and rotation properties to get the root transform of the peer. These properties update every frame.

peer.translation; // WebSG.Vector3
peer.rotation; // WebSG.Quaternion

Receiving Messages ​

To listen for network messages you can create a NetworkListener with network.listen().

// Create a new network listener
const networkListener = network.listen();

// Iterate over all messages received since the last call to .receive()
for (const message of networkListener.receive()) {
  message.peer; // The peer that sent the message
  message.data; // The message data, either a string or an ArrayBuffer
  message.isBinary; // True if the message is a binary ArrayBuffer
}

// Dispose of the network listener and associated resources if you no longer need it
networkListener.close();

To reduce memory allocations you can pass a buffer into .receive() to write message data into.

const buffer = new ArrayBuffer(1024);
const networkListener = network.listen();

for (const message of networkListener.receive(buffer)) {
  message.peer; // The peer that sent the message
  message.data; // The message data, either a string or an ArrayBuffer
  message.isBinary; // True if the message is a binary ArrayBuffer
  message.bytesWritten; // The number of bytes written into the buffer
}