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 SDK and plugin function, see Matchmaking Reference.

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 MatchmakingService.enterMatchmaking call, which is called as part of PartyService.enterMatchmaking, places the party into a Matchable object and invokes the initialize method.

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

The Matchable passed to the initialize method will include an empty ExtMatchable. Use initialize to set data on the ExtMatchable before the Matchable enters the queue.

This method will have one of the following outcomes:

  • Matchable is added to the matchmaking queue: return null
  • Party in the Matchable is fast-tracked to the game instance: generate and return a NewGameInstance. 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.
  • Matchable is prevented from joining the queue: an ExtException is thrown. The party leader will receive the PartyService_FailedToEnterMatchmaking error.

Related events:

Match parties in the matchmaking queue #

Design logic to compare parties to send to a game instance

Match parties

You can customize the matchParties() method to compare two Matchables in the matchmaking queue with the goal of creating a set of parties that should be sent to a game instance together. matchParties() compares a specific anchor Matchable with all other Matchables in the queue before changing anchor to the next-oldest queue member.

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

Within matchParties(), do the following:

  • compare parties in the anchor Matchable to parties in the other Matchable using a set of developer-defined matchmaking data, such as skill level or preferred game server zones.

  • move parties between the two Matchables to work toward creating a set of parties to send to a new game instance. Both anchor and other can take parties from one another using takePartiesFrom(). When parties move between Matchables, that change persists for the life of the party unless the party is deliberately moved elsewhere.

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

  • When a Matchable contains a set of parties that should be sent to a new game instance together:

    • create a NewGameInstance, setting ExtGameInstance and NewGameInstance.gameServerZone in the constructor
    • add parties to the game instance using addParties():
    class NewGameInstance(
  var ext: ExtGameInstance,
  var gameServerZone: GameServerZone,
) {
    fun addParties(parties: List<Matchmaking.Party>, teamNumber: Int = 0) {
      internalParties.addAll(parties.map { it as MatchmakingPartyImpl })
      setTeamByPlayers(parties.flatMap { it.players }, teamNumber)
    }
}
    • optionally, use setTeamByPlayers(), setExtGameParty(), and setExtGamePlayers() to set teams and player and party data for the parties
    • return the NewGameInstance

    At this point, a new game instance is created. Added players are considered associated with the game instance and removed from matchmaking by exchanging the MATCHMAKING_ID on their sessions with a GAME_INSTANCE_ID.

  • if you decide your new game instance should continue looking for parties, call continueMatchmaking() with a MatchmakingQueueKey

If the matchParties method throws an exception, the Matchmaking service logs an error and removes both the anchor Matchable and the other Matchable from the queue to allow for debugging. Players are notified via a SessionChangedV1Notification. The anchor position is then reset to the oldest Matchable in the queue.

See also: Add custom behavior after matchmaking loop.

Match parties with an active game instance #

Design logic to add parties to an existing game instances

Add to game instance

When a game instance enters matchmaking to receive more parties, the Matchmaking Plugin’s matchPartiesWithGame() method is called for each anchor Matchable in the specified matchmaking queue. Use matchPartiesWithGame() to determine whether parties in a Matchable should be added to the existing game instance.

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

Within matchPartiesWithGame(), do the following:

  • use developer-defined matchmaking data, such as skill level or preferred game server zones, to determine if a party or parties in the anchor should be added to the current game instance.

  • if parties in the Matchable should be added to game instance:

    • create a GameInstanceUpdate object

    • call GameInstanceUpdate.addParties() with the party or parties from the anchor to add to the game instance:

      class GameInstanceUpdate {
  fun addParties(parties: List<Matchmaking.Party>, teamNumber: Int = 0) {
    setTeamByPlayers(parties.flatMap { it.players }, teamNumber)
    internalParties.addAll(parties.map { it as MatchmakingPartyImpl })
  }
}

      Pragma Engine takes care of removing the appropriate parties from the anchor Matchable and advancing the anchor to the next-oldest queue member.

    • optionally, use setTeamByPlayers(), setExtGameParty(), and setExtGamePlayers() to set teams and player and party data for the new parties

    • return the GameInstanceUpdate

  • if you decide your game instance should not take any more parties or no more suitable parties exist, call GameInstanceUpdate.stopMatchmaking()

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.

Comparison data #

When comparing Matchables, the following information is available to the Matchmaking Plugin for consideration in your matchmaking logic.

  • parties: list of parties in the Matchable
    • partyId: unique party ID
    • ext (ExtMatchmakingParty): custom party data to inform the matchmaking process
    • preferredGameServerZones: list of the party’s preferred game server zones
    • players: list of player objects within the party
    • playerCount: number of players in the party
    • secondsInQueue(): number of seconds the party has been in the matchmaking queue
  • players: list of all the players in the Matchable
    • playerId: unique player ID
    • socialId: player’s unique social ID
    • displayName: player’s unique display name
    • teamNumber: player’s team number
    • partyId: unique party ID for the party the player is in
    • gameServerZoneToPing: map of the player’s client-supplied ping map, keyed by gameServerZone ID
    • ext (ExtMatchmakingPlayer): custom player data to inform the matchmaking process
  • extMatchable (ExtMatchable): use this ext to store data calculated within the Matchmaking loop so you don’t have to recompute it on every matchParties call
  • matchmakingKey (ExtMatchmakingKey): custom data about the Matchable’s matchmaking queue
  • gameServerVersion: version of the game server the match would be played on

Related events:

Related errors:

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?
The endOfLoop method is also called if there is only one item in the matchmaking queue.

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.

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 PartyApi.LeaveMatchmaking (Unreal) or GameLoopApi.LeaveMatchmaking (Unity). This action removes their whole party from the matchmaking service.

Player->PartyApi()->LeaveMatchmaking(
OnComplete
)

player.GameLoopApi.LeaveMatchmaking(
OnComplete
)

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

After the player and their party are removed from matchmaking, players receive a OnLeftMatchmaking event. TheLeaveMatchmaking() function 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.

Player->MatchApi()->LeaveMatchmaking(
  gameInstanceId,
  Delegate
)

player.MatchApi.LeaveMatchmaking(
  gameInstanceId,
  callback
)

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

Related events:

Related errors:

Customize queue names for reporting #

Customize queue names for metrics/logging

For purposes of viewing metrics and logs, you might want to group various matchmaking queues into one metric/log entry. Using the Matchmaking Plugin’s getQueueName() function, you can generate a queue name based on a queue’s ExtMatchmakingKey property.

For example, say your ExtMatchmakingKey contains a game mode, along with various other parameters needed for matchmaking purposes (region, difficulty, etc.). For reporting purposes, you might want matchmaking queues with the same game mode to appear as one metric. To do so, customize the getQueueName() function in your implementation of the Matchmaking Plugin:

fun getQueueName(extMatchmakingKey: ExtMatchmakingKey): String {
      
    return extMatchmakingKey.gameMode;
}

The getQueueName() function is called during instantiation of a new matchmaking queue or when a metric/log requires a queue name and doesn’t already have access to the queue. In our example, all queues with the same game mode will get the same queue name and be presented as one for metric/logging purposes.

If you don’t customize the getQueueName function, the function returns “undefinedqueueName” by default.

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.


Matchmaking Overview
Matchmaking Reference