Get started

Attention: The Digital Services Act (DSA) requires Unity to notify our customers’ end users if Unity takes an action that impacts those end users under the DSA. To comply with this requirement, if you use Unity Gaming Services (UGS) products that rely on the Unity Authentication Service, you must integrate the notification API.

For more information on DSA, refer to the Digital Services Act - compliance update.

To make your game compliant, refer to DSA notifications.

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.


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

Configure your hosting

Before enabling Matchmaker you must either initialize Game Server Hosting or Relay. See Get started (Game Server Hosting) and Get started (Relay).

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 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
  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 Game Server Hosting, first select Game Server Hosting in the dropdown menu, then select the Fleet and Build Configuration created when Game Server Hosting was configured.
  • If you're using Relay, select Relay 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 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


# Fetch anonymous token
curl -X POST -H "ProjectId: <projectId>"

# 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": {}
}' \


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;
    //Rate limit delay
    await Task.Delay(TimeSpan.FromSeconds(1f));

    // Poll ticket
    var ticketStatus = await MatchmakerService.Instance.GetTicketAsync("<ticket id here>");
    if (ticketStatus == null)

    //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;
        case MultiplayAssignment.StatusOptions.InProgress:
        case MultiplayAssignment.StatusOptions.Failed:
            gotAssignment = true;
            Debug.LogError("Failed to get ticket status. Error: " + assignment.Message);
        case MultiplayAssignment.StatusOptions.Timeout:
            gotAssignment = true;
            Debug.LogError("Failed to get ticket status. Ticket timed out.");
            throw new InvalidOperationException();

} while (!gotAssignment);


# 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' \


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 -X GET http://localhost:8086/payload/<allocation_uuid>