Game Instance Components #
This section provides a baseline understanding of key components used in the Game Instance service. To learn how these components work together, see Game Instance Tasks.
Game Instance SDK #
The Pragma SDK provides methods that developers can use to facilitate game instance processes, such as connecting more players or ending the game. In the Game Instance Tasks topic we’ll see how these methods can be used. You can view a list of the Game Instance service SDK methods in the Game Instance SDK and Events topic.
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.
Game Instances #
GameInstance.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 #
GameInstance.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 #
GameInstance.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 Instance Service 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 a game, 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 a game, 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. |
Teams #
Pragma Engine allows for creating teams of players or parties within a game instance. This allows for a scenario where a developer wishes to split the players or parties into opposing teams when necessary for MMR balancing.
End of Game Processing #
When game instances end, the Game Instance service processes individual players, as well as the complete game instance end flow. This includes making parallel requests to all services that need to process game instance results, aggregating the respective results, and sending the results notification to players. See End a Game Instance for more details about how Pragma Engine handles game ends.