Messages
Messages in comms are binary data packets, serialized using protocol buffers . They carry text and voice chat, positional updates, profile changes and other real-time interactions.
You can see the comms protocol in action and experiment with it using the open-source Comms Station .
All message definitions are available in the protocol repository , and each message type below has a link to its declaration.
Packet
↗ source
#
The Packet structure is the container for all messages.
| Field | Type | Value |
|---|---|---|
message |
enum |
One of Chat, Voice, Position, AnnounceProfileVersion, ProfileRequest, ProfileResponse, or Scene. |
Text and Voice Chat #
Clients chat by broadcasting text messages and audio clips to all connected peers (usually players in the same island).
Only two Packet types are involved, one for each use-case. Under typical circumstances, clients broadcast these messages to all other clients in their island, which is the group of nearby players they can interact with.
Chat
↗ source
#
Sends a text chat message to other clients.
| Field | Type | Value |
|---|---|---|
message |
string |
Text of the message |
timestamp |
double |
Sender’s UTC timestamp |
Voice
↗ source
#
Sends an encoded voice sample to other clients.
| Field | Type | Value |
|---|---|---|
encoded_samples |
bytes |
Encoded audio data |
codec |
enum |
Only VC_OPUS (no other codecs are supported for now) |
index |
uint32 |
An incremental counter set by the sender |
The codec field is an enum value. Custom codecs are not supported.
Movement #
Clients that control avatars send and receive positional updates within their island, in order to synchronize movement and posture among players.
Position
↗ source
#
Updates other clients on the position and orientation of an avatar.
| Field | Type | Value |
|---|---|---|
position_xposition_yposition_z |
float |
Avatar position in the world map |
rotation_xrotation_yrotation_zrotation_w |
float |
Avatar rotation quaternion |
index |
uint32 |
An incremental counter set by the sender |
Clients typically send Position updates with a low frequency (such as once every 1 or 2 seconds), and switch to a high frequency (several times per second) when moving or interacting.
When sending positional updates, speed is usually better than reliability. The perceived performance is better when delivery is faster, even if a Position message is ocasionally dropped or reordered. Some transports (e.g.
LiveKit
) can change between fast and reliable modes on a per-message basis.
The low-frequency broadcasts are recommended as a simple solution for deliverying updates to clients that momentarily lost connectivity or failed to catch a message while they joined the island.
The index field is an incremental counter, set by the sender so receivers can sort updates that arrive out-of-order.
Profile Sharing #
Clients within an island can request the avatar information of other players, in order to render their avatars, display their names and pictures, etc.
Since profiles changes are rare (compared with positional updates, for example), the system is designed to simplify the task of maintaining a local profile cache, and only fetch profiles when needed.
There’s 3
Packet
types involved: a
ProfileRequest
/
ProfileResponse
pair used by clients to share profiles on demand, and the
AnnounceProfileVersion
message to tell peers what the latest version is, so they can decide whether to request it.
Clients typically broadcast AnnounceProfileVersion messages periodically, plus immediately when their profile changes.
AnnounceProfileVersion
↗ source
#
Signals other clients that there’s a profile entity they can request.
| Field | Type | Value |
|---|---|---|
profile_version |
uint32 |
A version number incremented with every modification. |
Receivers that cache profiles can use the profile_version number to decide whether their local copy is up-to-date, or if they need to send a
ProfileRequest
.
ProfileRequest
↗ source
#
Requests a profile of a specified version from a particular peer.
| Field | Type | Value |
|---|---|---|
address |
string | The identifying address for the profile. |
profile_version |
uint32 |
The wanted profile version. |
Receivers can reply with
ProfileResponse
messages to provide the requested profile.
ProfileResponse
↗ source
#
Sends a profile in response to a
ProfileRequest
.
| Field | Type | Value |
|---|---|---|
serialized_profile |
string | JSON-serialized profile entity. |
base_url |
uint32 |
base URL for a filesystem endpoint, recommended by the sender. |
The serialized_profile field contains the JSON serialization of a
profile entity
.
If the sender wants to recommend a content server to download entities referenced in their profile (such as wearables), it can set the base_url field as a hint. Clients are free to use or ignore this URL.