Game Instances #

The Game Instance service is responsible for tracking in-progress game, sending data to game server, executing all end-of-game processing, and helping disconnected players reconnect to ongoing games.

Using the Game Instance API, Match API, Game Instance plugins, and extension data, developers can create custom game instance configurations and workflows.

Creating a game instance #

There are four way to create a game instance:

Player creation: players can directly create a game instance, bypassing the matchmaking service. The new game instance starts with only the creating player.
Matchmaking: the Matchmaking service can create a game instance when it finds a match. By default, all players from that match are added to the game instance.
Backend creation: backend methods and custom services can directly create game instances without using the Matchmaking service.
Game server creation: game servers can create and link to a game instance.

Joining a game instance #

There are four ways a player can join a game instance:

Player creation: a player who creates a game instance is automatically added to the game.
Matchmaking: when a match is made, all party players are added to the new or updated game instance.
Direct join: players can bypass matchmaking and directly join a specific game instance.
Server creation: when a game server creates and links to a game instance, it can specify which players to add to the game.

Players can belong to multiple game instances at a time.

Custom data #

You can define and update game instance data using the DataStore. Each game instance includes one DataStore for game-wide data such as game mode or map, and one DataStore for each game player. You can customize how this data is shared with players.

Teams #

Pragma supports assigning teams for game play. In team-based matchmaking flows, you can set the player’s team number in matchmaking and the value will automatically be forwarded to the game instance and game server. If a player joins a game instance directly, you can handle team assignment in backend plugins.

By default, all players enter a game on team 0.

Team specifics, such as color, can be set on the game instance DataStore.

Allocating and linking a game server #

For players to connect to a game server to play the game, you need to allocate a server and link the server to the game instance.

When a game instance is allocated a server, the server can establish communication with the Pragma backend and link to the game instance. The linking process allows the server to receive information about the game it will host, along with the players that will connect. Once linked, Pragma Engine distributes server details to the players so they can connect to the game server.

End of game processing #

When players finish playing a game, the hosting server can tell the Pragma backend to end the game instance. At this point, players are removed from the game instance. Alternatively, the game server can unlink itself from the game instance and leave the players in the game instance. This is useful if you want to spin down an unused server but keep players together.

After a game instance ends, you can handle any game end processing tasks, such as issuing rewards. 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.