UDP protocol

Blitz Relay uses LiteNetLib over UDP. Connect with the server’s BLITZ_RELAY_CONNECTION_KEY value and send every relay frame on LiteNetLib channel 0.

All integers are little-endian. Strings are UTF-8 without terminators; each string is preceded by the length field shown in its frame. Every frame starts with a one-byte message type.

Control frames should use reliable ordered delivery. Data frames must use the transport delivery corresponding to their encoded game channel.

Message types

Value	Message	Direction	Payload after type byte
0x01	HostRegister	Peer → relay	uint16 maximumClients
0x02	ClientJoin	Peer → relay	uint16 roomCodeLength, room code
0x03	Connected	Relay → host	int32 virtualClientId
0x04	Disconnected	Relay → peer	int32 virtualClientId
0x05	Data	Both	Role-dependent data frame
0x06	Kick	Host → relay	int32 virtualClientId
0x07	RoomCreated	Relay → host	Room code and host token
0x08	JoinSuccess	Relay → client	No payload
0x09	Error	Relay → peer	byte errorCode
0x0A	HostClaim	Promoted peer → relay	Room code and claim token
0x0B	HostPromoted	Relay → client	Room code, limit, and claim token
0x0C	HostUnavailable	Relay → client	No payload
0x0D	HostAvailable	Relay → client	No payload
0x0E	HostPromotionAck	Promoted client → relay	Room code and claim token

Create an ephemeral room

Send HostRegister from an unassigned peer:

0x01 | uint16 maximumClients

maximumClients must be at least 1. The relay creates an eight-character room code from ABCDEFGHJKLMNPQRSTUVWXYZ23456789 and returns:

0x07 | byte roomCodeLength | uint16 hostTokenLength | roomCode | hostToken

The peer is now the room host. When it disconnects, the relay removes the room, sends Disconnected to every client, and disconnects them.

Join a room

Send from an unassigned peer:

0x02 | uint16 roomCodeLength | roomCode

For a room with an active host, the relay sends JoinSuccess to the joining client and sends the new positive virtualClientId to the host in Connected.

For a persistent room without a host, the earliest eligible client may receive HostPromoted instead. Other clients can receive JoinSuccess followed by HostUnavailable while the claim is pending.

Relay game data

The host sends to one virtual client:

0x05 | int32 targetVirtualClientId | byte gameChannel | gamePayload

Use target -1 to broadcast to every current client. The relay forwards the client-facing form:

0x05 | byte gameChannel | gamePayload

A client sends that same client-facing form to the relay. The relay adds its source virtual ID before forwarding to the host:

0x05 | int32 sourceVirtualClientId | byte gameChannel | gamePayload

Game channel	Transport delivery
0	LiteNetLib ReliableOrdered
1	LiteNetLib Unreliable

Other game-channel values are ignored. A data frame is also ignored when the encoded channel and actual LiteNetLib delivery method do not match.

Kick and disconnect

An active host sends:

0x06 | int32 virtualClientId

The relay removes that client from the room, sends it Disconnected with the same virtual ID, and closes its relay connection. When a client disconnects normally, the host receives Disconnected with that client’s ID.

Claim a host role

When a persistent room has no host, the relay removes the earliest-joined client from the client set and sends:

0x0B | byte roomCodeLength | uint16 maximumClients | uint16 claimTokenLength | roomCode | claimToken

The selected client acknowledges before disconnecting:

0x0E | uint16 roomCodeLength | uint16 claimTokenLength | roomCode | claimToken

It then reconnects as an unassigned peer and sends:

0x0A | uint16 roomCodeLength | uint16 claimTokenLength | roomCode | claimToken

The claim token expires after 10 seconds. A successful claim returns RoomCreated with a new room host token. The relay then sends HostAvailable to existing clients and reports each existing virtual client to the new host with Connected.

See Handle host migration for official transport behaviour.

Error codes

Errors use this frame:

0x09 | byte errorCode

Value	Name	Meaning
0x01	RoomNotFound	No room matches the supplied code.
0x02	RoomFull	The room already contains its maximum number of clients.
0x03	RoomExists	A room-code collision occurred.
0x04	InvalidHostClaim	The room, state, peer, or token does not match the pending claim.
0x05	RoomClosed	An administrator or room host closed the room.
0x06	InvalidMaximumClients	A host requested a client limit below one.
0xFF	Unknown	An unspecified relay error.

Receiving Error is terminal in both official Unity transports: they stop the affected relay connection.