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 Game Server Hosting allocation.

Prerequisites

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

Configure Game Server Hosting

Before enabling Matchmaker you must initialize Game Server Hosting. Visit Get started to start working with Game Server Hosting.

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 com.unity.services.matchmaker or scroll through the Unity Registry to find the Matchmaker package.
  3. Select the package and click Install.

See 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 the Fleet and Build Configuration created when Game Server Hosting was configured. Click Next.

Define the Rules that will be 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 Game Server Hosting allocation:

Unity SDK

var players = new List<Player>
{
    new Player("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.

This code only works on the server allocated by Game Server Hosting.

Unity SDK

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

Note: Use the server.json file to get a server’s allocation UUID. [!NOTE] You will need to install the Game Server Hosting SDK to access the matchmaking results

CURL

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