1. Epic GamesDeveloper
  3. UGameInstance

UGameInstance

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

Unreal Engine C++ API Reference > Runtime > Engine > Engine

Inheritance Hierarchy

References

   
Module Engine
Header /Engine/Source/Runtime/Engine/Classes/Engine/GameInstance.h
Include #include "Engine/GameInstance.h"

Syntax

class UGameInstance :  
    public UObject,  
    public FExec

Remarks

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.

Variables

  Type Name Description
Public variable bool bReportedPIEStartupTime  
Public variable FLatentActionManager * LatentActionManager  
Protected variable TArray< TObjectPtr< ULocalPlayer > > LocalPlayers List of locally participating players in this game instance
Protected variable FOnPreClientTravel NotifyPreClientTravelDelegates Listeners to PreClientTravel call
Public variable FOnUserInputDeviceConnectionChange OnInputDeviceConnectionChange Callback for when an input device connection state has changed (a new gamepad was connected or disconnected)
Protected variable TObjectPtr< class UOnlineSession > OnlineSession Class to manage online services
Public variable FOnLocalPlayerEvent OnLocalPlayerAddedEvent Local player access
Public variable FOnLocalPlayerEvent OnLocalPlayerRemovedEvent  
Protected variable FOnPawnControllerChanged OnPawnControllerChangedDelegates Gets triggered shortly after a pawn's controller is set.
Protected variable FDelegateHandle OnPlayTogetherEventReceivedDelegateHandle Handle for delegate for handling PS4 play together system events
Public variable FOnUserInputDevicePairingChange OnUserInputDevicePairingChange Callback when an input device has changed pairings (the owning platform user has changed for that device)
Public variable FString PIEMapName  
Public variable double PIEStartTime  
Protected variable TArray< TObjectPtr< UObject > > ReferencedObjects List of objects that are being kept alive by this game instance.
Public variable FTimerManager * TimerManager  
Protected variable FWorldContext * WorldContext  

Constructors

  Type Name Description
Public function  

UGameInstance ( const FObjectInitializer& ObjectInitializer
)

  

Functions

  Type Name Description
Public function Virtual int32 Adds a LocalPlayer to the local and global list of Players.
Public function Static void  
Public function 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)
Protected function void Non-virtual dispatch for OnStart, also calls the associated global OnStartGameInstance.
Public function void  
Public function 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
Public function Virtual AGameModeBase *

CreateGameModeForURL ( FURL InURL,
UWorld* InWorld
)

 Call to create the game mode for a given map URL
Public function Virtual ULocalPlayer *  
Public function ULocalPlayer *

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

 Adds a new player.
Public function ULocalPlayer *

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

 Adds a new player.
Public function 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
Public function Virtual void

DebugCreatePlayer ( int32 ControllerId
)

 Debug console command to create a player.
Public function Virtual void

DebugRemovePlayer ( int32 ControllerId
)

 Debug console command to remove the player with a given controller ID.
Public function Virtual bool Return true to delay player controller spawn (sending NMT_Join)
Public function Virtual bool Return true to delay an otherwise ready-to-join PendingNetGame performing LoadMap() and finishing up useful to wait for content downloads, etc
Public function 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
Public function Const ULocalPlayer *

FindLocalPlayerFromControllerId ( const int32 ControllerId
)

 Returns the local player assigned to a physical Controller Id, or null if not found
Public function Const ULocalPlayer * Returns the local player assigned to this platform user id, or null if not found
Public function Const ULocalPlayer *

FindLocalPlayerFromUniqueNetId ( FUniqueNetIdPtr UniqueNetId
)

 Returns the local player that has been assigned the specific unique net id
Public function Const ULocalPlayer * Returns the local player that has been assigned the specific unique net id
Public function Const ULocalPlayer * Returns the local player that has been assigned the specific unique net id
Public function Const UEngine *  
Public function Const ULocalPlayer * Returns the first local player, will not be null during normal gameplay
Public function Const APlayerController * Returns the player controller assigned to the first local player.
Public function Const UGameViewportClient *  
Public function Const FLatentActionManager &  
Public function Const ULocalPlayer *

GetLocalPlayerByIndex ( const int32 Index
)

 Returns the local player at a certain index, or null if not found
Public function Const TArray< ULocalPlayer * >::TConstIterator Returns const iterator for searching list of local players
Public function Const const TArray< ULocalPlayer * > & Returns reference to entire local player list
Protected function 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).
Public function Const int32 Returns number of fully registered local players
Public function Virtual Const FName Retrieves the name of the online subsystem for the platform used by this instance.
Public function Const UOnlineSession *  
Public function Virtual TSubclassOf< UOnlineSession >  
Public function FOnPawnControllerChanged &  
Public function Const APlayerController *

GetPrimaryPlayerController ( bool bRequiresValidUniqueId
)

 Get the primary player controller on this machine (others are splitscreen children) (must have valid player state)
Public function Const FUniqueNetIdRepl Get the unique id for the primary player on this machine (others are splitscreen children)
Public function Const TSubsystemClass * Get a Subsystem of specified type
Public function 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
Public function Const const TArray< TSubsystemClass * > & Get all Subsystem of specified type, this is only necessary for interfaces that can have multiple implementations instanced at a time.
Public function Const UGameInstanceSubsystem * Get a Subsystem of specified type
Public function Const FTimerManager &  
Public function Virtual Const UWorld *  
Public function Const FWorldContext *  
Public function Virtual void

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

  
Public function Virtual void

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

 Called when demo recording fails for any reason
