Get started with matchmaking
Install and set up Matchmaker and create your first matching ticket.
Read time 2 minutesLast updated 3 days ago
Match players together in games using the Multiplayer Services SDK. Enable Matchmaker, create the first matchmaking ticket, and create a hosting provider allocation.
Configure your hosting
Before enabling Matchmaker, initialize your chosen hosting solution, or a client-hosted solution provided by Unity. Refer to Connect players, and the Distributed Authority Quickstart for details about using these services with Matchmaker.
Install the Multiplayer Services SDK
Follow the Install the Multiplayer Services SDK documentation to install the Multiplayer Services SDK.
Set up Matchmaker
You can set up and manage Matchmaker through the Unity Dashboard:
- In the Unity Dashboard, go to Development > Products.
- Select Matchmaker.
When you launch Matchmaker for the first time, this adds Matchmaker to the Shortcuts section on the sidebar and opens the Overview page.
Create a queue and a pool
The next step in working with Matchmaker is to set up a queue and pool to control how Matchmaker groups and matches tickets.
If you use a game hosting provider, you must use Cloud Code's allocation function to return allocation data from the hosting provider. Refer to Matchmaker hosting providers for more information.
To create a queue and pool, follow these steps:
- Select Queues > Create queue.
- Choose a name for the first queue and set the maximum number of players on a matchmaking ticket.
- Select Create.
- Select the queue you just created, then in the Pools tab, select Create pool.
- Choose a name for the pool.
- Choose the queue that you created in the previous step.
- Select a Pool type.
- Set the timeout value for a ticket. Select Next.
- Select your hosting type:
- If you're using a hosting provider, select Hosting via Cloud Code, then in the dropdown menu, select the Cloud Code Module Name that contains the allocation and poll functions for your hosting provider.
- If you're using a client-hosted solution provided by Unity, select Client Hosting.
- Select Next.
- Specify the rules used to define the matches created when sending ticket to that queue and pool. Select JSON and copy/paste the following block of code to create matches of one team with a minimum of one player and a maximum of five players:
{ "Name": "Test", "MatchDefinition": { "Teams": [ { "Name": "Main team", "TeamCount": { "Min": 1, "Max": 1 }, "PlayerCount": { "Min": 1, "Max": 5 } } ], "MatchRules": [] }, "BackfillEnabled": false}
- Select Create at the bottom of the page.
Matchmaker is now configured. In the Matchmaker section, select Queues to check the queue and pool that were created.
Important
Before using a hosting provider, refer to Matchmaker hosting providers to integrate Cloud Code modules to allocate game servers and coordinate matchmaking results.
Create a matchmaking ticket
Now that the matchmaker is configured, you can create and send a ticket to request a hosting allocation:
Unity SDK
using System;using System.Collections.Generic;using System.Threading;using System.Threading.Tasks;using Unity.Services.Authentication;using Unity.Services.Core;using Unity.Services.Multiplayer;using UnityEngine;public class MatchmakerExample : MonoBehaviour{ ISession m_Session; CancellationTokenSource m_MatchmakingCts; async void Start() { await UnityServices.InitializeAsync(); await AuthenticationService.Instance.SignInAnonymouslyAsync(); await StartMatchmakingAsync(); } async Task StartMatchmakingAsync() { m_MatchmakingCts = new CancellationTokenSource(); var matchOptions = new MatchmakerOptions { QueueName = "MyQueue", // Optional: filters/attributes used by pool rules TicketAttributes = new Dictionary<string, object> { { "gameMode", "ranked" } }, // Optional: per-player custom data used by matchmaking rules PlayerProperties = new Dictionary<string, PlayerProperty> { { "skill", new PlayerProperty("1200") } } }; var sessionOptions = new SessionOptions { MaxPlayers = 5 }.WithRelayNetwork(); // or .WithDistributedAuthorityNetwork() for Distributed Authority try { m_Session = await MultiplayerService.Instance.MatchmakeSessionAsync( matchOptions, sessionOptions, m_MatchmakingCts.Token); Debug.Log($"Match found and session joined: {m_Session.Id}"); } catch (SessionException e) { Debug.LogError($"Matchmaking failed: {e.Message}"); } } // Cancel matchmaking public void CancelMatchmaking() { m_MatchmakingCts?.Cancel(); }}
CURL
# Fetch anonymous tokencurl -X POST -H "ProjectId: <projectId>" https://player-auth.services.api.unity.com/v1/authentication/anonymous# Call the create ticket endpointcurl -X POST -H "Authorization: Bearer <TOKEN>" \-H 'Content-Type: application/json' \--data-raw '{ "queueName": "Default", "attributes": {}, "players": [{ "id": "Player 1", "customData": {} }]}' \'https://matchmaker.services.api.unity.com/v2/tickets'
Note
Player IDs must be different to be matched together.