End Game Instances #

This topic provides instructions on ending game instances using the player client, or backend methods and custom services.

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

End a game instance #

End a game instance for all players

Game instances do not end until the Game Instance interface’s end() method is called. This method can be invoked in the following ways:

• using the game server MatchApi.EndGame() method and the Game Instance Plugin onEndGame() method. By default, onEndGame() calls GameInstance.end().
• by calling GameInstance.end() directly from any Game Instance plugin implementation.

When end of game information has been successfully processed, and the game instance has ended, players will receive the onGameEnded event with the ExtGameEnded payload that relates to them.

Example 1: End a game instance through the MatchApi

To facilitate ending a game instance from the game server side, the game server can call MatchApi.EndGame(). MatchApi.EndGame() invokes GameInstancePlugin.onEndGame(), which, by default, calls GameInstance.end().

Server->MatchApi()->EndGame(
  const FString& GameInstanceId,
  const TArray<FPragma_GameInstance_PlayerGameResult>& PlayerGameResults,
  const FPragma_GameInstance_ExtEndGameRequest& Ext,
  const FOnCompleteDelegate& OnComplete
)

Server.MatchApi.EndGame(
  PragmaId gameInstanceId, 
  IEnumerable<PlayerGameResult> playerGameResults,
  ExtEndGameRequest ext, 
  CompleteDelegate onComplete
)

Example 2: End a game instance when all players are removed

To end a game instance as soon as all players have been removed, call GameInstance.end() from the Game Instance Plugin’s handleBackendRemovePlayersRequest() method:

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

    playersToRemove.forEach { (playerId, _) ->
        gameInstanceSnapshot.removePlayer(playerId, ExtRemovedFromGame.getDefaultInstance())
    }

    if (gameInstanceSnapshot.players.isEmpty()) {
        gameInstanceSnapshot.end(mapOf())
    }
}

Set game instance expiration #

Set a game instance to automatically expire

You can configure game instances to automatically expire after a certain duration (measured from the last time the game instance is accessed). Game instances will be removed after they have not been accessed for the full duration of the expiration. This includes actions such as reading or modifying game instance state or game player state, and player/partner client synchronization operations.

By default, the expiration feature is enabled with an expiration time of one day. If you change the configuration value, any existing game instances that have not been accessed during the expiration duration will be removed. You can disable expiration functionality or change the time limit in the GameInstanceServiceConfig block of your yaml file:

game:
  serviceConfigs:
    GameInstanceServiceConfig:
      enableStaleGameInstanceExpiration: true
      staleGameInstanceExpirationMinutes: 1440

When a game instance expires, the Game Instance plugin onGameInstanceExpired() method is called.

Handle game instance expirations #

Define what happens when a game instance expires

Using the Game Instance plugin onGameInstanceExpired() method, you can define other actions that should occur when a game instance expires.

suspend fun onGameInstanceExpired(
    readOnlyGameInstance: ReadOnlyGameInstance
) {
}

The readOnlyGameInstance is a read-only version of the GameInstance class.

Related events and errors #

Related events:

• OnGameEnded
• OnGameInstanceTerminated

Related errors:

• GameInstanceService_UnknownGameInstanceId