1. Epic GamesDeveloper
  3. UGameInstance

UGameInstance

GameInstance: high-level manager object for an instance of the running game.

API > API/Runtime > API/Runtime/Engine

GameInstance: high-level manager object for an instance of the running game. Spawned at game creation and not destroyed until game instance is shut down. Running as a standalone game, there will be one of these. Running in PIE (play-in-editor) will generate one of these per PIE instance.

   
Name UGameInstance
Type class
Header File /Engine/Source/Runtime/Engine/Classes/Engine/GameInstance.h
Include Path #include "Engine/GameInstance.h"

Syntax

UCLASS (Config=Game, Transient, BlueprintType, Blueprintable, MinimalAPI)  
class UGameInstance :  
    public UObject ,  
    public FExec

Inheritance Hierarchy

Derived Classes

Constructors

Name Remarks Include Path Unreal Specifiers

UGameInstance ( const FObjectInitializer& ObjectInitializer
)

   Engine/GameInstance.h  

Variables

Public

Name Type Remarks Include Path Unreal Specifiers
bReportedPIEStartupTime bool   Engine/GameInstance.h  
LatentActionManager FLatentActionManager *   Engine/GameInstance.h  
OnInputDeviceConnectionChange FOnUserInputDeviceConnectionChange Callback for when an input device connection state has changed (a new gamepad was connected or disconnected) Engine/GameInstance.h
  • BlueprintAssignable
  • DisplayName=OnInputDeviceConnectionChange
OnLocalPlayerAddedEvent FOnLocalPlayerEvent Local player access Engine/GameInstance.h  
OnLocalPlayerRemovedEvent FOnLocalPlayerEvent   Engine/GameInstance.h  
OnUserInputDevicePairingChange FOnUserInputDevicePairingChange Callback when an input device has changed pairings (the owning platform user has changed for that device) Engine/GameInstance.h
  • BlueprintAssignable
  • DisplayName=OnUserInputDevicePairingChange
PIEMapName FString   Engine/GameInstance.h  
PIEStartTime double   Engine/GameInstance.h  
TimerManager FTimerManager *   Engine/GameInstance.h  

Protected

Name Type Remarks Include Path Unreal Specifiers
SubsystemCollection FObjectSubsystemCollection< UGameInstanceSubsystem >   Engine/GameInstance.h  

Functions

Public

Name Remarks Include Path Unreal Specifiers

virtual int32 AddLocalPlayer ( ULocalPlayer* NewPlayer,
FPlatformUserId UserId
)

 Adds a LocalPlayer to the local and global list of Players. Engine/GameInstance.h  

virtual void AddUserToReplay ( const FString& UserString
)

 Adds a join-in-progress user to the set of users associated with the currently recording replay (if any) Engine/GameInstance.h  

void CleanupGameViewport()

   Engine/GameInstance.h  

virtual bool ClientTravelToSession ( int32 ControllerId,
FName InSessionName
)

 Helper function for traveling to a session that has already been joined via the online platform Grabs the URL from the session info and travels Engine/GameInstance.h  

virtual AGameModeBase * CreateGameModeForURL ( FURL InURL,
UWorld* InWorld
)

 Call to create the game mode for a given map URL Engine/GameInstance.h  

virtual ULocalPlayer * CreateInitialPlayer ( FString& OutError
)

   Engine/GameInstance.h  

ULocalPlayer * CreateLocalPlayer ( FPlatformUserId UserId,
FString& OutError,
bool bSpawnPlayerController
)

 Adds a new player. Engine/GameInstance.h  

ULocalPlayer * CreateLocalPlayer ( int32 ControllerId,
FString& OutError,
bool bSpawnPlayerController
)

 Adds a new player. Engine/GameInstance.h  

virtual void DebugCreatePlayer ( int32 ControllerId
)

 Debug console command to create a player. Engine/GameInstance.h
  • Exec

virtual void DebugRemovePlayer ( int32 ControllerId
)

 Debug console command to remove the player with a given controller ID. Engine/GameInstance.h
  • Exec

virtual bool DelayCompletionOfPendingNetGameTravel()

 Return true to delay player controller spawn (sending NMT_Join) Engine/GameInstance.h  

virtual bool DelayPendingNetGameTravel()

 Return true to delay an otherwise ready-to-join PendingNetGame performing LoadMap() and finishing up useful to wait for content downloads, etc Engine/GameInstance.h  

virtual bool EnableListenServer ( bool bEnable,
int32 PortOverride
)

 Turns on/off listen server capability for a game instance By default this will set up the persistent URL state so it persists across server travels and spawn the appropriate network listener Engine/GameInstance.h  

ULocalPlayer * FindLocalPlayerFromControllerId ( const int32 ControllerId
) const

 Returns the local player assigned to a physical Controller Id, or null if not found Engine/GameInstance.h  

