Game Instance Methods, Calls, and Events #

Game Instance Plugin Methods #

method	description
`buildExtGameStart`	Called to prepare any custom data (`ExtGameStart`) to send from the Game Instance service to the game server upon receiving new players.
`buildExtGameServerPlayer`	Called before notifying a game server that players are about to join the game instance. Use to customize the ext data (`ExtGameServerPlayer`) per player to send to the game server.
`buildExtAddedToGame`	Called immediately when a new player is added to a game. Use to customize the ext data (`ExtAddedToGame`) per player to send information about the incoming game to players.
`onRemovePlayers`	Called when players are removed from a game instance.
`onEndGame`	Called when the game is ending to prepare any custom data to send to players from the game.

Game Instance Matchmaking Plugin Methods #

method	description
`buildExtMatchmakingGameInstance`	Called when a game instance is about to be sent to matchmaking. Use to declare any custom data about the game instance (`ExtMatchmakingGameInstance`) that needs to be sent to the Matchmaking service.
`buildExtMatchmakingKey`	Used to produce the correct key (`ExtMatchmakingKey`) for your game instance when it enters matchmaking.
`buildExtMatchmakingGameParty`	Called when a game instance is about to be sent to matchmaking. Use to declare any custom data about the game party that needs to be sent to the Matchmaking Service.
`buildExtMatchmakingGamePlayer`	Called when a game instance is about to be sent to matchmaking. Use to declare any custom data about the game player that needs to be sent to the MatchmakingService.

Game Instance Service SDK Methods #

The SDK includes methods for Game Instance service implementation through the GameLoopApi and MatchApi classes, depending on whether the call comes from the game client or game server, respectively. The tables below contains a list of all the GameLoopApi and MatchApi methods relevant to the Game Instance service.

Call	class	description
`ConnectMorePlayers`	`MatchApi`	Confirms the connection details and game instance ext data for the found players.
`ConnectPlayers`	`MatchApi`	Signals a game instance is ready to start.
`EndGame`	`MatchApi`	Signals a game instance has completed.
`RemovePlayers`	`MatchApi`	Processes player game results for a subset of players within a game instance. Does not end the game instance.
`EnterMatchmaking`	`MatchApi`	Allows an active game instance to enter matchmaking to accept additional parties.
`LeaveMatchmaking`	`MatchApi`	Removes an active game instance from matchmaking.
`VerifyPlayer`	`MatchApi`	Uses player connection token to verify that connecting players are not misrepresenting their Pragma identity.
`KeepAliveTask`	`MatchApi`	Ensures a game instance does not get ended by the Game Instance Service.
`DeclineReconnect`	`GameLoopApi`	Signals that the player is declining to reconnect to the game instance after disconnecting.
`MatchConnectionDetails`	`GameLoopApi`	Provides player with connection information for the game instance. This is useful for a player if they disconnect and later decide to reconnect.

Game Instance Service RPCs #

The list below includes the Game Instance service RPCs.

createGameInstanceV1
getGameStartDataV1
connectPlayersV1
connectMorePlayersV1
matchKeepAliveV1
gameInstanceAllocationFailureV1
enterMatchmakingV1
foundMorePlayersV1
leaveMatchmakingV1
removedGameInstanceFromMatchmakingV1
removePlayersV1
endGameV1
declineReconnectV1
matchConnectionDetailsV1
verifyPlayerPartnerV1

Game Instance Service Bindable Events #

Besides the typical RPC calls, there are several 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.

Unreal	Unity	Trigger
`FMatchIdEvent OnGameInstanceIdChanged;`	`public event Action<PragmaId> OnGameInstanceIdChanged;`	The `GAME_INSTANCE_ID` for the game instance changes in the Party.
`FFailedToFindMatch OnFailedToFindMatch;`	`public event Action OnFailedToFindMatch;`	Game instance allocation fails due to game server issues after matchmaking succeeds.
`FMatchReadyEvent OnMatchReady;`	`public event Action<MatchReadyV1Notification> OnMatchReady;`	The game server starts a game instance and is available for parties to connect.
`FMatchReconnectEvent OnMatchReconnect;`	`public event Action<MatchReconnectV1Notification> OnMatchReconnect;`	Connection to the platform is established after disconnecting during an active game instance.
`FMatchTerminationEvent OnMatchTermination;`	`public event Action<MatchTerminationV1Notification> OnMatchTermination;`	A game instance is forcibly terminated because it’s no longer communicating with the engine.
`FMatchProcessedEvent OnMatchProcessed;`	`public event Action<MatchProcessedV3Notification> OnMatchProcessed;`	A match result is processed.
`FRemovedFromGameEvent OnRemovedFromGame;`	`public event Action<ExtRemovedFromGame> OnRemovedFromGame;`	The game server has removed the player from the game.

Game server events #

The following events are handled by the game server.

Unreal	Unity	Trigger
`FGameStartEvent OnGameStart;`	`public event Action<GameStart> OnGameStart;`	A game instance is started.
`FOnGameStartFailedEvent OnGameStartFailed;`	`public event Action<Error> OnGameStartFailed;`	An error occurs while attempting to start a game instance. The game server will not continue reporting capacity or receiving new game instances until `StartReportCapacityPolling` is called again.
`FMatchTerminationEvent OnMatchTerminationEvent;`	`public event Action<PragmaId> OnMatchTerminationEvent;`	The platform decides to terminate an in progress game instance. An example of this firing is when a game instance has failed to heartbeat due to connection issues to the platform. Calling `EndGame` will not cause this event to fire.
`FAddPlayersEvent OnAddPlayersEvent;`	`public event Action<PragmaId, List<GameServerPlayer>> OnAddPlayers;`	The platform sends new players to the game server to add to the game instance. Upon receiving, the game server should invoke `ConnectNewPlayersV1` with prepared details for the provided new players for the provided game instance id.
`FPlayerDeclinedReconnectEvent OnPlayerDeclinedReconnectEvent;`	`public event Action<PragmaId, PragmaId> OnPlayerDeclinedReconnect;`	A player declines to reconnect to the game they were in. Includes the game instance ID and player ID respectively.