Create Game Instances Directly #

This topic provides instructions on how to create or join a game instance directly from the player client or backend service. To learn about creating game instances from matchmaking see Define Matchmaking Logic.

Create a game instance from the player client #

Create a new game instance using the player client SDK

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
)

Handle player create requests #

The GameInstanceApi.Create() method invokes the Game Instance Plugin’s handlePlayerCreateRequest() method, which you can customize to handle game instance and player data. 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.

Create a game instance from the backend #

Create a game instance using backend methods and 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>
   

Handle backend create requests #

The GameInstanceApi class’s create() method invokes the Game Instance Plugin’s handleBackendCreateRequest() method. 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