Enter Matchmaking #

This topic provides instructions on how to prepare your party for matchmaking, and how to enter the matchmaking process.

Send a party to matchmaking #

Request a party be sent to matchmaking

When all players in the party are ready to join matchmaking, a party leader can call the Party API EnterMatchmaking() method:

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

player.PartyApi.EnterMatchmaking(
  CompleteDelegate CompleteDelegate
);

The Party API’s EnterMatchmaking() method invokes the Party plugin’s handlePlayerEnterMatchmakingRequest() method.

Handle enter matchmaking requests #

Respond to player requests to enter matchmaking

Using the Party plugin handlePlayerEnterMatchmakingRequest() method, you can define what happens when a party leader attempts to enter their party into matchmaking. In the following example, we set each player’s rich presence to “in matchmaking”.

suspend fun handlePlayerEnterMatchmakingRequest(
    party: Party.Party,
    requestingPlayer: Party.PartyPlayer
) {
    party.players.forEach { player ->
      val extBackendRich: ExtRichPresenceBackendRequest = ExtRichPresenceBackendRequest
          .newBuilder()
          .setInMatchmaking(true)
          .build()
      presenceApi.setRichPresence(player.playerId, extBackendRich)
  }
}

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

After handlePlayerEnterMatchmakingRequest() completes, matchmaking-related exts are built and the party is sent to the matchmaking service. When a party makes it to the Matchmaking service, a Matchable is created and passed to the Matchmaking Plugin’s initialize() method.

Build matchmaking party and player data #

Build ext data to use during the matchmaking process

The PartyPlugin.handlePlayerEnterMatchmakingRequest() invokes the buildExtMatchmakingParty() and buildExtMatchmakingPlayer() methods, where you can customize the ExtMatchmakingParty and ExtMatchmakingPlayer data used in matchmaking logic. For example, the following implementations set the party matchmaking style and the player’s MMR:

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()
}

Manage queues #

Determine how matchmaking queues are created and named

Define and build queue keys #

A matchmaking queue key contains:

• GameServerVersion: creates a queue for each version of the game server
• ExtMatchmakingKey: creates queues by developer-defined data

Different scenarios determine which queues parties enter:

• If you only set one value (GameServerVersion or ExtMatchmakingKey), players with matching set values will enter the same queue
• If you set both the GameServerVersion and ExtMatchmakingKey, only players with matching GameServerVersion AND ExtMatchmakingKey values will enter the same queue
• If you do not set the GameServerVersion or ExtMatchmakingKey, all player will enter one global queue.

For example, consider a game that has multiple game modes: 3v3 Ranked, 3v3 Casual, and Co-op Adventure. We can configure the ExtMatchmakingKey proto to consider the game mode.

message ExtMatchmakingKey {
    GameMode game_mode = 1;
}

enum GameMode {
    Unspecified = 0;
    ThreeVsThreeRanked = 1;
    ThreeVsThreeCasual = 2;
    CoopAdventure = 3;
}

Then, in PartyPlugin.buildMatchmakingKey(), we set the ExtMatchmakingKey game mode to the Party’s selected game mode. buildMatchmakingKey() is called after handlePlayerEnterMatchmakingRequest() completes.

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

Customize queue names for reporting #

For purposes of viewing metrics and logs, you might want to group various matchmaking queues into one metric/log entry. You can generate a queue name using the Matchmaking Plugin’s getQueueName() method, which 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.

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:

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

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

Enter the matchmaking queue #

Add the party to a matchmaking queue

When a party makes it to the Matchmaking service, a Matchable is created and passed to the Matchmaking Plugin’s initialize() method. The Matchable will include an empty ExtMatchable payload. Use initialize() to set data on the ExtMatchable before the Matchable enters the queue. Return null (default) to add the Matchable to the matchmaking queue identified by the queue key and begin the matchmaking process.

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

If the matchmaking queue only contains one Matchable, the matchParties()/matchPartiesWithGame() method is skipped and endOfLoop() is called.

Bypass matchmaking #

Bypass the matchmaking service and send a party directly to a new game

To bypass the matchmaking service and send a party directly to a new game instance, return a NewGameInstance object in the Matchmaking plugin initialize() method:

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

See Handle matchmaking and backend create requests for next steps.

Related events and errors #

Related events:

• OnEnteredMatchmaking
• OnPartyUpdated
• OnPartyPlayerDataChanged

Related errors:

• PartyService_NotInParty
• PartyService_PlayerNotLeader
• PartyService_PlayersNotReady
• PartyService_GameServerNoLongerCompatible
• PartyService_FailedToEnterMatchmaking