ULocalPlayer * FindLocalPlayerFromDeviceId ( const FInputDeviceId DeviceID
) const

 Returns the local player who the given input device is assigned to. Null if not found Engine/GameInstance.h  

ULocalPlayer * FindLocalPlayerFromPlatformUserId ( const FPlatformUserId UserId
) const

 Returns the local player assigned to this platform user id, or null if not found Engine/GameInstance.h  
  Engine/GameInstance.h  
  Engine/GameInstance.h  

ULocalPlayer * FindLocalPlayerFromUniqueNetId ( FUniqueNetIdPtr UniqueNetId
) const

 Returns the local player that has been assigned the specific unique net id Engine/GameInstance.h  

void ForEachSubsystem ( TFunctionRef< void(TSubsystemClass*)> Operation
) const

 Performs an operation on all all Subsystem of specified type, this is only necessary for interfaces that can have multiple implementations instanced at a time. Engine/GameInstance.h  

virtual EReplicationSystem GetDesiredReplicationSystem ( FName InNetDriverDefinition
) const

 Allows a GameInstance to override the default configured replication system for it's specific conditions. Engine/GameInstance.h  

UEngine * GetEngine()

   Engine/GameInstance.h  

ULocalPlayer * GetFirstGamePlayer()

 Returns the first local player, will not be null during normal gameplay Engine/GameInstance.h  
Returns the player controller assigned to the first local player. Engine/GameInstance.h  

UGameViewportClient * GetGameViewportClient()

   Engine/GameInstance.h  

FLatentActionManager & GetLatentActionManager()

   Engine/GameInstance.h  

ULocalPlayer * GetLocalPlayerByIndex ( const int32 Index
) const

 Returns the local player at a certain index, or null if not found Engine/GameInstance.h  

TArray< ULocalPlayer * >::TConstIterator GetLocalPlayerIterator()

 Returns const iterator for searching list of local players Engine/GameInstance.h  

const TArray< ULocalPlayer * > & GetLocalPlayers()

 Returns reference to entire local player list Engine/GameInstance.h  

int32 GetNumLocalPlayers()

 Returns number of fully registered local players Engine/GameInstance.h  
Retrieves the name of the online subsystem for the platform used by this instance. Engine/GameInstance.h  

UOnlineSession * GetOnlineSession()

   Engine/GameInstance.h  

virtual TSubclassOf< UOnlineSession > GetOnlineSessionClass()

   Engine/GameInstance.h  

FOnPawnControllerChanged & GetOnPawnControllerChanged()

   Engine/GameInstance.h  

APlayerController * GetPrimaryPlayerController ( bool bRequiresValidUniqueId
) const

 Get the primary player controller on this machine (others are splitscreen children) (must have valid player state) Engine/GameInstance.h  

FUniqueNetIdRepl GetPrimaryPlayerUniqueIdRepl()

 Get the unique id for the primary player on this machine (others are splitscreen children) Engine/GameInstance.h  

TSubsystemClass * GetSubsystem ()

 Get a Subsystem of specified type Engine/GameInstance.h  

const TArray< TSubsystemClass * > & GetSubsystemArray ()

 Get all Subsystem of specified type, this is only necessary for interfaces that can have multiple implementations instanced at a time. Engine/GameInstance.h  

TArray< TSubsystemClass * > GetSubsystemArrayCopy ()

 Get all Subsystem of specified type, this is only necessary for interfaces that can have multiple implementations instanced at a time. Engine/GameInstance.h  

UGameInstanceSubsystem * GetSubsystemBase ( TSubclassOf< UGameInstanceSubsystem > SubsystemClass
) const

 Get a Subsystem of specified type Engine/GameInstance.h  

FTimerManager & GetTimerManager()

   Engine/GameInstance.h  

virtual UWorld * GetWorld()

   Engine/GameInstance.h  

FWorldContext * GetWorldContext()

   Engine/GameInstance.h  

virtual PRAGMA_DISABLE_DEPRECATION_WARNINGS void HandleDemoPlaybackFailure ( EDemoPlayFailure::Type FailureType,
const FString& ErrorString
)

 Called when demo playback fails for any reason Engine/GameInstance.h  

virtual void HandleDemoPlaybackFailure ( const UE::Net::TNetResult< EReplayResult >& Result
)

   Engine/GameInstance.h  

virtual void HandleDemoRecordFailure ( const UE::Net::TNetResult< EReplayResult >& Result
)

 Called when demo recording fails for any reason Engine/GameInstance.h  

virtual void HandleGameNetControlMessage ( UNetConnection* Connection,
uint8 MessageByte,
const FString& MessageStr
)

 Handle a game specific net control message (NMT_GameSpecific) this allows games to insert their own logic into the control channel the meaning of both data parameters is game-specific Engine/GameInstance.h  

