Get started

Prerequisites

• Create a Unity ID.
• Create a Unity Cloud account.
• Create a project in your Unity Cloud account.

Configure your hosting

Install the Matchmaker SDK

1. In the Unity Editor's Package Manager, select Unity Registry.
2. Search for the following package:
   • For Unity 2022 LTS and later:

     com.unity.services.multiplayer

   • For earlier versions of Unity:

     com.unity.services.matchmaker

     Note

     For most users, the unified Multiplayer Services package replaces the Matchmaker standalone package, which is deprecated in Unity 6. Consider migrating to the unified package to facilitate a smooth transition. Visit the migration guide for a step-by-step transition process.
3. Select the package and select Install. Refer to the Package Manager.

Set up Matchmaker

1. In the Unity Dashboard, select the Products tab from the sidebar.
2. Under Gaming Services > Multiplayer, go to Matchmaker and select Launch.

Create a queue and a pool

1. Select Create a Queue. Choose a name for the first queue and set the maximum number of players on a matchmaking ticket. Select Create.
2. Select Create a Pool. Choose a name for the pool. Choose the queue that was created in the previous step. Set the timeout value for a ticket. Select Next.
3. Select your hosting type:
   • If you're using a third-party 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 need to enable this feature, contact Matchmaker support.
   • If you're using a client-hosted solution provided by Unity, select Client Hosting.
   Note

   If you're migrating from Multiplay Hosting, refer to Multiplay Hosting migration.
4. Select Next.

{  "Name": "Test",  "MatchDefinition": {    "Teams": [      {        "Name": "Main team",        "TeamCount": {          "Min": 1,          "Max": 1        },        "PlayerCount": {          "Min": 1,          "Max": 5        }      }    ],    "MatchRules": []  },  "BackfillEnabled": false}

5. Select Logic Builder and set the Default QoS Region by selecting one the regions in the dropdown.
6. Select Create at the bottom of the page.

Create a matchmaking ticket

Unity SDK

var players = new List<Unity.Services.Matchmaker.Models.Player>{    new ("Player1", new Dictionary<string, object>())};// Set options for matchmakingvar options = new CreateTicketOptions(  "Default", // The name of the queue defined in the previous step,  new Dictionary<string, object>());// Create ticketvar ticketResponse = await MatchmakerService.Instance.CreateTicketAsync(players, options);// Print the created ticket idDebug.Log(ticketResponse.Id);

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'

REST API

Poll ticket status

Unity SDK

MultiplayAssignment assignment = null;bool gotAssignment = false;do{    //Rate limit delay    await Task.Delay(TimeSpan.FromSeconds(1f));    // Poll ticket    var ticketStatus = await MatchmakerService.Instance.GetTicketAsync("<ticket id here>");    if (ticketStatus == null)    {        continue;    }    //Convert to platform assignment data (IOneOf conversion)    if (ticketStatus.Type == typeof(MultiplayAssignment))    {        assignment = ticketStatus.Value as MultiplayAssignment;    }    switch (assignment?.Status)    {        case MultiplayAssignment.StatusOptions.Found:            gotAssignment = true;            break;        case MultiplayAssignment.StatusOptions.InProgress:            //...            break;        case MultiplayAssignment.StatusOptions.Failed:            gotAssignment = true;            Debug.LogError("Failed to get ticket status. Error: " + assignment.Message);            break;        case MultiplayAssignment.StatusOptions.Timeout:            gotAssignment = true;            Debug.LogError("Failed to get ticket status. Ticket timed out.");            break;        default:            throw new InvalidOperationException();    }} while (!gotAssignment);

CURL

# Call the poll ticket status endpoint with same anonymous token as for the creationcurl -X GET -H "Authorization: Bearer <TOKEN>" \--header 'Content-Type: application/json' \'https://matchmaker.services.api.unity.com/v2/tickets/status?id=<TICKETID>'

REST API