2.4.6.2. Messages from Client to Server

The client emits messages over two WebRTC data channels:

• the reliable channel (id 100) for Acknowledgement, OrthogonalAcknowledgement, ReceivedResources, ResourceLost, NodeStatus, DisplayInfo and Handshake traffic that must not be lost;

• the unreliable channel (id 120) for per-frame messages: ControllerPoses, InputStates, InputEvents, KeyframeRequest and PongForLatency.

Any reliable-channel message MAY instead be sent as a binary frame on the signaling WebSocket. The payload bytes are identical, and a client MUST use this fallback transport whenever the WebRTC reliable data channel is not yet open (notably for the initial Handshake). Servers MUST accept reliable messages on either transport for the lifetime of the session; see Reliable-channel transport fallback (binary WebSocket frames). The unreliable channel has no such fallback.

The Client sends all of its messages in its local units and AxesStandard. The Server is responsible for converting incoming data to its own internal representation, and for converting outgoing commands to the client’s units.

2.4.6.2.1. Common header

Every client-to-server message begins with the 9-byte ClientMessage header (reference: teleport::core::ClientMessage):

Table 2.24 ClientMessage header

Bytes	Type	Description
1	ClientMessagePayloadType	The message type (see table below).
8	int64	timestamp_session_us – microseconds elapsed on the client since its local session start when this message was constructed.

Table 2.25 ClientMessagePayloadType

Id	Name	Reference struct
0	Invalid	(never sent)
1	Handshake	teleport::core::Handshake (initial send normally goes on the signaling WebSocket via the reliable-channel fallback, see Handshake and Reliable-channel transport fallback (binary WebSocket frames))
2	NodeStatus	teleport::core::NodeStatusMessage
3	ReceivedResources	teleport::core::ReceivedResourcesMessage
4	ControllerPoses	teleport::core::NodePosesMessage
5	ResourceLost	teleport::core::ResourceLostMessage
6	InputStates	teleport::core::InputStatesMessage
7	InputEvents	teleport::core::InputEventsMessage
8	DisplayInfo	teleport::core::DisplayInfoMessage
9	KeyframeRequest	teleport::core::KeyframeRequestMessage
10	PongForLatency	teleport::core::PongForLatencyMessage
11	OrthogonalAcknowledgement	teleport::core::OrthogonalAcknowledgementMessage
12	Acknowledgement	teleport::core::AcknowledgementMessage

2.4.6.2.2. DisplayInfo (id = 8)

The byte layout (reference: teleport::core::DisplayInfoMessage):

Table 2.26 DisplayInfoMessage

Bytes	Type	Description
9	ClientMessage	Standard header (DisplayInfo, timestamp).
4	uint32	width
4	uint32	height
4	float	framerate (Hz, measured).

2.4.6.2.3. ControllerPoses (id = 4)

Sent on the unreliable channel (reference: teleport::core::NodePosesMessage).

Table 2.27 NodePosesMessage

Bytes	Type	Description
9	ClientMessage	Standard header (ControllerPoses, timestamp).
28	Pose_packed	headPose (vec4 orientation + vec3 position).
2	uint16	numPoses = N.
N × 36	NodePose[]	For each pose: 8-byte node uid, 28-byte PoseDynamic_packed (pose + linear velocity + angular velocity), all in stage space.

2.4.6.2.4. ReceivedResources (id = 3)

Sent on the reliable channel (reference: teleport::core::ReceivedResourcesMessage).

Table 2.28 ReceivedResourcesMessage

Bytes	Type	Description
9	ClientMessage	Standard header (ReceivedResources, timestamp).
8	size_t	receivedResourcesCount = N.
8 * N	uid[]	Resource uids that have been fully decoded and stored.

2.4.6.2.5. NodeStatus (id = 2)

Sent on the reliable channel to tell the server which nodes the client is currently rendering, and which it has chosen to release (reference: teleport::core::NodeStatusMessage).

Table 2.29 NodeStatusMessage