Protected function Virtual bool

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

  
Public function 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
Public function Virtual void

HandleInputDeviceConnectionChange ( EInputDeviceConnectionState NewConnectionState,
FPlatformUserId PlatformUserId,
FInputDeviceId InputDeviceId
)

 Callback for handling an Input Device's connection state change.
Public function Virtual void

HandleInputDevicePairingChange ( FInputDeviceId InputDeviceId,
FPlatformUserId NewUserPlatformId,
FPlatformUserId OldUserPlatformId
)

 Callback for handling an Input Device pairing change.
Public function void

HandleNetworkError ( ENetworkFailure::Type FailureType,
bool bIsServer
)

 Opportunity for blueprints to handle network errors.
Protected function Virtual bool

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

  
Protected function Virtual bool

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

  
Protected function Virtual bool

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

  
Public function void Opportunity for blueprints to handle travel errors.
Public function Virtual void

Init ()

 Virtual function to allow custom GameInstances an opportunity to set up what it needs
Public function void

InitializeForMinimalNetRPC ( const FName InPackageName
)

 Called to initialize the game instance with a minimal world suitable for basic network RPC
Public function Virtual FGameInstancePIEResult

InitializeForPlayInEditor ( int32 PIEInstanceIndex,
const FGameInstancePIEParameters& Params
)

 Called to initialize the game instance for PIE instances of the game
Public function void

InitializeStandalone ( const FName InWorldName,
UPackage* InWorldPackage
)

 Called to initialize the game instance for standalone instances of the game
Public function Const bool Returns true if this instance is for a dedicated server world
Public function Virtual bool

JoinSession ( ULocalPlayer* LocalPlayer,
const FOnlineSessionSearchResult& SearchResult
)

  
Public function Virtual bool

JoinSession ( ULocalPlayer* LocalPlayer,
int32 SessionIndexInSearchResults
)

  
Public function Virtual void

LoadComplete ( const float LoadTime,
const FString& MapName
)

  
Public function Virtual void Game instance has an opportunity to modify the level name before the client starts travel
Public function void

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

 Broadcast a notification that travel is occurring
Protected function void

OnConsoleInput ( const FString& Command
)

 Delegate for handling external console commands
Public function FOnPreClientTravel &  
Protected function void

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

 Delegate for handling PS4 play together system events
Public function Virtual void This gets called when the player scrubs in a replay to a different level
Protected function Virtual void

OnStart ()

 Called when the game instance is started either normally or through PIE.
Public function Virtual void

OnWorldChanged ( UWorld* OldWorld,
UWorld* NewWorld
)

 Callback from the world context when the world changes
Public function Virtual Const TSubclassOf< AGameModeBase >

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

 Return the game mode subclass to use for a given map, options, and portal.
Public function Virtual bool

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

 Start playing back a previously recorded replay.
Public function bool

PlayReplayPlaylist ( const FReplayPlaylistParams& PlaylistParams
)

 Start playing back a playlist of previously recorded replays.
Public function Virtual FGameInstancePIEResult Called as soon as the game mode is spawned, to allow additional PIE setting validation prior to creating the local players / etc...
Public function Virtual void Call to preload any content before loading a map URL, used during seamless travel as well as map loading
Public function Virtual void

ReceivedNetworkEncryptionAck ( const FOnEncryptionKeyResponse& Delegate
)

 Called when a client receives the EncryptionAck control message from the server, will generally enable encryption.
Public function Virtual EEncryptionFailureAction Called when a connecting client fails to setup encryption
Public function Virtual void

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

 Handle setting up encryption keys.
Public function void Opportunity for blueprints to handle the game instance being initialized.
Public function void Opportunity for blueprints to handle the game instance being shutdown.
Public function Virtual void

RegisterReferencedObject ( UObject* ObjectToReference
)

 Registers an object to keep alive as long as this game instance is alive
Public function Virtual bool

RemoveLocalPlayer ( ULocalPlayer* ExistingPlayer
)

 Removes a player.
Public function void  
Public function Virtual void Calls HandleDisconnect on either the OnlineSession if it exists or the engine, to cause a travel back to the default map.
Public function Virtual void Call to modify the saved url that will be used as a base for future map travels
Public function Virtual void Virtual function to allow custom GameInstances an opportunity to do cleanup when shutting down
Public function Virtual void Starts the GameInstance state machine running
Public function Virtual FGameInstancePIEResult Called to actually start the game when doing Play/Simulate In Editor
Public function 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.
Public function Virtual void Stop recording a replay if one is currently in progress
Public function Virtual void

UnregisterReferencedObject ( UObject* ObjectToReference
)

 Remove a referenced object, this will allow it to GC out

Overridden from UObject

  Type Name Description
Public function Virtual void Called to finish destroying the object.

Deprecated Functions

  Type Name Description
Public function Virtual int32

AddLocalPlayer ( ULocalPlayer* NewPlayer,
int32 ControllerId
)

 This version of AddLocalPlayer has been deprecated, pleasse use the version that takes a FPlatformUserId instead.
Public function Const FUniqueNetIdPtr Use GetPrimaryPlayerUniqueIdRepl.
Public function Virtual PRAGMA_DISABLE_DEPRECATION_WARNINGSvoid

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

 Now takes a EReplayResult instead.

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page
Back to top
Games
Marketplaces
Tools
Online Services
Resources
Company

© 2004-2025, Epic Games, Inc. All rights reserved. Unreal and its logo are Epic’s trademarks or registered trademarks in the US and elsewhere.