Enter and Leave Matchmaking #

Prepare to enter matchmaking #

Initialize matchmaking

Initialize the matchmaking process when parties enter 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 Matchmaking Plugin’s initialize() method.

interface MatchmakingPlugin {
    fun initialize(
        queueKey: MatchmakingQueueKey,
        matchable: Matchmaking.Matchable
    ): NewGameInstance? {
        return null
    }
}

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

This method will have one of the following outcomes:

  • null (default): A Matchable is added to the matchmaking queue
  • NewGameInstance: A party in the Matchable is fast-tracked to the game instance. 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.

Send a party to matchmaking #

Enter matchmaking

After all players in the party are ready to join matchmaking, a party leader can call the Party API EnterMatchmaking() method to enter the party into matchmaking.

Player->PartyApi().EnterMatchmaking(
  const FOnCompleteDelegate& FOnCompleteDelegate
);

player.PartyApi.EnterMatchmaking(
  CompleteDelegate CompleteDelegate
);

{
  "requestId": 12,
  "type": "PartyRpc.EnterMatchmakingV1Request",
  "payload": {
  }
}

When the party leader issues the EnterMatchmaking() call, the Party plugin’s handlePlayerEnterMatchmakingRequest() method is invoked. If the action is allowed, the party is placed in a new Matchable object and the Matchmaking Plugin’s initialize method is invoked.

In addition, after handlePlayerEnterMatchmakingRequest() is processed, the Party Plugin invokes the buildMatchmakingKey(), buildExtMatchmakingParty(), and buildExtMatchmakingPlayer(), functions. These functions allow for customization of matchmaking keys and any other custom matchmaking content.

override suspend fun buildMatchmakingKey(
    party: Party.Party
): ExtMatchmakingKey {
    return ExtMatchmakingKey.newBuilder()
        .setGameMode(party.ext.selectedGameMode)
        .build()
}

override suspend fun buildExtMatchmakingParty(
    party: Party.Party,
): ExtMatchmakingParty {
    return ExtMatchmakingParty.newBuilder()
        .setMatchStyle(party.ext.matchStyle)
        .build()
}

override suspend fun buildExtMatchmakingPlayer(
    party: Party.Party,
    player: Party.PartyPlayer
): ExtMatchmakingPlayer {
    return ExtMatchmakingPlayer.newBuilder()
        .setMmr(player.ext.mmr)
        .build()
}

When entering matchmaking, a snapshot of the party’s state is captured, including player and party selections. The Matchmaking service uses the values stored in this snapshot even if a user makes changes to the player or party while the party is in matchmaking. The exception to this is when a player leaves a party. If a player leaves a party while the party is in matchmaking, the whole party is removed from the Matchmaking service.

Handle enter matchmaking requests #

Using the Party plugin handlePlayerEnterMatchmakingRequest() method, you can define what happens when a party leader attempts to enter their party into matchmaking, such as recording telemetry data or setting ext data. The party will automatically be entered into matchmaking after the plugin completes.

To prevent the party from entering matchmaking, throw an application error.

suspend fun handlePlayerEnterMatchmakingRequest(
    party: Party.Party,
    requestingPlayer: Party.PartyPlayer
) {
}

Leave matchmaking with the API #

Exit the matchmaking process using the API for Unreal or Unity

Players can request that their party leave matchmaking by invoking the Party API’s LeaveMatchmaking() method. This action removes the player’s whole party from the matchmaking service. After the player and their party are removed from matchmaking, players receive a OnLeftMatchmaking event. The PartyApi.LeaveMatchmaking() function also triggers the Party Plugin’s returnFromMatchmaking() method, which provides a way to handle players and parties leaving matchmaking. See Return from matchmaking for more information.

Player->PartyApi()->LeaveMatchmaking(
  const FOnCompleteDelegate& OnComplete
)

player.PartyApi.LeaveMatchmaking(
  CompleteDelegate onComplete
)

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

Game servers can request that an active game instance leave matchmaking by invoking MatchApi.LeaveMatchmaking().

Player->MatchApi()->LeaveMatchmaking(
  const FString& GameInstanceId,
  const FOnCompleteDelegate& OnComplete
)

player.MatchApi.LeaveMatchmaking(
  PragmaId gameInstanceId,
  CompleteDelegate onComplete
)

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

Return from matchmaking #

Process matchmaking instance exit scenarios

When players return from matchmaking, the Party Plugin’s returnFromMatchmaking() method is invoked. Use this method to perform any necessary updates to player or party states. By default, no selections or relevant party fields are changed when a party leaves matchmaking.

override suspend fun returnFromMatchmaking(
    party: Party,
    returningPlayers: List<PartyPlayer>,
    config: PartyConfig
) {
    returningPlayers.forEach {
        it.isReady = false
    }
}

Related events:

Related errors:

  • PartyService_NotInParty
  • PartyService_PlayerNotLeader
  • PartyService_PlayersNotReady
  • PartyService_GameServerNoLongerCompatible
  • PartyService_FailedToEnterMatchmaking

Leave parties
Define matchmaking logic