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
float Avatar position in the world map
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.

C l i e n t P A A P A A r n n r 1 n n o n n o n n f o o f o o i u u i u u l n n l n n e c c e c c R e e R e e e P P e P P s r r s r r p o o p o o o f f o f f n i i n i i s l l s l l e e e e e e ( V V ( V V v e e v e e 1 r r 2 r r ) s s ) s s i i i i o o o o n n n n ( ( ( ( v v v v 1 2 1 1 ) ) C ) ) l i e n t P r 2 o f i l e R e q u e s t ( @ c l i e n t 1 C ) l i e n t P P r r 3 o o f f i i l l e e R R e e q q u u e e s s t t ( ( @ @ c c l l i i e e n n t t 1 1 ) )

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.