Get started#

This guide walks you through the different steps required to install the Matchmaker SDK, enable Matchmaker, create the first matchmaking ticket and create a Multiplay Hosting allocation.

Prerequisites#

To get started with Matchmaker, you need to do the following:

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

Configure your hosting#

Before enabling Matchmaker, either initialize Multiplay Hosting or a client-hosted solution provided by Unity. Refer to Get Started with Multiplay Hosting, Get Started with Relay, and the Distributed Authority Quickstart.

Install the Matchmaker SDK#

To install the latest Matchmaker package for Unity:

1. In the Unity Editor, navigate to Window > Package Manager.
2. From the Package Manager, search for the following package:
   • For Unity 6 and above: com.unity.services.multiplayer
   • For Unity 2022 LTS and earlier: com.unity.services.matchmaker
3. Select the package and select Install.

Refer to the Package Manager documentation for more information.

Set up Matchmaker#

You can set up and manage Matchmaker through the Unity Cloud Dashboard:

1. Go to cloud.unity.com.
2. Select the Products tab from the sidebar.
3. Under Gaming Services > Multiplayer, go to Matchmaker and select Launch.

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#

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.

1. Click Next.

Define 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:

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

This creates matches of one team with a minimum of one player and a maximum of five players.

1. Click on Logic Builder and set the Default QoS Region by selecting one the regions in the dropdown.
2. Click on Create at the bottom of the page.

Matchmaker is now configured. You can check the Queue and Pool that were created by clicking on Queues in the menu under the Matchmaker section.

Create a matchmaking ticket#

Now that the matchmaker is configured we can create and send a ticket to request a Multiplay Hosting allocation:

Unity SDK

var players = new List<Unity.Services.Matchmaker.Models.Player>
{
    new ("Player1", new Dictionary<string, object>())
};


// Set options for matchmaking
var options = new CreateTicketOptions(
  "Default", // The name of the queue defined in the previous step,
  new Dictionary<string, object>());

// Create ticket
var ticketResponse = await MatchmakerService.Instance.CreateTicketAsync(players, options);

// Print the created ticket id
Debug.Log(ticketResponse.Id);

CURL

# Fetch anonymous token
curl -X POST -H "ProjectId: <projectId>" https://player-auth.services.api.unity.com/v1/authentication/anonymous

# Call the create ticket endpoint
curl -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

https://services.docs.unity.com/matchmaker/v2/index.html#tag/Tickets/operation/createTicket

Poll ticket status#

Once the ticket is created, the client polls to get the status of the ticket using the ticket ID returned when creating the ticket.

When the ticket is assigned to a match and a server is allocated, Matchmaker adds the server information to the ticket status response.

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 creation

curl -X GET -H "Authorization: Bearer <TOKEN>" \
--header 'Content-Type: application/json' \
'https://matchmaker.services.api.unity.com/v2/tickets/status?id=<TICKETID>'

REST API

https://services.docs.unity.com/matchmaker/v2/index.html#tag/Tickets/operation/getTicketStatus

Matchmaking Results#

On the server side, when the server is allocated it is possible to fetch the Matchmaking Results about the match made using the Payload Allocation.

Matchmaking results give the server information about the different players that are supposed to be in the match, their data as well as their distribution in the different teams.

Unity SDK

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

CURL

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