Create or Update Game Instances in Matchmaking #

Create new game instance from matchmaking #

When the Matchmaking service determines that a set of parties from the Matchmaking queue should be sent to a game instance together, it creates a NewGameInstance object, which includes party and player information, as well as extra game information that will be used to create the game instance.

To create a new game instance from the matchParties() method:

• Create a NewGameInstance, providing ExtBackendCreateRequest and gameServerZone in the constructor.
• Add parties to the game instance using addParties(). This method invokes the handleBackendAddPlayersRequest.
• Optionally, use setTeamByPlayers() and setExtForPlayer() to set teams and player data for the parties.
• If you decide your new game instance should continue looking for parties after creation, call newGameInstance.continueMatchmaking() with a MatchmakingQueueKey. In this case, the new game instance will be spun up and then will re-enter matchmaking as a Matchmaking.GameInstance. See match parties with an active game instance
• Return the NewGameInstance.

For example:

override fun matchParties(
    queueKey: MatchmakingQueueKey,
    anchor: Matchable,
    other: Matchable
): NewGameInstance? {

    // Custom matchmaking logic 

    if (isCompleteMatch()) {
        val newGameInstance = NewGameInstance(
          requestExt = ExtBackendCreateRequest.getDefaultInstance(),
          gameServerZone = "North America")
        
        newGameInstance.addParties(allCompatibleParties)
        return newGameInstance
    } else {
        anchor.takePartiesFrom(matchable, compatiblePartiesFromMatchable)
        return null
    }
}

Update game instances via matchmaking #

To add additional players to an existing game instance, enter the game instance into the Matchmaking service. Within the matchPartiesWithGame() method, do the following:

• Create a game instance update object.
• Add appropriate parties to the game instance update using addParties(). This method invokes the handleBackendAddPlayersRequest.
• Optionally, use setTeamByPlayers() and setExtForPlayer() to set teams and player data for the new parties.
• Because GameInstanceUpdate objects are created with the express purpose of entering matchmaking, the matchmaking loop will continue until you explicitly call GameInstanceUpdate.stopMatchmaking().

For example:

override fun matchPartiesWithGame(
    queueKey: MatchmakingQueueKey,
    anchor: Matchmaking.Matchable,
    game: Matchmaking.GameInstance
): GameInstanceUpdate? {

    // Custom matchmaking logic 

    if (isCompleteMatch()) {
        val gameInstanceUpdate = GameInstanceUpdate(
          ExtBackendAddPlayerRequest.getDefaultInstance())
        gameInstanceUpdate.addParties(allPartiesToAdd)
        gameInstanceUpdate.stopMatchmaking()
        return gameInstanceUpdate
    } else {
        game.takePartiesFrom(anchor, compatiblePartiesFromAnchor)
        return null
    }
}