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. Click on 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. Click on Next.
3. Select your hosting type:

• If you're using Multiplay Hosting, first select Multiplay Hosting in the dropdown menu, then select the Fleet and Build Configuration created when Multiplay Hosting was configured.
• If you're using a client-hosted solution provided by Unity, select Client Hosting in the dropdown menu.

4. Click Next.

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

5. Click on Logic Builder and set the Default QoS Region by selecting one the regions in the dropdown.
6. Click on 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

Matchmaking Results

Unity SDK

var payloadAllocation = await MultiplayService.Instance.GetPayloadAllocationFromJsonAs<MatchmakingResults>();

CURL

curl -X GET http://localhost:8086/payload/<allocation_uuid>