Game Instance Tasks #

Game Instance features are built and customized using a combination of calls and plugin methods. This page describes common game instance operations, along with descriptions of SDK actions and related plugin methods.

Common game instance operations include:

For a full list of all available Game Instance calls and methods, see Game Instance Methods, Calls, and Events.

Send custom game data to the game server #

When a game server is allocated a game, the game server SDK calls getGameStartDataV1 to get the game start data.

The getGameStartDataV1 function invokes the Game Instance Plugin’s buildExtGameStart plugin method once. This method builds the ExtGameStart payload, which declares custom data to start the game instance.

suspend fun buildExtGameStart(
    gameInstance: GameInstance.GameInstance
): ExtGameStart

The getGameStartDataV1 function also invokes the Game Instance Plugin’s buildExtGameServerPlayer plugin method for each player in the game. This method builds the ExtGameServerPlayer payload, which declares custom data to send to the game server for a player.

suspend fun buildExtGameServerPlayer(
    gameInstance: GameInstance.GameInstance, 
    player: GameInstance.GamePlayer
): ExtGameServerPlayer

Send custom game data to players #

When a player is added to a game, the OnAddedToGame event triggers with the ExtAddedToGame payload.

public event Action<PragmaId, ExtAddedToGame> OnAddedToGame;

The buildExtAddedToGame function allows for customization of ExtAddedToGame data to send to the player when they are added to a new game. This data will be sent to the players immediately, even if a game server is still preparing to host the game instance.

suspend fun buildExtAddedToGame(
    gameInstance: GameInstance.GameInstance,
    player: GameInstance.GamePlayer
): ExtAddedToGame

Verify players #

Pragma Engine can use connection tokens to verify the correct players join a game instance. The player verification process is optional, but recommended for competitive games.

Once a game server calls ConnectPlayers to indicate that it’s ready for players to join the game instance, players receive a HostConnectionDetailsNotification, which includes the connection token, as well as basic connection details, such as URL and port. The notification also includes the ExtPlayerConnectionDetails ext, which can be used to define custom information unique to each player.

The player client needs to provide the connection details to the game server upon joining the game instance. The game server then sends the connection token to the engine via VerifyPlayer so the engine can validate the token. If the engine determines the token is valid, players can join the game instance.

A player who disconnects and reconnects to the same game instance will receive the same connection token on the MatchReconnectV1Notification.

Enter matchmaking to connect more players #

Game instances can enter matchmaking to accept more players using the MatchmakingPlugin matchPartiesWithGame function. (See Add parties and players to active game instances).

When a game instance enters matchmaking, the Game Instance Matchmaking Plugin builds customized data about the game instance (ExtMatchmakingGameInstance), the parties within it (ExtMatchmakingGameParty), or the players within it (ExtMatchmakingGamePlayer). This data will be made available to the matchmaking plugin when comparing game instances.

suspend fun buildExtMatchmakingGameInstance(
    gameInstance: GameInstance.GameInstance
): ExtMatchmakingGameInstance
  
suspend fun buildExtMatchmakingGameParty(
    gameInstance: GameInstance.GameInstance,
    party: GameInstance.GameParty
): ExtMatchmakingGameParty

suspend fun buildExtMatchmakingGamePlayer(
    gameInstance: GameInstance.GameInstance,
    party: GameInstance.GameParty,
    player: GameInstance.GamePlayer
): ExtMatchmakingGamePlayer

Reconnect players #

Pragma Engine provides a way to reconnect players who disconnect during a game instance. This feature can be configured via the GameInstanceServiceConfig.reconnect config value with the following options in the GameInstanceReconnect enum: OFF, REQUIRED, and OPTIONAL. The default value is OFF.

valuedescription
OFFWhen the player reconnects to the engine, no reconnect to the game instance is attempted.
OPTIONALWhen the player reconnects to the engine, the game instance reconnect flow is triggered, and the player can accept or decline the game instance.
REQUIREDWhen the player reconnects to the engine, the game instance reconnect flow is triggered, and the player must reconnect to the game instance.

When the configuration is set to OPTIONAL or REQUIRED and the game instance reconnect flow is triggered, the engine sends a MatchReconnectV1Notification to the player’s client with the game instance details. If the game instance is still active (and if the player accepts the reconnect when the OPTIONAL value is set), the client uses these connection details to reconnect the player to the active game instance.

When the configuration is set to OPTIONAL and the player declines the reconnect with DeclineReconnect, the game server receives a PlayerDeclinedReconnectV1Notification to inform the game server that the player is no longer expected to return to the game instance. At this point, the game server can invoke removePlayers for the departing player to provide any details it would like to record about the player’s performance.

ReconnectedPlayer->Session()->GameLoopApi().DeclineReconnect(
  UPragmaPartyService::FOnCompleteDelegate::CreateLambda(
    [this, OnStepComplete](
    const TPragmaResult<> Result)
    {
      // OnComplete Delegate
    }));

var promise = new Promise();
  reconnectedPlayer.GameLoopApi.DeclineReconnect(promise);
yield return promise.Future;

Connection details #

The service endpoint matchReconnectV1 is called automatically if a player logs in while their session indicates they’re in an existing game instance. This results in a MatchReconnectV1Notification being sent to the player’s client, and includes the host connection details. These details can also be requested from a player client using the matchConnectionDetailsV1endpoint.

Example: Managing a reconnect scenario

Pragma Engine keeps track of a player’s current game instance, and will provide the game instance details if the player logs in again so they can reconnect to the existing game instance.

