Leave Game Instances #

This topic provides instructions on how to voluntarily leave or remove players from a game instance.

A game instance does not automatically end when all players are removed.

Players are not removed from a game instance until the Game Instance interface’s removePlayer() method is called. This method can be invoked in the following ways:

• by calling the Game Instance API’s leave() method from the player client to voluntarily leave the game instance
• by calling the Match API’s removePlayers() method from the game server
• by calling the GameInstanceApi backend class’s removePlayers() method from a backend method or service

The above scenarios invoke handler methods that in turn can invoke GameInstance.removePlayer(). You can also choose to call GameInstance.removePlayer() from other Game Instance Plugin methods.

Leave a game instance voluntarily #

Voluntarily leave a game instance

Players can request to leave a specific game instance using the Game Instance API Leave() method.

Server->GameInstanceApi()->Leave(
  const FString& GameInstanceId,
  const FPragma_GameInstance_ExtPlayerLeaveRequest& RequestExt, 
  const FOnCompleteDelegate& OnComplete
)

Server.GameInstanceApi.Leave(
  PragmaId gameInstanceId,
  ExtPlayerLeaveRequest requestExt, 
  CompleteDelegate onComplete
)

The Game Instance API’s Leave() method invokes the Game Instance Plugin’s handlePlayerLeaveRequest() method.

Handle player leave requests #

To allow players to voluntarily leave a game instance, call GameInstance.removePlayer() from the Party Plugin’s handlePlayerLeaveRequest() method:

  suspend fun handlePlayerLeaveRequest(
      gameInstanceSnapshot: GameInstance.GameInstance,
      requestingPlayer: GameInstance.GamePlayer,
      requestExt: ExtPlayerLeaveRequest
  ) {
      gameInstanceSnapshot.removePlayer(requestingPlayer, requestExt)
  }

If you want to prevent a player from leaving a game instance voluntarily, use this method to throw an application error. To prevent unintentionally removal, the method throws an error by default.

Remove players #

Remove players from their game instances using the Match API or backend services

From the game server #

To remove one or more players from an active game instance as the game server, call MatchApi.removePlayers(). Game results and metrics can be stored in the ExtBackendRemovePlayersRequest payload.

Server->MatchApi()->RemovePlayers(
  const FString& GameInstanceId,
  const TArray<FPragma_GameInstance_BackendPlayerToRemove>& Players,
  const FPragma_GameInstance_ExtBackendRemovePlayersRequest& Ext,
  const FOnCompleteDelegate& OnComplete
)

Server.MatchApi.RemovePlayers(
  PragmaId gameInstanceId,
  IEnumerable<BackendPlayerToRemove> players,
  ExtBackendRemovePlayersRequest ext,
  CompleteDelegate onComplete
)

The MatchApi.removePlayers() method invoke Game Instance Plugin’s handleBackendRemovePlayersRequest() method.

From the backend #

To remove one or more players from a game instance using backend methods or custom services, use the GameInstanceApi.kt backend class’s removePlayers() method.

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 class’s removePlayers() method with the game instance ID, ExtBackendRemovePlayersRequest payload, and list of players to remove from the game instance.

suspend fun removePlayers(
    gameInstanceId: GameInstanceId,
    requestExt: ExtBackendRemovePlayersRequest,
    playersToRemove: Map<PlayerId, ExtBackendRemovePlayer>
): PragmaResult<Unit, PragmaFailure>

Handle player removal requests #

The MatchApi.RemovePlayers() method and GameInstanceApi class’s removePlayers() method invoke the Game Instance Plugin’s handleBackendRemovePlayersRequest() method, which you can customize to handle player data. By default, the provided players are removed from the game instance.

Example usage:

For example, say you want to let a player know why they are being removed from the game instance. Use the handleBackendRemovePlayersRequest() method to forward the “reason” information on the ExtBackendRemovePlayerRequest to the player’s ExtRemovedFromGame.

override suspend fun handleBackendRemovePlayersRequest(
    gameInstanceSnapshot: GameInstance.GameInstance,
    requestExt: ExtBackendRemovePlayersRequest,
    playersToRemove: Map<PlayerId, ExtBackendRemovePlayer>
) {

    playersToRemove.forEach { (playerId, playerExt) ->
        val ext = ExtRemovedFromGame.newBuilder().setReason(
          requestExt.reason
        ).build()

        gameInstanceSnapshot.removePlayer(playerId, ext)
    }
}

Related events and errors #

Related events:

• OnRemovedFromGameInstance
• OnPlayersRemoved

Related errors:

• GameInstanceService_UnknownGameInstanceId
• GameInstanceService_PlayerNotInGameInstance
• GameInstanceService_LeaveFailed