Connection flow

The connection flow is the process by which the Allocations service reserves slots on a Relay server to group players into a match. The process involves two types of players: a host player and joining players. The following list describes the high-level steps involved in the connection process.

  1. The host player requests allocation
  2. The Allocations service selects a Relay server
  3. The Allocations service sends the connection data to the host player
  4. The host player binds to the Relay server
  5. The host player requests a join code
  6. The Allocations service returns a join code to the host player
  7. The host player shares the join code with joining players
  8. The joining players use the join code
  9. The Allocations service sends connection data to the joining player
  10. The joining player binds to the Relay server
  11. The joining player sends connection request

The host player requests an allocation

The host player initiates the connection flow by requesting an allocation from the Allocations service. The allocation request includes the maximum number of connections the allocation can allow. It can also include a specific region. If the request doesn’t include a region, the Allocations service uses QoS to select the best region for the request.

The Allocations service selects a Relay server

The Allocations service receives the host player's request and selects an appropriate Relay server. The Relay server selection depends on the maximum connections allowed and the region.

When the Allocations service finds a Relay server, it reserves a space on the Relay server for the game session. At this point, the Relay server also generates a unique secret key. The Relay server returns the secret key to the Allocations service, in addition to the Relay server IP, the Relay server ports, and the connection data.

The Allocations service sends the connection data to the host player

The Allocations service sends the Relay server connection data to the host player's game client.

The host player binds to the Relay server

The host sends a BIND message to the selected Relay server using the data received from the response from the allocation request. The BIND message has the connection data, the accept mode, nonce, and HMAC. If the host doesn’t send the bind to the Relay server within 60 seconds after making the allocation, the allocation times out from inactivity.

If the information in the request is accurate, the Relay server acknowledges the bind request by sending a BIND_RECEIVED message back to the host client.

Note: You typically send BIND messages after calling the allocate and join APIs, which retrieve the Relay server’s destination address for use with the BIND message.

The host player requests a join code

Once bound to the Relay server, the host player can request a join code from the Allocations service.

The Allocations service returns a join code to the host player

The Allocations service generates and returns a join code to the host player. The join code the Allocations service returns uniquely represents the host player’s allocation to the Relay server, and allows joining players to bind to the same Relay server and connect to the host player.

The host player shares the join code with joining players

The host player shares the unique join code with other players through any method, including verbally, through a text message, or through a Lobby. The join codes are short and easy to remember to ease sharing.

The players that use the join code with a join request to the Allocations service become the joining players.

Note: Any number of joining players can use the same join code so long as the number doesn't exceed the maximum number of connections specified in the initial allocation request.

The joining players use the join code

The joining players use the join code from the host player to send a join request to the Allocations service.

Note: A “join” is when a joining player (a non-host player) client joins the host client’s game session. Under the hood, it’s another allocate call to the Relay backend service.

The Allocations service sends connection data to the joining player

The Allocations service uses the join code to look up the host player’s allocation and returns the data to the joining players.

The response from the Allocations service has the Relay server IP address, the Relay server port, the secret key, the encrypted joining player’s connection data, the joining player’s allocation ID, and the encrypted host connection data. The joining player can then use the secret key to decrypt and use the host connection data to connect to the host.

The joining player binds to the Relay server

The joining player sends a BIND message to the Relay server using its connection data it received from the response to the join request made to the Allocations service.

Upon success, the Relay server acknowledges by sending aBIND_RECEIVED message to the joining player's game client.

Note: You should typically send BIND messages after calling the allocate and join APIs, which retrieve the Relay server’s destination address for use with the BIND message.

The joining player sends a connection request

Once bound to the same Relay server as the host player, the joining player then sends a connection request to the host player. If the connection request is successful, the joining player and the host player can send data to each other through the Relay server.

Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.