Game Instance SDK Reference #

This section provides references for Game Instance methods, classes, and events in the Pragma SDK for Unreal and Unity. For information on Pragma Engine backend classes and plugins, see Game Instance Backend Reference.

The Pragma SDK provides methods that developers can use to facilitate game instance processes. The SDK includes methods for Game Instance service implementation through the GameInstanceApi and the MatchApi, depending on whether the call comes from the player client or game server, respectively. The tables below contains a list of all the methods relevant to the Game Instance service.

Game Instance API (player client) SDK methods #

method	description
`Initialize()`	Initializes the client’s party API state and synchronizes its party state with the platform’s party state. Must be called prior to using other functionality on the API.
`ForceSync()`	Forcibly synchronizes the player client’s game instance data with the game instance information in the Pragma Engine backend
`Update()`	Requests game instance data updates
`Create()`	Creates a new game instance
`Join()`	Request to join a specific game instance
`Leave()`	Requests that the current player be removed from their game instance
`GetGameInstanceCache()`	Gets the player’s game instance cache

Match API (game server) SDK methods #

method	description
`RequestStartGame()`	Requests the game start data for a game instance
`ConnectPlayers()`	Connects the initial players to the game server
`ConnectMorePlayers()`	Connects more players to the game server
`VerifyPlayer()`	Uses player connection token to verify that connecting players are not misrepresenting their Pragma identity
`UpdateGameInstance()`	Requests game instance data updates
`RemovePlayers()`	Removes players from a game instance and processes player game results. Does not end the game instance.
`EndGame()`	Request that a game instance end. Does note automatically end the game instance.
`EnterMatchmaking()`	Enters a game instance into matchmaking to accept additional players
`LeaveMatchmaking()`	Removes a game instance from matchmaking
`SetRichPresence()`	Sets a player’s rich presence based on server-side options (such as “in party”)

The SDK calls invoke various Game Instance Plugin methods through Game Instance service RPCs.

Unreal classes #

The SDK for Unreal makes use of Pragma-defined Unreal classes. The following sections list methods available on each class:

FPragmaGameInstance #

method	returns
`GetId()`	game instance ID
`GetDataStore()`	map of data store key and `FPragma_GameInstance_ExtData`
`GetHostConnectionDetails()`	FPragmaHostConnectionDetail
`GetPlayers()`	List of FPragmaGamePlayers
`GetPlayer(const FString& PlayerId)`	FPragmaGamePlayer
`GetVersion()`	game instance version

FPragmaGameInstanceCache #

method	returns
`IsInGame()`	true/false
`GetGameInstance`	FPragmaGameInstance

FPragmaGamePlayer #

method	returns
`GetPlayerId()`	player ID
`GetDataStore()`	map of data store key and `FPragma_GameInstance_ExtData`

FPragmaHostConnectionDetails #

method	returns
`GetHostName()`	hostname
`GetPort()`	port number
`GetConnectionToken()`	connection token (string)
`GetExt()`	`FPragma_GameInstance_ExtPlayerConnectionDetails`

FPragma_GameInstance_GameStart #

property	definition
`GameInstanceId`	game instance ID
`Players`	List of FPragma_GameInstance_GameServerPlayer
`Ext`	`FPragma_GameInstance_ExtGameStart`
`IsInMatchmaking`	Whether or not the game instance is in matchmaking

FPragma_GameInstance_GameServerPlayer #

property	definition
`PlayerId`	player’s ID
`PartyId`	party ID
`TeamNumber`	player’s team number
`Ext`	FPragma_GameInstance_ExtGameServerPlayer

Events #

There are several game instance-related events that player clients and game servers can listen to. The following tables contain bindable events relevant to the Game Instance service, along with associated descriptions of when the event is triggered.

Player client events #

The following events are handled by the player client.

Event	Trigger	Data returned
`OnAddedToGameInstance`	The player has been added to a game instance. Will be followed with `OnHostConnectionDetailsReceived` when the game server is ready.	`GameInstance`
`OnGameInstanceUpdated`	A game instance is updated due to player client request	`GameInstance`
`OnFailedToAllocateGameInstance`	Game instance allocation fails due to game server issues after matchmaking succeeds	N/A
`OnHostConnectionDetailsReceived`	The game server starts a game instance and is available for parties to connect	`GameInstance`
`OnRemovedFromGameInstance`	The game server has removed the player from the game	game instance ID, `ExtRemovedFromGame`
`OnGameInstanceEnded`	The game has ended	Game instance ID, `ExtGameEnded`
`OnGameInstanceTerminated`	A game instance is forcibly terminated because it’s no longer communicating with the engine	game instance ID, termination reason (`UNSPECIFIED`, `KEEP_ALIVE_FAILED`, or `ABSOLUTE_TIMEOUT_ELAPSED`)

Game server events #

The following events are handled by the game server.

Event	Trigger	Data returned
`OnGameStart`	A game instance is started. The game server receives game instance data on this event.	FPragma_GameInstance_GameStart
`OnGameStartFailed`	An error occurs when attempting to retrieve game instance data with the provided game instance ID	Pragma error
`OnKeepAliveFailed`	The platform fails to process a keep alive request	game instance ID, Pragma error
`OnPlayersAdded`	The platform adds players to a game game instance. Upon receiving, the game server should invoke `ConnectMorePlayers` with prepared details for the provided new players for the provided game instance ID.	game instance ID, list of FPragma_GameInstance_GameServerPlayer
`OnPlayersRemoved`	Players are removed from the game instance by the backed.	game instance ID, list of FPragma_GameInstance_GameServerPlayer
`OnGameInstanceEnteredMatchmaking`	The given active game instance enters matchmaking	game instance ID
`OnGameInstanceLeftMatchmaking`	The given active game instance leaves matchmaking	game instance ID