Game Instance SDK and Events #

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.

GameLoopApi (player client) SDK methods #

Calldescription
DeclineReconnectSignals that the player is declining to reconnect to the game instance after disconnecting.
GetHostConnectionDetailsProvides player with connection information for the game instance. This is useful for a player if they disconnect and later decide to reconnect.

MatchApi (game server) SDK methods #

Calldescription
ConnectMorePlayersConfirms the connection details and game instance ext data for the found players.
ConnectPlayersSignals a game instance is ready to start.
EndGameSignals a game instance has completed.
RemovePlayersProcesses player game results for a subset of players within a game instance. Does not end the game instance.
EnterMatchmakingAllows an active game instance to enter matchmaking to accept additional parties.
LeaveMatchmakingRemoves an active game instance from matchmaking.
VerifyPlayerUses player connection token to verify that connecting players are not misrepresenting their Pragma identity.
GetGameStartDataV1Retrieves the game start data.
KeepAliveTaskEnsures a game instance does not get ended by the Game Instance service.
UpdateGameInstanceTriggers an update of the custom data held within the platform for a game instance.
UpdateMaxGameInstanceAllows a game server to reconfigure its max game instance count after report capacity polling has started
RequestStartGameIf not using the Fleet service, use to request game start data for a known game instance.

The SDK calls invoke various Game Instance Plugin methods through Game Instance service RPCs. For a list of Game Instance service RPCs, see the GameInstance reference page.

Game Instance Service Bindable 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.

UnrealUnityTrigger
FAddedToGameEvent OnAddedToGame;public event Action<PragmaId> OnAddedToGame;The player has been added to a game. Will be followed with OnHostConnectionDetailsReceived when the game server is ready.
FHostConnectionDetailsEvent OnHostConnectionDetailsReceived;public event Action<HostConnectionDetails> OnHostConnectionDetailsReceived;The game server starts a game instance and is available for parties to connect.
FFailedToAllocateGameInstance OnFailedToAllocateGameInstance;public event Action OnFailedToAllocateGameInstance;Game instance allocation fails due to game server issues after matchmaking succeeds.
FGameInstanceTerminationEvent OnGameInstanceTerminated;public event Action<PragmaId, GameInstanceTerminationReason> OnGameInstanceTerminated;A game instance is forcibly terminated because it’s no longer communicating with the engine.
FGameInstanceReconnectEvent OnGameInstanceReconnect;public event Action<GameInstanceReconnectV1Notification> OnGameInstanceReconnect;Connection to the platform is established after disconnecting during an active game instance.
FRemovedFromGameEvent OnRemovedFromGame;public event Action<ExtRemovedFromGame> OnRemovedFromGame;The game server has removed the player from the game.
FGameEndedEvent OnGameEnded;public event Action<PragmaId, GameInstanceTerminationReason> OnGameEnded;The game has ended.
FMatchIdEvent OnGameInstanceIdChanged;public event Action<PragmaId> OnGameInstanceIdChanged;The GAME_INSTANCE_ID for the game instance changes in the Party.

Game Server Events #

The following events are handled by the game server.

UnrealUnityTrigger
FGameStartEvent OnGameStart;public event Action<GameStart> OnGameStart;A game instance is started. The game server receives game instance data on this event.
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.
FKeepAliveFailedEvent OnKeepAliveFailed;public event Action<PragmaId, PragmaError> OnKeepAliveFailed;The platform fails to process a keep alive request.
FGameInstanceTerminationEvent OnGameInstanceTermination;public event Action<GameInstanceTerminationV1Notification> OnGameInstanceTermination;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 OnAddPlayers;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 ConnectMorePlayers with prepared details for the provided new players for the provided game instance id.
FEnteredMatchmakingEvent OnGameInstanceEnteredMatchmaking;public event Action<PragmaId> OnGameInstanceEnteredMatchmaking;The given active game instance enters matchmaking.
FLeftMatchmakingEvent OnGameInstanceLeftMatchmaking;public event Action<PragmaId> OnGameInstanceLeftMatchmaking;The given active game instance leaves matchmaking.
FPlayerDeclinedReconnectEvent OnPlayerDeclinedReconnect;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.
FEnteredMatchmakingEvent OnGameInstanceEnteredMatchmaking;public event Action<PragmaId> OnGameInstanceEnteredMatchmaking;The given active game instance enters matchmaking.
FLeftMatchmakingEvent OnGameInstanceLeftMatchmaking;public event Action<PragmaId> OnGameInstanceLeftMatchmaking;The given active game instance leaves matchmaking.