virtual void HandleInputDeviceConnectionChange ( EInputDeviceConnectionState NewConnectionState,
FPlatformUserId PlatformUserId,
FInputDeviceId InputDeviceId
)

 Callback for handling an Input Device's connection state change. Engine/GameInstance.h  

virtual void HandleInputDevicePairingChange ( FInputDeviceId InputDeviceId,
FPlatformUserId NewUserPlatformId,
FPlatformUserId OldUserPlatformId
)

 Callback for handling an Input Device pairing change. Engine/GameInstance.h  

void HandleNetworkError ( ENetworkFailure::Type FailureType,
bool bIsServer
)

 Opportunity for blueprints to handle network errors. Engine/GameInstance.h
  • BlueprintImplementableEvent
  • Meta=(DisplayName="NetworkError")

void HandleTravelError ( ETravelFailure::Type FailureType
)

 Opportunity for blueprints to handle travel errors. Engine/GameInstance.h
  • BlueprintImplementableEvent
  • Meta=(DisplayName="TravelError")

virtual void Init()

 Virtual function to allow custom GameInstances an opportunity to set up what it needs Engine/GameInstance.h  

void InitializeForMinimalNetRPC ( const FName InPackageName
)

 Called to initialize the game instance with a minimal world suitable for basic network RPC Engine/GameInstance.h  

virtual FGameInstancePIEResult InitializeForPlayInEditor ( int32 PIEInstanceIndex,
const FGameInstancePIEParameters& Params
)

 Called to initialize the game instance for PIE instances of the game Engine/GameInstance.h  

void InitializeStandalone ( const FName InWorldName,
UPackage* InWorldPackage
)

 Called to initialize the game instance for standalone instances of the game Engine/GameInstance.h  

bool IsDedicatedServerInstance()

 Returns true if this instance is for a dedicated server world Engine/GameInstance.h  

virtual bool JoinSession ( ULocalPlayer* LocalPlayer,
const FOnlineSessionSearchResult& SearchResult
)

   Engine/GameInstance.h  

virtual bool JoinSession ( ULocalPlayer* LocalPlayer,
int32 SessionIndexInSearchResults
)

   Engine/GameInstance.h  

virtual void LoadComplete ( const float LoadTime,
const FString& MapName
)

   Engine/GameInstance.h  

virtual void ModifyClientTravelLevelURL ( FString& LevelName
)

 Game instance has an opportunity to modify the level name before the client starts travel Engine/GameInstance.h  

void NotifyPreClientTravel ( const FString& PendingURL,
ETravelType TravelType,
bool bIsSeamlessTravel
)

 Broadcast a notification that travel is occurring Engine/GameInstance.h  

FOnPreClientTravel & OnNotifyPreClientTravel()

   Engine/GameInstance.h  

virtual void OnSeamlessTravelDuringReplay()

 This gets called when the player scrubs in a replay to a different level Engine/GameInstance.h  

virtual void OnWorldChanged ( UWorld* OldWorld,
UWorld* NewWorld
)

 Callback from the world context when the world changes, this ensure the world context is set properly Engine/GameInstance.h  

virtual TSubclassOf< AGameModeBase > OverrideGameModeClass ( TSubclassOf< AGameModeBase > GameModeClass,
const FString& MapName,
const FString& Options,
const FString& Portal
) const

 Return the game mode subclass to use for a given map, options, and portal. Engine/GameInstance.h  

virtual void OverrideIrisReplicationSystemConfig ( FNetDriverReplicationSystemConfig& OutConfig,
bool bIsServer
) const

 Allows a GameInstance to override the default configuration of the Iris replication system. Engine/GameInstance.h  

virtual bool PlayReplay ( const FString& InName,
UWorld* WorldOverride,
const TArray< FString >& AdditionalOptions
)

 Start playing back a previously recorded replay. Engine/GameInstance.h  

bool PlayReplayPlaylist ( const FReplayPlaylistParams& PlaylistParams
)

 Start playing back a playlist of previously recorded replays. Engine/GameInstance.h  
Called as soon as the game mode is spawned, to allow additional PIE setting validation prior to creating the local players / etc... Engine/GameInstance.h  

virtual void PreloadContentForURL ( FURL InURL
)

 Call to preload any content before loading a map URL, used during seamless travel as well as map loading Engine/GameInstance.h  

virtual void ReceivedNetworkEncryptionAck ( const FOnEncryptionKeyResponse& Delegate
)

 Called when a client receives the EncryptionAck control message from the server, will generally enable encryption. Engine/GameInstance.h  

virtual EEncryptionFailureAction ReceivedNetworkEncryptionFailure ( UNetConnection* Connection
)

 Called when a connecting client fails to setup encryption Engine/GameInstance.h  

