Game Instance Backend Reference #

This section provides Game Instance references for plugins, classes, configuration values, and ext data defined in the Pragma Engine backend. For specifics on the using the Pragma SDK for game instance tasks, see Game Instance SDK Reference.

Game Instance service plugins #

The Pragma game instance plugins allow developers to implement custom game instance functionality. Pragma provides the following customizable game instance plugins:

Game Instance Plugin #

The Game Instance Plugin can be used to define custom interactions throughout the lifecycle of a game instance.

method	description
`handleBackendCreateRequest()`	Called when a backend service creates a game instance. By default, players are added to the game instance and a host is allocated.
`handleBackendCreateByMatchmakingRequest()`	Called when a game instance is being created out of matchmaking. The matched players will already be added to the game instance.
`handlePlayerCreateRequest()`	Called when receiving a request from a player client to create a game instance.
`onGameServerAllocationFailed()`	Called when a game server allocation fails for a game instance. This can happen if `GameServerProviderPlugin.startAllocationForGameInstance()` throws an exception, or when a game server doesn’t link to the game instance within the `GameInstanceConfig.gameServerAllocationTimeoutMillis`.
`buildExtGameStart()`	Use to prepare any custom data to provide to the game server when the game server has been allocated to a game
`buildExtGameServerPlayer()`	Use to prepare any custom data to send to the game server when a player is joining a game
`handlePlayerUpdateRequest()`	Called when receiving a player request to update a game instance
`handleBackendUpdateRequest()`	Called when receiving a backend request to update a game instance
`handlePlayerJoinRequest()`	Called when receiving a player client request to join a game instance
`handleBackendAddPlayersRequest()`	Called when receiving a backend request to add one or more players to the game instance
`handleBackendAddPlayersByMatchmakingRequest()`	Use when adding players to a game instance with the deprecated `ExtGameInstance` or `ExtGamePlayer` protos. See the 0.4.0 integration guide for more information.
`handlePlayerLeaveRequest()`	Called when receiving a player request to leave the game instance
`handleBackendRemovePlayersRequest()`	Called when receiving a backend request to remove one or more players from the game instance
`onEndGame()`	Called when players are removed from the game. Use to prepare any custom data to send to the removed players.

Pragma provides a default GameInstancePlugin implementation, DefaultGameInstancePlugin, that returns the default ext payloads.

Game Instance Matchmaking Plugin #

The Game Instance Matchmaking Plugin can be used to define custom interactions for a game instance and its players when entering matchmaking.

method	description
`buildExtMatchmakingKey()`	Use to declare any custom data about the matchmaking queue that the game instance is going to enter
`buildExtMatchmakingGameInstance()`	Use to declare any custom data about the game instance that needs to be sent to the Matchmaking service for use in `matchPartiesWithGame()`
`buildExtMatchmakingGamePlayer()`	Use to declare any custom data about the players in the game that needs to be sent to the Matchmaking service for use in `matchPartiesWithGame()`

Pragma provides a default GameInstanceMatchmakingPlugin implementation, DefaultGameInstanceMatchmakingPlugin, that returns the default ext payloads.

Game Instance classes #

The following interfaces and data classes represent game instances and their players.

GameInstance #

The GameInstance.GameInstance interface 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	description
`id`	Unique `GameInstanceId` of the game instance
`players`	List of players in the game instance
`removedPlayers`	List of players previously removed from the game instance
`gameServerVersion`	Game server version the game instance is running within
`gameServerZone`	Game server zone the game instance is using
`inMatchmaking`	Boolean value indicating whether the GameInstance is currently enrolled within matchmaking to find more players
`gameServerAllocationStatus`	Allocation status of a game server for the game instance (`NOT_STARTED`, `IN_PROGRESS`, `COMPLETE`, or `FAILED`)
`dataStore`	The data store used to store and sync data on the game instance

method	description
`allocateGameServer()`	Starts the process of allocating a game server for this game instance
`addPlayer()`	Add a player to the game instance
`removePlayer()`	Remove a player from the game instance
`end()`	Ends the game instance. Game instances are not ended until this method is called.
`getPlayer()`	Get the `GamePlayer` object for an active player in the game instance (identified by playerId)
`getPlayersByPartyId()`	Get `GamePlayer` objects for all players in the game instance, organized by party ID
`getPlayersByTeamNumber()`	Get `GamePlayer` objects for all players in the game instance, organized by team number

GamePlayer #

The GameInstance.GamePlayer interface represents a player within a game instance.

property	description
`playerId`	Unique player ID
`partyId`	Party ID for the party the player belongs to
`teamNumber`	Player’s assigned team number
`dataStore`	The data store used to store and sync data on the game player

DataStore #

The GameInstance.DataStore interface is used to store custom data about both the game instance and its players.

method	description
`create()`	Creates data in the data store. By default, the data is hidden from players.
`get()`	Gets data from the data store by key
`updateData()`	Updates data in the data store
`updateSync()`	Update the sync values on some data in the data store
`delete()`	Deletes data from the data store by key

PlayerSync #

The GameInstance.PlayerSync class determines accessibility of information on the game instance’s data store. Information in a data store can be synced with one or more players in the game instance, or hidden.

data object/class	description
`Hidden`	Data is not synced with any player in the game instance. Data is hidden from all players in the game instance.
`Player`	Data is synced with a specific player in the game instance. Data is only accessible to this player.
`Party`	Data is synced with all players in a specific party. Data is only accessible to these players.
`Team`	Data is synced with all players on a specific team. Data is only accessible to these players.
`Public`	Data is synced with all players in the game instance. Data is only accessible to all players.

