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.

1. Configure Game Server Hosting

Before enabling Matchmaker it is required to initialize Game Server Hosting. Visit this link to get started with Game Server Hosting.

2. Install the Matchmaker SDK

To install the latest Matchmaker package for Unity:

  1. In Unity, 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.

3. Set up the Matchmaker

To configure Matchmaker, create a new Unity Project and enable Matchmaker in your project.

To create a new Unity Project and enable Matchmaker:

  1. Go to the Unity Dashboard and sign into your account.
  2. From the main menu on the left, select Projects then Create project.
  3. Unity opens a new modal. Enter the project name and use the dropdown to select if your project will be primarily targeted to children under 13.
  4. From the Unity Dashboard, select Multiplayer then Matchmaker > Set up Matchmaker. Follow the steps displayed on the page.

4. Creating a queue and a pool

  1. Click on 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. Click on 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. Click on 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 1 team with a minimum of 1 player and a maximum of 5 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.

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


6. 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' \


7. 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>