Matchmaking Tasks #

Matchmaking features are built and customized using a combination of calls and plugin methods. This page describes common matchmaking operations, along with descriptions of SDK actions and related Matchmaking plugin methods.

Common matchmaking operations include:

For a full list of all available Matchmaking service SDK calls and events, see Matchmaking SDK and Events. For Matchmaking Plugin methods, see the MatchmakingPlugin reference pages.

Initialize the matchmaking process #

Perform any validation logic or party/player transformations before adding the party to a matchmaking queue.

Initialize matchmaking

The matchmaking process starts when parties enter the Matchmaking service from the Party service. The initialize method is called every time a new party enters the Matchmaking service via MatchmakingService.enterMatchmaking, which is called as part of PartyService.enterMatchmaking.

interface MatchmakingPlugin {
  fun initialize(
    queueKey: MatchmakingQueueKey, 
    party: Matchmaking.Party
  ): NewGameInstance? { 
    // Custom logic to run before adding this party to a queue

Add custom logic to the initialize method to determine one of the following outcomes:

  • Party is added to the matchmaking queue
  • Party is fast-tracked to the game instance
  • Party is prevented from joining the queue

If a party is successfully added to the matchmaking queue, the initialize method returns null and a Matchable is created for that party. This Matchable is like a train car, where there’s space for other parties to join until the car is full.

If a party contains all the players needed for a game instance, and the developer wants to enable fast-tracking the game instance and ignore any mismatches that would typically invalidate a matchup (such as skill disparity), initialize can generate a NewGameInstance directly. For example, custom games for events like in-house tournaments may want to skip matchmaking and place players directly in a game instance regardless of skill level or other standard matchmaking data.

If the party cannot join the matchmaking queue due to validation errors, an ExtException is thrown. The party leader will receive the PartyService_FailedToEnterMatchmaking error.

Match parties #

Design logic to compare parties and form or update game instances.

The primary methods in the Matchmaking Plugin are matchParties and matchPartiesWithGame, which are used to perform matchmaking operations such as comparing players and moving them between Matchables.

Compare parties in the Matchmaking queue #

Match parties

As part of the matchParties method, Matchables are compared using a set of developer-defined matchmaking data, such as skill level or preferred game server zones. Only two Matchables can be compared at once. One is considered the anchor Matchable, and the other is considered the other Matchable.

interface MatchmakingPlugin {
  fun matchParties(
    queueKey: MatchmakingQueueKey, 
    anchor: Matchable, 
    other: Matchable
  ): NewGameInstance? { 
    // Custom matchmaking logic 

Build logic in the matchParties method to compare parties in the Matchables. The method can be used to do the following:

Compare parties with an active game instance #

Add to game instance

The Matchmaking service uses Matchmaking Game Instances to allow game instances that have already been sent to a game server to accept new parties by entering matchmaking. When a game instance enters matchmaking to receive more parties, the Matchmaking Plugin’s matchPartiesWithGame method is called.

interface MatchmakingPlugin {
  fun matchPartiesWithGame(
    queueKey: MatchmakingQueueKey, 
    anchor: Matchable, 
    game: Matchmaking.GameInstance
  ): GameInstanceUpdate? { 
    // Custom matchmaking logic for active game instances

Build logic in the matchPartiesWithGame method to determine if a party should be added to the game instance. The method can be used to do the following:

When adding new players to a Matchmaking Game Instance, an OnAddPlayers event is sent via WebSocket connection. To use this feature, your game server must be using WebSockets instead of HTTP to connect to Pragma Engine.

Comparison data #

When comparing Matchables, the following information is available to the Matchmaking Plugin for consideration in your matchmaking logic. This data is stored on the Matchable object.

  • parties - list of matchmaking parties
    • partyId: UUID
    • ext: ExtMatchmakingParty
    • preferredGameServerZones: List
    • players: List<Matchmaking.Player> - details for all players within that matchmaking party
    • playerCount: Int - count of players in this party
    • secondsInQueue(): Int
  • players - list of all players in match parties
    • playerId: UUID
    • socialId: UUID
    • displayName: PragmaDisplayName
    • teamNumber: Int
    • partyId: UUID
    • gameServerZoneToPing: Map<String, Int>
  • matchmakingKey: ExtMatchmakingKey - the ext data associated with the queue
  • gameServerVersion: String - the version of the game server the match would be played on

Move parties #

Take parties from one Matchable and move them to another Matchable or Matchmaking.GameInstance.

Move parties between Matchables #

When the logic in the matchParties method determines that parties should be moved from one Matchable to another, they can be moved by invoking the Matchable.takePartiesFrom method. Both the anchor Matchable and the other Matchable can take parties from one another.

interface Matchable {
  fun takePartiesFrom(matchable: Matchable, parties: List<Matchmaking.Party>)

Add parties to a game instance #

When the logic in the matchPartiesWithGame method determines that additional parties should be moved into the Matchmaking.GameInstance, they can be moved by invoking the GameInstanceUpdate.addParties method. Only the game MatchakingGameInstance can gain parties; the anchor Matchable cannot take parties from the Matchmaking.GameInstance.

interface GameInstanceUpdate {
  fun addParties(parties: List<Matchmaking.Party>, teamNumber: Int = 0) {
    setTeamByPlayers(parties.flatMap { it.players }, teamNumber)
    internalParties.addAll( { it as MatchmakingPartyImpl })
Moving parties between Matchables does not automatically update team numbers. For existing game instances you can use the teamNumber parameter in the addParties method. Otherwise, use the functions in the Assign Teams section to change team numbers as necessary.

Add custom behavior after matchmaking loop #

Define what happens after an anchor Matchable exhausts the matchmaking queue.

If an anchor Matchable makes it through the entire queue without forming a complete match, the default behavior is that the anchor position is moved to the next oldest Matchable in the queue. Custom behavior can be added before the anchor position is moved by defining logic in the endOfLoop method:

fun endOfLoop(
  queueKey: MatchmakingQueueKey,
  anchor: Matchable
): NewGameInstance?

Example: Use this function to examine data such as match queue time and create a NewGameInstance immediately, even if the matchmaking process failed to build an ideal complete Matchable. This capability can be leveraged to build matches with a limited matchmaking pool, such as during testing.

Start or update a game instance #

Create a new game instance or update an existing game instance and send data to the game server.

New game instance

After successfully matching parties using the matchParties or matchPartiesWithGame methods, the game instance data needs to be communicated to the game server. This information is sent when creating and returning a NewGameInstance of GameInstanceUpdate.

When returning a NewGameInstance or a GameInstanceUpdate:

  • Add parties to the game instance using addParties
  • Set team numbers using setTeamByPlayers (optional; default 0)
  • Use setExtGameParty to set/update the ExtGameParty payload for a given party in the game instance update. This data will be set on the GameInstance for the specified party.
  • Use setExtGamePlayer to set/update the ExtGamePlayer payload for a given player in the game instance update. This data will be set on the GameInstance for the specified player.
  • Call the continueMatchmaking method with a MatchmakingQueueKey if the NewGameInstance/GameInstanceUpdate should continue to find players

In addition, if creating a new game instance, set the NewGameInstance.ext (ExtGameInstance) and NewGameInstance.gameServerZone values using the constructor.

Continue matchmaking #

Continue matchmaking process after creating or updating a game.

Continue matchmaking

After you create a NewGameInstance or GameInstanceUpdate from the matchmaking process, you have the option to keep the game instance in the matchmaking queue to continue accepting new players/parties. Game instances remain in matchmaking as long as their continueMatchmaking property is true.

By default, NewGameInstance.continueMatchmaking is false, meaning the new game instance will exit the matchmaking process as soon as it is created. If you want a new game instance to continue accepting new players/parties, call NewGameInstance.continueMatchmaking with the appropriate matchmaking queue key. When called, the continueMatchmaking boolean is set to true and the game instance will be added to the matchmaking queue.

Because GameInstanceUpdate objects are created with the express purpose of entering matchmaking, the GameInstanceUpdate.continueMatchmaking value defaults to true.

Leave matchmaking #

Exit the matchmaking process.

Leave matchmaking as a player #

Player leaves matchmaking

Players can request to leave matchmaking by invoking GameLoopApi.LeaveMatchmaking. This action removes their whole party from the matchmaking service.

  "requestId": 15,
  "type": "matchmakingRpc.LeaveMatchmakingV2Request",
  "payload": {

After the player and their party are removed from matchmaking, players receive a OnLeftMatchmaking event. The GameLoopApi LeaveMatchmaking method also triggers the Party Plugin’s returnFromMatchmaking method, which provides a way to handle players and parties leaving matchmaking. See Party Service Tasks: Return from Matchmaking for more information.

Leave matchmaking as a game instance #

If, after creating a Game Instance Update object, you want the Matchmaking Game Instance to leave matchmaking, use GameInstanceUpdate.stopMatchmaking.

interface GameInstanceUpdate {
  fun stopMatchmaking() {
    continueMatchmaking = false

Game servers can also directly request to leave matchmaking by invoking MatchApi.LeaveMatchmaking.

  "requestId": 16,
  "type": "matchmakingRpc.LeaveMatchmakingV2Request",
  "payload": {

Examples #

Example: Party enters matchmaking service #

When a party enters the matchmaking service it joins the matchmaking queue as a Matchable object. The matchmaking service uses logic defined in the Matchmaking Plugin’s matchParties method to compare Matchable objects. During this matchmaking process, parties may be added to or removed from Matchable objects. If the matchParties method determines that two Matchables are a match, a NewGameInstance is generated and the Matchable is sent to the game server.

Example: Game Instance enters matchmaking #

Depending on your settings, a game instance can enter the matchmaking service and accept additional parties. For example, a battle royale mode may keep all players in a pre-game lobby where they can interact with each other before the full game has been built. This lobby exists on a game server, and this game requires the use of a Matchmaking Game Instance. The matchPartiesWithGame method is called when a Matchmaking Game Instance enters the matchmaking process. Like the matchParties function compares a queued Matchable to an anchor Matchable, the matchPartiesWithGame function compares an anchor Matchable with the Matchmaking.GameInstance.