Matchmaking into a session#

Find and join the most suitable multiplayer sessions for a given player.

Matchmaking uses a set of parameters to find and connect players to the most suitable session. The Multiplayer Services SDK supports two ways to find a session:

• Using the Unity Lobby service for quick joins.
• Using the Unity Matchmaker service for advanced rules and network quality controls.

Find a session with Quick Join using Unity Lobby service#

Use the Lobby service to have a player randomly join any session that's 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 this point, if the player can't join a session for any reason, such as all available sessions being full, the quick join operation can optionally create a new session using the CreateSession parameter. Note that the new session is only 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.

Find a session using Unity Matchmaker service#

Use the Unity Matchmaker service to have 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#

• ISession interface
• MatchmakerOptions
• Matchmaker overview
• Matchmaker Rules samples
• QuickJoinOptions
• Unity Lobby service