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.
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.
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.
message
string
Text of the message
timestamp
double
Sender's UTC timestamp
Voice ↗ source
Sends an encoded voice sample to other clients.
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.
position_x
position_y
position_z
float
Avatar position in the world map
rotation_x
rotation_y
rotation_z
rotation_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.
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.
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.
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.
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.
Last updated