Game Instance Service Overview #

The Game Instance service is responsible for tracking in-progress game instances, receiving events from the game server, executing all end of game processing, and helping disconnected players reconnect to ongoing game instances.

A player can only be in one game instance at a time.

Custom game and player data #

You can store custom data about a game instance and its players on the ExtData proto. Information on this proto is managed using the Game Instance DataStore interface.

Most game instance data should remain on the game server and be sent directly to players. However, you may want to use the data store when:

• Players need to communicate with each other before a game server is allocated
• The game server needs to send information to the Pragma backend that impacts finding more players for the game instance
• You need to select which player will host a peer-to-peer game
• Players are required to pass a ready check before a game server is allocated
• Players have to select a unique character from a pool of characters before a game server is allocated

Game instances and games players have an associated DataStore property (GameInstance.dataStore and GamePlayer.dataStore, respectively) that can be used to create and update ExtData related to the game instance or game player.

When a player leaves or is removed from a game instance, their GamePlayer object is removed along with the data in their data store.

See Build custom data in the Game Instance Tasks page for instructions about customizing a DataStore.

Data synching #

Each item in the DataStore can be synced to specific players, players in a party, players on a team, or made public. Sync options determine what players (if any) are notified of data store changes.

To configure data sync options, specify one of the following when creating a DataStore:

• Hidden: Data is not synced with any player/party/team and is accessible only from the GameInstancePlugin
• Player: Data is sent to a specific player client in the game instance
• Party: Data is sent to player clients for all players in a specific party in the game instance
• Team: Data is sent to player clients for all players on a specific team in the game instance
• Public: Data is sent to all players clients in 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. See Assign Teams to learn how to assign a player or party to a team once in a game instance.

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.

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.