Game Instance Reference #

Game Instance service SDK #

The Pragma SDK provides methods that developers can use to facilitate game instance processes, such as connecting more players or ending the game. The SDK includes methods for Game Instance service implementation through the GameLoopApi and MatchApi classes, depending on whether the call comes from the game client or game server, respectively. The tables below contains a list of all the GameLoopApi and MatchApi methods relevant to the Game Instance service.

GameLoopApi (player client) SDK methods #

Call	description
`DeclineReconnect`	Signals that the player is declining to reconnect to the game instance after disconnecting.
`GetHostConnectionDetails`	Provides player with connection information for the game instance. This is useful for a player if they disconnect and later decide to reconnect.

MatchApi (game server) SDK methods #

Call	description
`ConnectMorePlayers`	Confirms the connection details and game instance `ext` data for the found players.
`ConnectPlayers`	Signals a game instance is ready to start.
`EndGame`	Signals a game instance has completed.
`RemovePlayers`	Processes player game results for a subset of players within a game instance. Does not end the game instance.
`EnterMatchmaking`	Allows an active game instance to enter matchmaking to accept additional parties.
`LeaveMatchmaking`	Removes an active game instance from matchmaking.
`VerifyPlayer`	Uses player connection token to verify that connecting players are not misrepresenting their Pragma identity.
`KeepAliveTask`	Ensures a game instance does not get ended by the Game Instance service.
`UpdateGameInstance`	Triggers an update of the custom data held within the platform for a game instance.
`RequestStartGame`	If not using the Fleet service, use to request game start data for a known game instance.

The SDK calls invoke various Game Instance Plugin methods through Game Instance service RPCs. For a list of Game Instance service RPCs, see the GameInstance reference page.

Game Instance service plugins #

The GameInstancePlugin, GameInstanceHostPlugin, and GameInstanceMatchmakingPlugin allow developers to implement custom game instance functionality. In the Game Instance Tasks topic we’ll see how these methods can be used, along with the SDKs that invoke them. You can view all the Game Instance Plugin methods and their properties on the Game Instance Plugin reference page, Game Instance Host Plugin reference page, and the Game Instance Matchmaking Plugin reference page.

Data classes #

For information on the NewGameInstance and GameInstanceUpdate class, see Matchmaking Reference.

Game instances #

GameInstance represents a running game instance, and includes details about the parties, players, and a custom-defined payload of extra game information that will be used to create the game instance.

property/method	description
`id`	Unique `GameInstanceId` of the game instance
`players`	List of players in the game instance
`parties`	List of parties in the game instance
`gameServerZone`	The game server zone the game instance is using
`inMatchmaking`	Boolean value indicating whether the GameInstance is currently enrolled within matchmaking to find more players
`removedPlayers`	List of players previously removed from the game instance
`ext`	The `ExtGameInstance` created during matchmaking in the `NewGameInstance`

Game parties #

GameParty represents a party within a game instance.

property	description
`id`	Unique party ID
`players`	List of players in the game instance
`ext`	The `ExtGameParty` set by the `NewGameInstance` and `GameInstanceUpdate`. Used to store unique data for a party in a game instance.

Game players #

GamePlayer represents a player within a game instance.

property	description
`playerId`	Unique player ID
`socialId`	Unique social ID
`displayName`	Player’s public display name
`partyId`	Party ID for the party the player belongs to
`teamNumber`	Player’s assigned team number
`ext`	The `ExtGamePlayer` created during matchmaking in the `NewGameInstance` or `GameInstanceUpdate`. Used to store unique data for a player in a game instance.

Game start #

GameStart represents data sent to the game server when a game server is allocated for a game instance.

property	description
`gameInstanceId`	Unique game instance ID
`playersAndExts`	List of `GamePlayer` and `ExtGameServerPlayer`
`ext`	The `ExtGameStart` used to store custom data to send to the game server

PartnerClientTokens #

The PartnerClientTokens class contains data for partner client tokens that the game server should use when authenticating to Pragma.

property	description
`gameToken`	Partner client token to use when authenticating to Pragma game backend
`socialToken`	Partner client token to use when authenticating to Pragma social backend

Configuration #

