Use the Matchmaker#

Sample#

There is a sample scene and script available in the package.

To install the sample:

1. Open the Unity Package Manager by going to Window > Package Manager.
2. Within the Package Manager, find the Unity Matchmaker Package.
3. Under the Samples section, select Import.

Use the sample#

Before using the sample, make sure that you have set up at least one queue and pool in your matchmaker. See Configure the Matchmaker.

To use the sample:

1. Open the Scene.
2. Select the MatchmakerTicketer GameObject.
3. In the inspector view, make sure that the QueueName is set to the queue name you created on the dashboard.
4. Select Play > Sign In in the game view. This signs in the player anonymously.
5. Select Find Match in the game view.

Common namespaces#

The following code excerpts for the SDK use the following using statements.

using Unity.Services.Core;
using Unity.Services.Authentication;
using Unity.Services.Matchmaker;
using Unity.Services.Matchmaker.Http;
using Unity.Services.Matchmaker.Models;
using StatusOptions = Unity.Services.Matchmaker.Models.MultiplayAssignment.StatusOptions;

Create a ticket#

To create a ticket using the SDK, create a new CreateTicketOptions object with a QueueName, Attributes, Players, and CustomData. This object can then be passed to MatchmakerService.Instance.CreateTicketAsync(). The response from this async method will include the created ticket ID. This ticket ID is useful for checking the ticket or match status.

The following code snippet shows how this works:

var attributes = new Dictionary<string, object>
{
    { "platform", "ps4" },
    { "totalSkill", 9441 }
};

var players = new List<Player>
        {
            new Player("Player1", new Dictionary<string, object>{ { "preferredMap", "dune" } })
        };


// Set options for matchmaking
var options = new CreateTicketOptions("Free For All", attributes);

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

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

The response returned by CreateTicketAsync will return the ticket ID to use for getting the ticket status or deleting the ticket from the matchmaking queue.

Poll for ticket status#

Once a ticket is created, you can use the ticket ID to check the status of finding a match. To check the status of a ticket you can call the MatchmakerService.Instance.GetTicketAsync("<ticket id here>") async method passing in the ticket ID. The response will include a TicketStatusResponse object.

Unity recommends that you call this method once every second until the

TicketStatusResponse object returned is no longer null. Once this condition is true, the TicketStatusResponse object will contain the result of matchmaking.

The following code snippet shows how this works: 

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

} while (!gotAssignment);

Delete a ticket#

In some cases, a player might decide to cancel matchmaking to stop finding a match. We recommend deleting the ticket to prevent issues when the same player tries to create another ticket. To delete a ticket, call the MatchmakerService.Instance.DeleteTicketAsync("<ticket id here>") async method passing in the ticket ID.

The following code snippet shows how this works:

await MatchmakerService.Instance.DeleteTicketAsync("<ticket id here>");

Retrieve Match Info on the DGS#

To retrieve the match information on the DGS refer to the Integrations section.

Use the in-package sample#

A pre-setup sample is included in the SDK package that includes a loop polled scene and script that initializes and authenticates matchmaker and exposes some simple UI to create a ticket, find a match, and delete a ticket.

To access the sample:

1. Go to the Editor > Package Manager.
2. Under Samples, select Import on the Matchmaking Polling Sample. The test scene includes a simple UI for sign-in and finding a match.

In the hierarchy, there is an object with an attached script called MatchmakerTicketer that drives the initialization, authentication, UI control and calls to the Matchmaker SDK that manage the functionality in this sample.