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.

methoddescription
handleBackendCreateByMatchmakingRequestCalled when a game instance is being created out of matchmaking. The matched players will already be added to the game instance.
buildExtGameStartUse to prepare any custom data to provide to the game server when the game server has been allocated to a game
buildExtGameServerPlayerUse to prepare any custom data to send to the game server when a player is joining a game
handlePlayerUpdateRequestCalled when receiving a player request to update a game instance
handleBackendUpdateRequestCalled when receiving a backend request to update a game instance
onRemovePlayersCalled when players are removed from the game. Use to prepare any custom data to send to the removed players.
onEndGameCalled 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.

methoddescription
buildExtMatchmakingKeyUse to declare any custom data about the matchmaking queue that the game instance is going to enter
buildExtMatchmakingGameInstanceUse to declare any custom data about the game instance that needs to be sent to the Matchmaking service for use in matchPartiesWithGame()
buildExtMatchmakingGamePartyUse to declare any custom data about the party in the game that needs to be sent to the Matchmaking service for use in matchPartiesWithGame()
buildExtMatchmakingGamePlayerUse 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 interfaces #

There are three main interfaces within the Game Instance service: GameInstance, GameParty, and GamePlayer. These interfaces represent game instances and their parties and players.

GameInstance #

The 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.

propertydescription
idUnique GameInstanceId of the game instance
playersList of players in the game instance
removedPlayersList of players previously removed from the game instance
gameServerVersionGame server version the game instance is running within
gameServerZoneGame server zone the game instance is using
inMatchmakingBoolean value indicating whether the GameInstance is currently enrolled within matchmaking to find more players
gameServerAllocationStatusAllocation status of a game server for the game instance (NOT_STARTED, IN_PROGRESS, COMPLETE, or FAILED)
extThe ExtGameInstance created during matchmaking in the NewGameInstance
dataStoreThe data store used to store and sync data on the game instance
methoddescription
allocateGameServer()Starts the process of allocating a game server for this game instance
addPlayerAdd a player to the game instance
removePlayerRemove a player from the game instance
end()Ends the game instance. Game instances are not ended until this method is called.
getPlayerGet the GamePlayer object for an active player in the game instance (identified by playerId)
getPlayersByPartyIdGet GamePlayer objects for all players in the game instance, mapped by party ID
getPlayersByTeamNumberGet GamePlayer objects for all players in the game instance, mapped by team number

GameParty #

The GameParty interface represents a party within a game instance.

propertydescription
idUnique party ID
playersList of players in the game instance
extThe ExtGameParty set by the NewGameInstance and GameInstanceUpdate. Used to store unique data for a party in a game instance.

GamePlayer #

The GamePlayer interface represents a player within a game instance.

propertydescription
playerIdUnique player ID
partyIdParty ID for the party the player belongs to
teamNumberPlayer’s assigned team number
extThe ExtGamePlayer created during matchmaking in the NewGameInstance or GameInstanceUpdate. Used to store unique data for a player in a game instance.
dataStoreThe data store used to store and sync data on the game player

DataStore #

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

methoddescription
createCreates data in the data store. By default, the data is hidden from players.
getGets data from the data store by key
updateDataUpdates data in the data store
updateSyncUpdate the sync values on some data in the data store
deleteDeletes data from the data store by key

PlayerSync #

The 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/classdescription
HiddenData is not synced with any player in the game instance. Data is hidden from all players in the game instance.
PlayerData is synced with a specific player in the game instance. Data is only accessible to this player.
PartyData is synced with all players in a specific party. Data is only accessible to these players.
TeamData is synced with all players on a specific team. Data is only accessible to these players.
PublicData 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.

methoddescription
update()Forwards the ExtBackendUpdateRequest to the Game Instance Plugin’s handleBackendUpdateRequest()

Configuration #

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

configdescription
gameReadyTimeoutMillisTime, in milliseconds, to wait for a game server to send a connect players request before releasing the players attached to the game instance
enableKeepAliveEnables 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.
keepAliveIntervalMillisInterval, in milliseconds, to wait between keep alive requests. This value will be ignored if enableKeepAlive is false.
keepAliveMissesLimitNumber 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.
reconnectDetermines the player client behavior when recovering from an unexpected disconnect during a game
enableExtraCreateGameInstanceTimersEnables additional timing metrics to diagnose performance issues within the CreateGameInstanceV1 endpoint
enableStaleGameInstanceExpirationWhether to enable the game instance expiration feature. Defaults to true.
staleGameInstanceExpirationMinutesTime, 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.

extdescriptionExample data
ExtAllocateGameServerData to assist in game server allocation. Populated by GameServerProviderPlugin.startAllocationForGameInstance()game mode (3v3, 1v1, etc.) or game version (beta, trial, etc.)
ExtRemovePlayersRequestGame 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
ExtRemovePlayerPlayer 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
ExtRemovedFromGamePlayer 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 instancerewards delta
ExtEndGameRequestGame instance data sent from the game server to the Game Instance Plugin’s onEndGame() method when a game instance endsgame metrics
ExtPlayerGameResultPlayer data passed from the game server to the Game Instance Plugin’s onEndGame() method via the PlayerGameResult list when a game instance endscompleted missions, points gained
ExtGameEndedPlayer 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
ExtDataGame 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
ExtGameInstanceGame 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
ExtGamePartyParty 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
ExtGamePlayerPlayer 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
ExtGameStartGame 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
ExtGameServerPlayerPlayer 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
ExtPlayerConnectionDetailsConnection 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
ExtBackendUpdateRequestPayload sent via the game server’s UpdateGameInstance() SDK method defining what updates to make to a game instanceadvance the current game phase
ExtPlayerUpdateRequestPayload populated by player clients defining what updates to make to a game instanceconnection details in peer-to-peer setups

Errors #

  • GameInstanceService_GameServerAlreadyAllocated
  • GameInstanceService_CapacityRequestFailed
  • GameInstanceService_UnknownGameInstanceId
  • GameInstanceService_PlayerNotInGameInstance
  • GameInstanceService_GameInstanceAlreadyInMatchmaking
  • GameInstanceService_MissingPlayerConnectionDetails
  • GameInstanceService_CannotDeclineReconnect
  • GameInstanceService_FailedToUpdateMatchmakingGameInstancePlayers
  • GameInstanceService_FailedToLeaveMatchmaking
  • GameInstanceService_GameInstanceNotInMatchmaking
  • GameInstanceService_FailedToUpdateMatchmakingGameInstance
  • GameInstanceService_DataStore_DataAlreadyExists
  • GameInstanceService_DataStore_DataNotFound