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
Find a session using Unity Matchmaker service
Matchmaking through Unity Matchmaker lets a player join the best-suited session using more advanced rules.
Note: Unity Matchmaker is offered free of charge when you're using Multiplay Hosting or a client-hosted solution provided by Unity (Relay and [Distributed Authority]).
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.
Note: The Multiplayer Services SDK automatically performs QoS measurements, and includes the results with the matchmaking request.
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.
Note: To test this code,
create a queue named Friendly
and use the default pool.
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()
orWithDistributedAuthorityNetwork()
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();