Matchmaking into a session#

Matchmaking uses a set of parameters to find the most suitable session for players.

In the Multiplayer Services SDK, there are two ways to find a session. Depending on how advanced you want the matchmaking search to be, you can find a session using the Unity Lobby service or using the Unity Matchmaker service.

Find a session with Quick Join using Unity Lobby service#

Matchmaking through the Lobby service allows the player to randomly join any session that is compatible with the parameters and filters passed to the MatchmakeSessionAsync method.

The following example demonstrates how to find and join a session in a single operation:

var quickJoinOptions = new QuickJoinOptions()
{
    Filters = new List<FilterOption>
    {
        new(FilterField.AvailableSlots, "1", FilterOperation.GreaterOrEqual),
        new (FilterField.StringIndex1, "map 1", FilterOperation.Equal)
    },
    Timeout = TimeSpan.FromSeconds(5),
    CreateSession = true
};

var sessionOptions = new SessionOptions()
{
    MaxPlayers = 2,
    Type = "Session",
}.WithRelayNetwork();

ISession session = await MultiplayerService.Instance.MatchmakeSessionAsync(quickJoinOptions, sessionOptions);

This code tries to join a session that has at least 1 available slot and the property map 1. MatchmakeSessionAsync continues searching for a session until the set timeout of 5 seconds is reached.

At that point, if no available sessions could be joined (for example, all the sessions were full), the quick join operation can optionally create a new session using the CreateSession parameter. Note that the new session will only be created after the set timeout has expired, if set.

When the quick join operation finds or creates a session, it configures networking to use Relay connections.

Additional resources#

• ISession interface
• QuickJoinOptions
• Unity Lobby service

Find a session using Unity Matchmaker service#

Matchmaking through Unity Matchmaker lets a player join the best-suited session using more advanced rules.

Matches can be tuned for network quality using Quality of Service (QoS) rules on the pool configuration. This type of rule ensures that players in the match do not exceed a specified latency to the host or server. For a given match, these rules also select the most suitable region in which to allocate a server or relay.

The following example demonstrates how to find and join a session using Matchmaker:

var matchmakerOptions = new MatchmakerOptions
{
    QueueName = "Friendly"
};

var sessionOptions = new SessionOptions()
{
    MaxPlayers = 2
}.WithDirectNetwork();

var matchmakerCancellationSource = new CancellationTokenSource();

ISession session = await MultiplayerService.Instance.MatchmakeSessionAsync(matchmakerOptions, sessionOptions, matchmakerCancellationSource.Token);

For Matchmaker to find a session for the player, the user is expected to configure the matchmaking rules.

Network choice when matchmaking#

• Using WithDirectNetwork() is the recommended best practice when the Matchmaker pool is configured with Multiplay Hosting.
• WithDirectNetwork() instructs clients to use direct network connections to the allocated server's IP and port.
• Using WithRelayNetwork() or WithDistributedAuthorityNetwork() is required when the Matchmaker pool is configured for client-hosted (peer-to-peer) games.

Cancel matchmaking#

If the player wants to stop the matchmaking process, use the following code:

matchmakerCancellationSource.Cancel();

This indicates to the Multiplayer Services SDK to delete the matchmaking ticket that was sent in the background to the service, and stop the search for a session.

Matchmaking results#

The session also provides access to the Matchmaking Results with the information about the match and the players that are going to connect to the session (their teams and their data).

Some information, such as team breakdown and custom ticket data, is only available through matchmaking results. The results also include the list of expected players, which is handy as it is available immediately and authoritatively before the players join the session and connect.

You can access the matchmaking results with the following code:

var matchmakingResults = session.GetMatchmakingResults();

Additional resources#

• Matchmaker overview
• Matchmaker Rules samples
• MatchmakerOptions
• ISession interface