Mirror transport
Namespace: BlitzRelay.Mirror
Component: BlitzRelayTransport
Package version 1.0.0 requires Unity 6000.0 or later, an existing Mirror installation, and Blitz Relay 1.3.1 or later. The package does not declare a Mirror package dependency. WebGL is not supported.
For installation and a host-and-client example, see Connect Mirror.
Inspector settings
Section titled “Inspector settings”Configure the transport with the following Inspector settings:
| Setting | Default | Purpose |
|---|---|---|
| Relay Address | 127.0.0.1 |
Relay hostname or IP address. |
| Relay Port | 7770 |
Relay UDP port. |
| Relay Key | Empty | Connection key; must match BLITZ_RELAY_CONNECTION_KEY. |
| Room Code | Empty | Room to join or claim. The relay assigns a code to a new host. |
| Do Not Route | Off | Sets LiteNetLib’s socket DontRoute option. |
| Maximum Clients | 4096 |
Relay client limit. The Inspector accepts values from 1 to 8,192. |
| Disconnect Timeout Milliseconds | 30000 |
LiteNetLib inactivity timeout in milliseconds. |
| Maximum Reliable Message Size | 262144 |
Reliable transport-packet limit in bytes; minimum 1340. |
Mirror’s NetworkManager.maxConnections is a separate framework limit. The local host client does not connect through the relay and does not consume a relay client slot.
The transport ignores the address passed to ClientConnect(string). Configure the relay endpoint through the transport settings. Keep NetworkManager.networkAddress non-empty because Mirror checks it before calling the transport.
Runtime API
Section titled “Runtime API”Use these members to configure and inspect the transport:
| Member | Purpose |
|---|---|
GetRelayAddress() / SetRelayAddress(string) |
Read or replace the relay address. |
GetRelayPort() / SetRelayPort(ushort) |
Read or replace the relay UDP port. |
GetRelayKey() / SetRelayKey(string) |
Read or replace the connection key. |
GetRoomCode() / SetRoomCode(string) |
Read the assigned code or choose a room before starting a client. |
GetRoomHostToken() / SetRoomHostToken(string) |
Read or replace the room’s HTTP administration token. |
GetMaximumClients() / SetMaximumClients(int) |
Read or replace the requested relay client limit. |
IsRelayHostAvailable |
Most recently reported relay host availability. |
OnRelayHostAvailabilityChanged |
Raised with a bool when host availability changes. |
HasPendingHostPromotion |
Whether the transport holds a claim for the next server start. |
ClearPendingHostPromotion() |
Discard the stored promotion claim. |
OnHostPromotionReceived |
Raised with HostPromotion, containing RoomCode and MaximumClients. |
OnTransportFailure |
Raised with a reason string when the host’s relay connection fails. |
ServerSocket / ClientSocket |
Relay sockets and their current RelaySocketState. |
Configure settings before starting a session. Changing them does not reconnect an active socket or alter an existing room’s relay client limit. Maximum Reliable Message Size has no public runtime setter.
SetRoomHostToken() stores the HTTP room token, not a promotion claim. Without a pending promotion, starting server mode creates a new ephemeral room and clears the old room code until registration completes. Shutdown alone can leave the previous code stored.
IsRelayHostAvailable starts as false. Use ServerSocket.SocketState == RelaySocketState.Started to check relay registration and Mirror’s callbacks to check game-session readiness. ServerActive() also returns true while the relay connection is still starting.
Delivery and packet sizes
Section titled “Delivery and packet sizes”The transport maps Channels.Unreliable to ordinary unreliable delivery. Every other channel ID maps to reliable ordered delivery. It does not expose sequenced unreliable delivery.
The maximum transmission unit (MTU) is 1,350 bytes. The transport reports these limits:
| API | Limit |
|---|---|
GetMaxPacketSize(Channels.Unreliable) |
1,340 bytes |
GetMaxPacketSize(Channels.Reliable) |
Configured reliable limit; 262,144 bytes by default |
GetBatchThreshold(channelId) |
1,340 bytes for every channel |
These are transport limits, not the amount of user data in a Mirror message. Mirror also needs message IDs, a batch timestamp, and size prefixes. Use NetworkMessages.MaxContentSize(channelId) to obtain the content limit for a Mirror message.
The batch threshold keeps ordinary batches within one packet. A larger reliable message can occupy its own batch and be fragmented by LiteNetLib. Unreliable frames cannot be fragmented. Reliable traffic still follows the relay’s backpressure limits.
Connection IDs and addresses
Section titled “Connection IDs and addresses”For remote clients on the host, Mirror’s connectionId is the relay virtual client ID. Use it directly in HTTP client-kick requests. The local host connection has ID 0 and is not a relay client.
ServerGetClientAddress(connectionId) returns relay:{connectionId} for a known remote client, or an empty string otherwise. It does not return a player’s IP address.
Host promotion
Section titled “Host promotion”The transport sends HostPromotionAck before raising OnHostPromotionReceived. Let the relay disconnect the promoted client and wait until NetworkClient.active is false before starting host or server mode. The next server-start attempt consumes the pending claim. Starting a new client session discards it.
Mirror does not change framework roles or reconnect the remaining clients automatically. Follow Handle host migration in Mirror. A room code or HTTP room token alone cannot claim a persistent room.
Relay errors
Section titled “Relay errors”Client errors reach NetworkManager.OnClientError and are followed by NetworkManager.OnClientDisconnect. RoomNotFound and RoomFull map to TransportError.Refused; RoomClosed maps to ConnectionClosed; other relay errors map to Unexpected.
If the host’s relay connection fails, the transport reports remote-client disconnects and raises its custom OnTransportFailure(string) event. This includes HostRemoved and RoomClosed received in disconnect additional data. Mirror does not stop the host session automatically. Handle the event with NetworkManager.StopHost() or StopServer(), as shown in Connect Mirror.