Bytes	Type	Description
9	ClientMessage	Standard header (NodeStatus, timestamp).
8	size_t	nodesDrawnCount = N.
8	size_t	nodesWantToReleaseCount = M.
8 * N	uid[]	Drawn node uids.
8 * M	uid[]	Node uids the client wants to release.

2.4.6.2.6. ResourceLost (id = 5)

Sent on the reliable channel to tell the server that a previously-confirmed resource has been lost (e.g. due to a decoder error) and must be re-sent (reference: teleport::core::ResourceLostMessage).

Table 2.30 ResourceLostMessage

Bytes	Type	Description
9	ClientMessage	Standard header (ResourceLost, timestamp).
2	uint16	resourceCount = N.
8 * N	uid[]	Lost resource uids.

2.4.6.2.7. InputStates (id = 6)

Sent on the unreliable channel each frame, after SetupInputs has been received. Carries the current value of every state-typed input declared by the server (reference: teleport::core::InputStatesMessage). See Input for the full input model.

Table 2.31 InputStatesMessage

Bytes	Type	Description
9	ClientMessage	Standard header (InputStates, timestamp).
2	uint16	numBinaryStates = B.
2	uint16	numAnalogueStates = A.
B (bits, padded to bytes)	bitfield	One bit per declared binary-state input, in declaration order.
4 * A	float[]	One float per declared analogue-state input, in declaration order.

2.4.6.2.8. InputEvents (id = 7)

Sent on the unreliable channel when one or more event-typed inputs have fired since the last frame (reference: teleport::core::InputEventsMessage).

Table 2.32 InputEventsMessage

Bytes	Type	Description
9	ClientMessage	Standard header (InputEvents, timestamp).
2	uint16	numBinaryEvents = B.
2	uint16	numAnalogueEvents = A.
2	uint16	numMotionEvents = M.
B × 7	InputEventBinary[]	4-byte eventID, 2-byte inputID, 1-byte activated flag.
A × 10	InputEventAnalogue[]	4-byte eventID, 2-byte inputID, 4-byte strength (float).
M × 14	InputEventMotion[]	4-byte eventID, 2-byte inputID, 8-byte vec2 motion.

2.4.6.2.9. KeyframeRequest (id = 9)

Sent on the unreliable channel when the video decoder has lost sync; the server forces the encoder to emit the next frame as an IDR (reference: teleport::core::KeyframeRequestMessage).

Table 2.33 KeyframeRequestMessage

Bytes	Type	Description
9	ClientMessage	Standard header (KeyframeRequest, timestamp). No additional fields.

2.4.6.2.10. PongForLatency (id = 10)

Sent on the unreliable channel in response to PingForLatency. The server uses the round-trip to estimate one-way latency (reference: teleport::core::PongForLatencyMessage).

Table 2.34 PongForLatencyMessage

Bytes	Type	Description
9	ClientMessage	Standard header (PongForLatency, timestamp).
8	int64	unix_time_us – the value echoed from the matching PingForLatencyCommand.
8	int64	server_to_client_latency_us – the client’s measured one-way latency from server to client (microseconds).

2.4.6.2.11. Acknowledgement (id = 12)

Sent on the reliable channel in response to any AckedCommand (currently SetupLighting and SetOriginNode; reference: teleport::core::AcknowledgementMessage).

Table 2.35 AcknowledgementMessage

Bytes	Type	Description
9	ClientMessage	Standard header (Acknowledgement, timestamp).
8	uint64	ack_id – copied from the command being acknowledged.

2.4.6.2.12. OrthogonalAcknowledgement (id = 11)

Sent on the reliable channel to confirm a single confirmationNumber carried by a NodeStateCommand (e.g. UpdateNodeStructure). Allows independent state updates to be confirmed without the monotonic ack_id ordering of AckedCommand (reference: teleport::core::OrthogonalAcknowledgementMessage).

Table 2.36 OrthogonalAcknowledgementMessage

Bytes	Type	Description
9	ClientMessage	Standard header (OrthogonalAcknowledgement, timestamp).
8	uint64	confirmationNumber.