GameInstance API backend class #

The GameInstanceApi.kt backend class is the entrypoint to the game instance service from other backend services or plugins.

method	description
`getIdForPlayer()`	Returns a game instance ID for a specific player, identified by player ID
`getForPlayer()`	Returns a `GameInstanceSummary` for a specific player, identified by player ID
`get()`	Returns a `GameInstanceSummary` for a specific game instance ID
`create()`	Requests to create a new game instance. Triggers `GameInstancePlugin.handleBackendCreateRequest()`
`update()`	Forwards the `ExtBackendUpdateRequest` to the Game Instance Plugin’s `handleBackendUpdateRequest()`
`addPlayers()`	Requests to add one or more players (identified by player ID) to a game instance (identified by game instance ID). Triggers `GameInstancePlugin.handleBackendAddPlayerRequest()`.
`removePlayers()`	Requests to remove one or more players (identified by player ID) from a game instance (identified by game instance ID). Triggers `GameInstancePlugin.handleBackendRemovePlayerRequest()`.

GameInstanceSummary #

The GameInstance.GameInstanceSummary data class represents a subset of game instance data.

property	description
`id`	Unique `GameInstanceId` of the game instance
`players`	List of players in the game instance
`gameServerVersion`	Game server version the game instance is running within
`gameServerZone`	Game server zone the game instance is using
`dataStore`	The data store used to store and sync data on the game instance

GamePlayerSummary #

The GameInstance.GamePlayerSummary data class represents a subset of game player data.

property	description
`playerId`	Unique player ID
`dataStore`	The data store used to store and sync data on the game player

Configuration #

The GameInstanceServiceConfig configuration block provides a place to define default values for game instance and game server operations:

config	description
`gameServerAllocationTimeoutMillis`	Time, in milliseconds, to wait for a game server to send a getGameStartData request before allocation is marked as failed. If using the Pragma Fleet Service, this configuration value should match the Fleet Service `serverMaxStartDurationMillis` config.
`connectPlayersTimeoutMillis`	Time, in milliseconds, to wait for a game server to send a connect players request before releasing the players attached to the game instance
`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.
`assessTimeoutsIntervalSeconds`	Interval, in seconds, between checking for expiration of timeouts on the service
`removePlayersOnDisconnect`	Determines whether the player is removed from their game instance upon disconnect. Defaults to `false`.
`enableExtraCreateGameInstanceTimers`	Enables additional timing metrics to diagnose performance issues within the `CreateGameInstanceV1` endpoint
`enableStaleGameInstanceExpiration`	Enables the absolute timeout that will release a game from the service after a specific amount of time has elapsed. Defaults to `true`.
`staleGameInstanceExpirationMinutes`	Time, in minutes, to wait before releasing a game instance. A 0 or negative values means games will never timeout. This value will be ignored if `enableStaleGameInstanceExpiration` is `false`.

See the Game Server section in the documentation for more information on game server operations.

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
`ExtData`	Game instance and player data. Populated in any method of the GameInstancePlugin and used in the backend, player clients, and game servers.	player’s team color, game mode
`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.	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.	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
`ExtBackendCreateRequest`	Data about a new game instance that is forwarded from a backend request to create a game instance.	game mode
`ExtPlayerCreateRequest`	Data about a new game instance that is forwarded from the player client’s request to create a game instance.	game mode
`ExtAllocateGameServer`	Data to assist in game server allocation. Populated by `GameServerProviderPlugin.startAllocationForGameInstance()`	game mode (3v3, 1v1, etc.) or game version (beta, trial, etc.)
`ExtPlayerUpdateRequest`	Payload populated by player clients defining what updates to make to a game instance	connection details in peer-to-peer setups
`ExtBackendUpdateRequest`	Payload sent via the game server’s `UpdateGameInstance()` SDK method defining what updates to make to a game instance	advance the current game phase
`ExtBackendAddPlayersRequest`	Payload containing data to use when adding a player to an existing game instance via backend services or processes.
`ExtBackendAddPlayer`	Payload for a specific player being added to a game instance via the `handleBackendAddPlayersRequest()`.	character selection
`ExtPlayerJoinGameInstanceRequest`	Data about the player joining the game instance via the Game Instance API.	character selection
`ExtPlayerLeaveRequest`	Data about the player requesting to leave the game instance.	reason for leaving
`ExtBackendRemovePlayersRequest`	Payload containing data to use when removing a player from a game instance via backend services or processes.
`ExtBackendRemovePlayer`	Payload for a specific player being removed from a game instance via the `handleBackendRemovePlayersRequest()`.
`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
`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

Errors #

GameInstanceService_GameServerAlreadyAllocated
GameInstanceService_CapacityRequestFailed
GameInstanceService_UnknownGameInstanceId
GameInstanceService_PlayerNotInGameInstance
GameInstanceService_GameInstanceAlreadyInMatchmaking
GameInstanceService_MissingPlayerConnectionDetails
GameInstanceService_FailedToUpdateMatchmakingGameInstancePlayers
GameInstanceService_FailedToLeaveMatchmaking
GameInstanceService_GameInstanceNotInMatchmaking
GameInstanceService_FailedToUpdateMatchmakingGameInstance
GameInstanceService_DataStore_DataAlreadyExists
GameInstanceService_DataStore_DataNotFound
GameInstanceService_LeaveFailed
GameInstanceService_PlayerJoinFailed