Matchmaking #

Matchmaking flow diagram

The Matchmaking service compares available parties and combines them into new game instances to send to the game server. This service handles queue configuration and matchmaking logic. Custom behavior can be defined using the Matchmaking Plugin.

Parties enter the Matchmaking service from the Party service, and are placed into a queue as a Matchable object. Matchable objects iterate through the Matchmaking process to find a match and generate a new game instance. New game instances that have been created can remain within the matchmaking flow or reenter it at any time to accept more players.

The Matchmaking service is structured to work at scale to support the world’s largest games. All matchmaking state is held in-memory upon entry from the Party service to improve performance by avoiding extraneous network hits. This allows the Matchmaking service to remain CPU-dependent and tailored to prioritize for match speed or quality; when more comparison data is used, the matchmaking is slower but the quality of the match is higher.

In the following sections, we’ll take a look at the basic matchmaking flow, some key concepts, and then dive into the specifics of the Matchmaking Plugin, including developer-defined points to allow for any custom matchmaking configuration.

Matchmaking Flow Overview #

At a very high level, there are just a few steps the Matchmaking service cycles through while taking in parties from the Party service and outputting approved new game instances to the Game Instance service.

To enter matchmaking, a party indicates that it’s ready to be sent to the Matchmaking service when a party leader triggers the call to start matchmaking:


At this point, players receive the SessionServicePB.SessionChangedV1Notification. The party is assigned a matchmaking ID, and it becomes a Matchable. All parties entering matchmaking become Matchables.

Matchmaking compares and combines Matchables, as explained in the Match Parties section on the Matchmaking Plugin page; a Matchable can contain multiple parties that have been combined. Once a match has been made, according to the logic defined in the Matchmaking Plugin, a NewGameInstance is generated.

A party can leave matchmaking without finding a viable match in the following two scenarios:

  • A player client can request to leave matchmaking in an expected way, such as by having a player removed from the party.
  • A player client can accidentally leave matchmaking by disconnecting.

If one of the parties in a Matchable leaves matchmaking, the other parties in that Matchable retain their place in the queue, and the exiting party is removed from the Matchable.

Contents #

Key ConceptsKey concepts for understanding the Matchmaking service.
Matchmaking TasksImplementing the Matchmaking features.
All Calls and MethodsAll calls and methods for the Matchmaking service.
Sample ImplementationSample implementation of a basic matchmaking flow.