The GameInstanceServiceConfig configuration block provides a place to define default values for the Party service. The following configuration values are available:

config	description
`gameReadyTimeoutMillis`	Time, in milliseconds, to wait for a game server to send a connect players request before releasing the players attached to the game instance
`enableAbsoluteTimeout`	Enables the absolute timeout that will release a game from the service after a specific amount of time has elapsed
`absoluteTimeoutMillis`	Time, in milliseconds, to wait before releasing a game instance. A 0 or negative values means games will never timeout. This value will be ignored if `enableAbsoluteTimeout` is `false`.
`enableKeepAlive`	Enables the keep alive interval, which specifies the interval within which a game server needs to send a keep alive request. If the game server does not send a request within this interval, the the game instance will be released from the service.
`keepAliveIntervalMillis`	Interval, in milliseconds, to wait between keep alive requests. This value will be ignored if `enableKeepAlive` is `false`.
`keepAliveMissesLimit`	Number of keep alive request the game server can miss before releasing the game instance from the service. This value will be ignored if enableKeepAlive is false.
`reconnect`	Determines the player client behavior when recovering from an unexpected disconnect during a game.
`useFleetService`	Enables the usage of server pools.

Extension data #

You can use Extension Data (exts) to pass custom information between different Pragma components for the duration of the game instance. Fields in the various exts can be stored on the engine, or forwarded to plugins, game servers, and player clients through other exts. Using exts to define when and how certain data travels between two components allows you to control each component’s access to certain data. See Game Instance Tasks for sample implementation.

The following table lists the ext payloads relevant to game instance information.

`ext`	description	Example data
`ExtRemovePlayersRequest`	Game instance data sent from the game server to the Game Instance Plugin’s `onRemovePlayers` method when a group of players are removed from a game instance.	game time elapsed at removal time
`ExtRemovePlayer`	Player data passed from the game server to the Game Instance Plugin’s `onRemovePlayers` method via the `playerToRemove` list when a player is removed from a game instance.	player’s progress on current mission
`ExtRemovedFromGame`	Player data populated by the Game Instance Plugin’s `onRemovePlayers` method and sent to the removed player client in the `OnRemovedFromGame` notification when the player is removed from a game instance.	rewards delta
`ExtEndGameRequest`	Game instance data sent from the game server to the Game Instance Plugin’s `onEndGame` method when a game instance ends.	game metrics
`ExtPlayerGameResult`	Player data passed from the game server to the Game Instance Plugin’s `onEndGame` method via the `PlayerGameResult` list when a game instance ends.	completed missions, points gained
`ExtGameEnded`	Player data populated by the Game Instance Plugin’s `onEndGame` method and sent to the player in the `OnGameEnded` notification when a game instance ends. Players previously removed from the game instance can still receive this information.	rewards delta
`ExtAddedToGame`	Game instance data populated by the Game Instance Plugin’s `buildExtAddedToGame` method and sent to the player client in the `OnAddedToGame` notification when the player is added to a game.	team color, current game score
`ExtGameInstance`	Game instance data populated by the Matchmaking Plugin’s `matchParties` method and sent to the Game Instance Service when a new game instance is created. This data will be used when creating the new game instance and persists on the engine for the duration of the game instance.	max game instance duration, game mode, map
`ExtGameParty`	Party data populated and passed to the Game Instance service when the Matchmaking service creates a `NewGameInstance` or `GameInstanceUpdate`. The data persists on the engine for the duration of the party’s time in the game instance and can be updated during subsequent plugin calls.	custom party data
`ExtGamePlayer`	Player data populated and passed to the Game Instance service when the Matchmaking service creates a `NewGameInstance` or `GameInstanceUpdate`. The data persists on the engine for the duration of the player’s time in the game instance and can be updated during subsequent plugin calls.	Steam ID
`ExtGameStart`	Game instance data provided to the game server starting the game. When the game server is allocated for a game instance, it calls `getGameStartDataV1`, which invokes the Game Instance Plugin’s `buildExtGameStart` method. This `ext` could include data sent to the Game Instance service in the `ExtGameParty` payload.	game instance duration
`ExtGameServerPlayer`	Player data provided to the game server by the Game Instance service. When the game server is allocated for a game instance, it calls `getGameStartDataV1`, which invokes the Game Instance Plugin’s `buildExtGameServerPlayer` method for each player in the game instance. This `ext` could include data sent to the Game Instance service in the `ExtGamePlayer` payload.	Steam ID
`ExtPlayerConnectionDetails`	Connection details populated by the game server and used when a game instance is ready for players to join. Players receive the connect details in the `OnHostConnectionDetailsReceived` notification.	game server zone/region
`ExtUpdateGameInstanceRequest`	Payload sent via the game server’s `UpdateGameInstance` SDK method defining what updates to make to a game instance.	advance the current game phase
`ExtHostRequest`	Data to assist in game server allocation. Populated by `GameInstanceHostPlugin.findHostForGameInstance` and used in the fleet service to determine which server pool to assign for the game instance.