Below are the steps for a sample scenario, along with the relevant calls for each step in both Unity and Unreal.

  1. Login: A player loses their connection during the game and needs to reconnect. When they relaunch the client they will log in to Pragma again.

    unityunreal
    player.LoginPlayer->Login

  2. A MatchReconnectV1Notification with connection details is sent to the player’s client on login. The notification triggers the OnMatchReconnect event, allowing the player to connect back to their game using the rebroadcasted connection information.

    unityunreal
    player.GameLoopApi.OnMatchReconnectPlayer->GameLoopApi().OnMatchReconnect

  3. (optional) If the player’s client needs to request details again, it can manually invoke the matchConnectionDetailsV1 endpoint.

    unityunreal
    player.GameLoopApi.MatchConnectionDetailsV1Player->GameLoopApi().MatchConnectionDetailsV1

Remove players from a game instance #

The game server can call removePlayers to remove one or more players from an active game instance. Game results and metrics can be stored in the ExtRemovePlayersRequest payload (for game-specific data) and the ExtRemovePlayer payload in the list of players to remove (for player-specific data).

Server->MatchApi()->RemovePlayers(
  GameInstanceId,
  PlayersToRemove,
  ExtRemovePlayersRequest,
  RemovePlayersDelegate
)

Server.MatchApi.RemovePlayers(
  GameInstanceId,
  PlayersToRemove,
  ExtRemovePlayersRequest,
  RemovePlayersCallback
)

After a player has been removed from the party, the Game Instance Plugin onRemovePlayers is called. This method is used to prepare any custom data (ExtRemovedFromGame) to send to the removed players.

suspend fun onRemovePlayers(
    gameInstance: GameInstance.GameInstance,
    playersToRemove: List<PlayerToRemove>,
    requestExt: ExtRemovePlayersRequest
): Map<PlayerId, ExtRemovedFromGame>

Removed players will receive the onRemovedFromGame event with the ExtRemovedFromGame payload.

RemovePlayers also invokes the Party Plugin’s returnFromMatch method and provides a list of the specific players being removed from the game. See Party Implementation for more information.

End a game instance #

EndGame must be invoked to end the game instance, even if all players have left the game instance.

The game server calls EndGame to end the game instance and perform end game processes.

Server->MatchApi()->EndGame(
  GameInstanceId,
  PlayerGameResults,
  ExtEndGameRequest,
  EndGameDelegate
)

Server.MatchApi.EndGame(
  GameInstanceId,
  PlayerGameResults,
  ExtEndGameRequest,
  EndGameCallback
)

After the game instance has ended, the Game Instance Plugin onEndGame method is invoked to create a new ExtGameEnded payload per player. This payload can store game results, metrics, grants, and other end game data.

suspend fun onEndGame(
    gameInstance: GameInstance.GameInstance,
    playerGameResults: List<PlayerGameResult>,
    requestExt: ExtEndGameRequest
): Map<PlayerId, ExtGameEnded>

Players removed from the game instance before the game ends can be included in end game processes and receive end game data. This is useful if you have a game that issues additional rewards to players at the end of the game, whether or not they are still active.

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

EndGame also invokes the Party Plugin’s returnFromMatch method and provides a list of players currently in the game instance. This list does not include players previously removed from the game instance. See Party Implementation for more information.

Handle game end failures #

Pragma Engine provides two features to account for situations where the end game request never arrives: Keep Alive Heartbeats and Absolute Timeouts. A game end payload can fail to arrive due to game server crashes, game code bugs, network issues, or malicious actors. These features help release players from a game instance and allow them to reenter the game loop to start a new game instance.

In these failure situations, the player receives an OnMatchTermination event, including a reason for shutdown.

When the game is forced to shut down, no end game data is processed.

Keep alive heartbeats #

The Keep Alive Heartbeats feature requires game servers to send occasional heartbeats after starting a game instance. This allows Pragma Engine to confirm that the game instance and game server are still operational.

When enabled, Pragma Engine expects a MatchKeepAliveV1 request based on the configured amount of time (keepAliveIntervalMillis). If the engine doesn’t receive the request after a consecutive set of the configured amount of missed values (keepAliveMissesLimit), it ends the game instance and returns players to their party, calling the Party Plugin returnFromMatch method.

Game servers using the Pragma Engine-provided Unreal and Unity SDKs automatically send heartbeats to Pragma Engine on a successful response of the ConnectPlayers method when this feature is enabled. It does this by starting a background process that makes the necessary MatchKeepAliveV1 requests every keepAliveIntervalMillis while the match is progress.

The configuration for this feature can be found in GameInstanceServiceConfig. This feature is enabled by default, with a 30000 milliseconds (30 seconds) value for keepAliveIntervalMillis in production environments, and a keepAliveMissesLimit value of 3.

A separate keepAliveIntervalMillis configuration for development in dev-defaults.yml is set to 5000 milliseconds (5 seconds). To modify these values, edit the local-dev.yml file.

To disable this feature, set the GameInstanceServiceConfig.enableKeepAlive configuration property to false.

As a best practice, we recommend against turning off the Keep Alive Heartbeats feature, as it’s critical for game flow health.

Absolute timeouts #

The Absolute Timeouts feature makes Pragma Engine end a game instance after a specified period of time elapses.

To enable this feature, set the GameInstanceServiceConfig.enableAbsoluteTimeout configuration property to true and provide a value for GameInstanceServiceConfig.absoluteTimeoutMillis.

Once enabled, Pragma Engine starts a background task that runs after a configured amount of time (absoluteTimeoutMillis) passes. If a game instance is still in progress when the background task runs, the engine ends the game instance and returns players to their party, calling the Party Plugin returnFromMatch method.

This process releases the game instance from the Game Instance Service. The game server itself may still need to end or cleanup the game, and/or shutdown.

Game Instance Key Concepts
All Methods, Calls, and Events