virtual void ReceivedNetworkEncryptionToken ( const FString& EncryptionToken,
const FOnEncryptionKeyResponse& Delegate
)

 Handle setting up encryption keys. Engine/GameInstance.h  

void ReceiveInit()

 Opportunity for blueprints to handle the game instance being initialized. Engine/GameInstance.h
  • BlueprintImplementableEvent
  • Meta=(DisplayName="Init")

void ReceiveShutdown()

 Opportunity for blueprints to handle the game instance being shutdown. Engine/GameInstance.h
  • BlueprintImplementableEvent
  • Meta=(DisplayName="Shutdown")

virtual void RegisterReferencedObject ( UObject* ObjectToReference
)

 Registers an object to keep alive as long as this game instance is alive Engine/GameInstance.h  

virtual bool RemoveLocalPlayer ( ULocalPlayer* ExistingPlayer
)

 Removes a player. Engine/GameInstance.h  

virtual void ReportPIEStartupTime()

   Engine/GameInstance.h  

virtual void ReturnToMainMenu ()

 Calls HandleDisconnect on either the OnlineSession if it exists or the engine, to cause a travel back to the default map. Engine/GameInstance.h  

virtual void SetPersistentTravelURL ( FURL InURL
)

 Call to modify the saved url that will be used as a base for future map travels Engine/GameInstance.h  

virtual void Shutdown()

 Virtual function to allow custom GameInstances an opportunity to do cleanup when shutting down Engine/GameInstance.h  

virtual void StartGameInstance()

 Starts the GameInstance state machine running Engine/GameInstance.h  

virtual FGameInstancePIEResult StartPlayInEditorGameInstance ( ULocalPlayer* LocalPlayer,
const FGameInstancePIEParameters& Params
)

 Called to actually start the game when doing Play/Simulate In Editor Engine/GameInstance.h  

virtual void StartRecordingReplay ( const FString& InName,
const FString& FriendlyName,
const TArray< FString >& AdditionalOptions,
TSharedPtr< IAnalyticsProvider > AnalyticsProvider
)

 Start recording a replay with the given custom name and friendly name. Engine/GameInstance.h  

virtual void StopRecordingReplay()

 Stop recording a replay if one is currently in progress Engine/GameInstance.h  

virtual void UnregisterReferencedObject ( UObject* ObjectToReference
)

 Remove a referenced object, this will allow it to GC out Engine/GameInstance.h  

Overridden from UObject

Name Remarks Include Path Unreal Specifiers

virtual void FinishDestroy()

   Engine/GameInstance.h  

Protected

Name Remarks Include Path Unreal Specifiers

void BroadcastOnStart()

 Non-virtual dispatch for OnStart, also calls the associated global OnStartGameInstance. Engine/GameInstance.h  

virtual bool HandleDisconnectCommand ( const TCHAR* Cmd,
FOutputDevice& Ar,
UWorld* InWorld
)

   Engine/GameInstance.h  

virtual bool HandleOpenCommand ( const TCHAR* Cmd,
FOutputDevice& Ar,
UWorld* InWorld
)

   Engine/GameInstance.h  

virtual bool HandleReconnectCommand ( const TCHAR* Cmd,
FOutputDevice& Ar,
UWorld* InWorld
)

   Engine/GameInstance.h  

virtual bool HandleTravelCommand ( const TCHAR* Cmd,
FOutputDevice& Ar,
UWorld* InWorld
)

   Engine/GameInstance.h  

void OnConsoleInput ( const FString& Command
)

 Delegate for handling external console commands Engine/GameInstance.h  

void OnPlayTogetherEventReceived ( int32 UserIndex,
const TArray< const FUniqueNetId& >& UserList
)

 Delegate for handling PS4 play together system events Engine/GameInstance.h  

virtual void OnStart()

 Called when the game instance is started either normally or through PIE. Engine/GameInstance.h  

Static

Name Remarks Include Path Unreal Specifiers

static void AddReferencedObjects ( UObject* InThis,
FReferenceCollector& Collector
)

   Engine/GameInstance.h  

static void CreateMinimalNetRPCWorld ( const FName InPackageName,
UPackage*& OutWorldPackage,
UWorld*& OutWorld
)

 Static util function used by InitializeForMinimalNetRPC and LoadMap to create the minimal world suitable for basic network RPC Engine/GameInstance.h  

static bool GetMapOverrideName ( const TCHAR* CmdLine,
FString& OverrideMapName
)

 Find a map override argument on the command-line string (the first argument without a leading '-' or -map=..., whichever comes first). Engine/GameInstance.h  

static TSubsystemClass * GetSubsystem ( const UGameInstance* GameInstance
)

 Get a Subsystem of specified type from the provided GameInstance returns nullptr if the Subsystem cannot be found or the GameInstance is null Engine/GameInstance.h  

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page