Create Game Instances #

This topic provides instructions on how to create or join a game instance through matchmaking or directly from the player client or backend service.

Create a game instance from the player client #

Create a new game instance using the player client API

Player clients can create a game instance directly using the Game Instance API for Unreal and Unity, making custom game creation easy.

Player->GameInstanceApi()->Create(
  const FPragma_GameInstance_ExtPlayerCreateRequest& RequestExt, 
  const FGameInstanceIdDelegate& OnComplete
);

Player.GameInstanceApi.Create(
  ExtPlayerCreateRequest requestExt, 
  GameInstanceIdDelegate onComplete
)

Create() invokes the Game Instance Plugin’s handlePlayerCreateRequest() method.

Create a game instance from matchmaking #

Create a new game instance when a match is made

When logic within the machParties() method determines that a set of parties from the Matchmaking queue should be sent to a game instance together, create and return a NewGameInstance object:

• Create a NewGameInstance, providing ExtBackendCreateRequest and gameServerZone in the constructor.
• Add parties to the game instance using addParties().
• 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 Add players via matchmaking.
• 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
    }
}

NewGameInstance.addParties() invokes the Game Instance plugin’s handleBackendCreateRequest() method.

Create a game instance from the backend #

Create a new game instance using backend methods or custom services

Backend services can create a game instance via the GameInstanceApi.kt backend class’s create() method. This workflow bypasses the matchmaking process.

1. Create an instance of the GameInstanceApi.kt class in a Pragma plugin or custom service:

   private val gameInstanceApi: 
       GameInstanceApi = GameInstanceApi(service)
   

2. Call the GameInstanceApi.kt class’s create() method with an ExtBackendCreateRequest payload, players to add to the game instance, a game server version, and game server zone.

   suspend fun create(
       requestExt: ExtBackendCreateRequest,
       playersToAdd: List<PlayerToAdd>,
       gameServerVersion: GameServerVersion,
       gameServerZone: GameServerZone,
   ): PragmaResult<GameInstanceId, PragmaFailure>
   

Create() invokes the Game Instance plugin’s handleBackendCreateRequest().

Create a game instance from a game server #

Create a new game instance using the game server API

Game servers can create and link to a game instance via the MatchApi.CreateAndLink() method. The CreateAndLink() method accepts a list of players to add to the game instance, as well as an ExtBackendCreateRequest payload and a return delegate containing the game start data.

Player->MatchApi()->CreateAndLink(
  TArray<FPragma_GameInstance_BackendPlayerToAdd> PlayersToAdd,
  FPragma_GameInstance_ExtBackendCreateRequest ExtBackendCreateRequest,
  const FGameStartDataDelegate& OnComplete
);

Player.MatchApi.CreateAndLink(
  List<BackendPlayerToAdd> players, 
  ExtBackendCreateRequest requestExt,
  GameStartDataDelegate onComplete
)

CreateAndLink() invokes the Game Instance Plugin’s handleBackendCreateRequest().

Handle player create requests #

Use the GameInstancePlugin.handlePlayerCreateRequest() method to handle game instance creation requests from the player client. To prevent unnecessary or unintended game instance creation, the method prevents a player from creating a game instance by default.

Example usage:

suspend fun handlePlayerCreateRequest(
    gameInstanceSnapshot: GameInstance.GameInstance,
    requestingPlayerId: PlayerId,
    requestExt: ExtPlayerCreateRequest
) {
    gameInstanceApplicationError(
        PragmaError.GameInstanceService_CreateFailed,
        "Player $requestingPlayerId cannot create game instance.")
}

If you want to prevent a player from creating new game instances while in another game instance, use this method to throw an application error to prevent game instance creation.

Handle backend and server create requests #

Use the GameInstancePlugin.handleBackendCreateRequest() method to handle game instance creation requests that come from the Matchmaking service, backend methods, or game servers.

Use this method to perform tasks that need to happen as soon as a game instance is created, such as establishing ExtData (see Create ExtData), or allocating a game server for the game instance (see Allocate game servers).

The handleBackendCreateRequest() method accepts a list of PlayerToAdd objects, which include the following:

• playerId
• ExtBackendAddPlayer
• partyId
• teamNumber

By default, the provided players are added to the game instance and a server is allocated to host the game instance.

Example usage:

  suspend fun handleBackendCreateRequest(
      gameInstanceSnapshot: GameInstance.GameInstance,
      requestExt: ExtBackendCreateRequest,
      playersToAdd: List<PlayerToAdd>
  ) {
      playersToAdd.forEach { player ->
          gameInstanceSnapshot.addPlayer(
            player.playerId, 
            player.partyId, 
            player.teamNumber)
      }

      gameInstanceSnapshot.allocateGameServer(
        ExtAllocateGameServer.getDefaultInstance())
  }

If you want to prevent players from being added to a new game instance while in another game instance, use this method to throw an application error to prevent game instance creation.

To learn how to handle game server allocation failures, see Handle Allocation Failures.

Related events and errors #

Related events

• OnPlayersAdded
• OnAddedToGameInstance
• OnGameInstanceEnteredMatchmaking
• OnGameInstanceLeftMatchmaking

Related errors:

• GameInstanceService_UnknownGameInstanceId
• GameInstanceService_GameInstanceAlreadyInMatchmaking
• PartyService_FailedToEnterMatchmaking
• GameInstanceService_FailedToLeaveMatchmaking
• GameInstanceService_PlayerJoinFailed