Skip to main content
Search our knowledge base

How to Use Unity Matchmaker with Relay to Match Players

zoey park
  • Updated

This guide will walk you through the steps of using Unity's Matchmaker to match players through Relay. You will learn how to integrate Matchmaker with Relay and use the Lobby service for a seamless multiplayer session.

 

Detailed Procedure

 

Initial Setup

1. Install the Matchmaker SDK

Unity's multiplayer features (Matchmaker, Lobby, Relay) are now distributed through a unified Multiplayer Services package. Instead of installing individual packages, you should install this one.

  • In the Unity Editor, go to Window > Package Manager.
  • Change the package scope in the top-left dropdown to Unity Registry.
  • Search for and install the following package:
    • For Unity 6 or newer: com.unity.services.multiplayer
    • For Unity 2022 LTS or older: While you can still install com.unity.services.matchmaker and com.unity.services.lobby separately, it is highly recommended to use the unified com.unity.services.multiplayer package for better compatibility and future support.

2. Configure Matchmaker in Unity Cloud Dashboard

  • Visit cloud.unity.com.
  • Navigate to Products > Multiplayer > Matchmaker and select Launch.
  • Create a Queue and a Pool.
  • Select Client Hosting as your hosting type during the pool setup.

 

Creating and Polling Matchmaking Tickets

3. Create a Matchmaking Ticket

  • Use the Matchmaker SDK or API to create a matchmaking ticket. This requests Matchmaker to find and allocate a Relay server for your players.

4. Poll for Ticket Status

  • Continuously check the status of your matchmaking ticket.
  • Determine when a match has been found and a Relay allocation has been made.

 

Integrate Lobby Service

5. Obtain MatchIdAssignment

  • After players create a matchmaking ticket, they receive a MatchIdAssignment that contains a MatchId, which is the same for all players in the match.
  • All players use this Match ID to send a CreateOrJoin request to the Lobby service.

 

Configuring Relay in Lobby

6. Set Up the Host and Generate Relay Join Code

  • The host (one of the players) keeps the Lobby alive by sending heartbeats.
  • The host requests a Relay allocation, joins the allocation and starts to heartbeat the Relay.

7. Distribute Relay Join Code

  • The host generates a Relay join code
  • The host uses the Lobby service to share the Relay join code with other players.
  • Players use this join code to connect to the Relay allocation.

 

Additional Configuration

8. Transition Players

  • Implement the logic to transition players from the matchmaking phase to the lobby phase using the provided Match ID.

 

Resources

 

If you encounter any issues or have further questions, please feel free to reach out for assistance via portal.

 

Related articles