Events #

There are several game instance-related events that player clients and game servers can listen to. The following tables contain bindable events relevant to the Game Instance service, along with associated descriptions of when the event is triggered.

Player client events #

The following events are handled by the player client.

Event	Trigger	Data returned
`OnAddedToGame`	The player has been added to a game. Will be followed with `OnHostConnectionDetailsReceived` when the game server is ready.	Pragma ID, `ExtAddedToGame`
`OnHostConnectionDetailsReceived`	The game server starts a game instance and is available for parties to connect	host name, port, game instance ID, `ExtPlayerConnectionDetails`, unique connection token
`OnFailedToAllocateGameInstance`	Game instance allocation fails due to game server issues after matchmaking succeeds	N/A
`OnGameInstanceTerminated`	A game instance is forcibly terminated because it’s no longer communicating with the engine	game instance ID, termination reason (`UNSPECIFIED`, `KEEP_ALIVE_FAILED`, or `ABSOLUTE_TIMEOUT_ELAPSED`)
`OnGameInstanceReconnect`	Connection to the platform is established after disconnecting during an active game instance	host name, port, game instance ID, `ExtPlayerConnectionDetails`, unique connection token
`OnRemovedFromGame`	The game server has removed the player from the game	game instance ID, `ExtRemovedFromGame`
`OnGameEnded`	The game has ended	Game instance ID, `ExtGameEnded`
`OnGameInstanceIdChanged`	The `GAME_INSTANCE_ID` for the game instance changes in the Party	new game instance ID

Game server events #

The following events are handled by the game server.

Event	Trigger	Data returned
`OnGameStart`	Game instance data is retrieved using the provided game instance ID	GameStart
`OnGameStartFailed`	An error occurs when attempting to retrieve game instance data with the provided game instance ID	Pragma error
`OnKeepAliveFailed`	The platform fails to process a keep alive request	game instance ID, Pragma error
`OnGameInstanceTerminated`	The platform decides to terminate an in progress game instance. An example of this firing is when a game instance has failed to heartbeat due to connection issues to the platform. Calling `EndGame` will not cause this event to fire.	game instance ID, termination reason
`OnAddPlayers`	The platform sends new players to the game server to add to the game instance. Upon receiving, the game server should invoke `ConnectMorePlayers` with prepared details for the provided new players for the provided game instance id.	game instance ID, list of Game players
`OnGameInstanceEnteredMatchmaking`	The given active game instance enters matchmaking	game instance ID
`OnGameInstanceLeftMatchmaking`	The given active game instance leaves matchmaking	game instance ID
`OnPlayerDeclinedReconnect`	A player declines to reconnect to the game they were in. Includes the game instance ID and player ID respectively.	game instance ID, player ID

Errors #

GameInstanceService_CapacityRequestFailed
GameInstanceService_UnknownGameInstanceId
GameInstanceService_PlayerNotInGameInstance
GameInstanceService_GameInstanceAlreadyInMatchmaking
GameInstanceService_MissingPlayerConnectionDetails
GameInstanceService_CannotDeclineReconnect
GameInstanceService_FailedToUpdateMatchmakingGameInstancePlayers
GameInstanceService_FailedToLeaveMatchmaking
GameInstanceService_GameInstanceNotInMatchmaking
GameInstanceService_FailedToUpdateMatchmakingGameInstance