GameFeaturePlugin.ForceAsyncLoad

GameFeaturePlugin.ForceAsyncLoad

#Overview

name: GameFeaturePlugin.ForceAsyncLoad

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of GameFeaturePlugin.ForceAsyncLoad is to control the loading behavior of Game Feature Plugins in Unreal Engine 5. It allows developers to force asynchronous loading of these plugins even when it would normally not be allowed.

This setting variable is primarily used by the Game Features subsystem, which is part of the Runtime Game Features plugin in Unreal Engine 5. This plugin provides a framework for modular game development, allowing developers to add or remove features dynamically.

The value of this variable is set as a console variable (CVar) in the GameFeaturePluginStateMachine.cpp file. It is initialized with a default value of false, meaning that by default, it does not force asynchronous loading.

The associated variable CVarForceAsyncLoad directly interacts with GameFeaturePlugin.ForceAsyncLoad. They share the same value and purpose, with CVarForceAsyncLoad being the actual TAutoConsoleVariable instance that holds the value.

Developers must be aware that this variable can override the normal loading behavior of Game Feature Plugins. When set to true, it forces asynchronous loading even in situations where synchronous loading would typically be used, such as when running a commandlet.

Best practices when using this variable include:

  1. Use it cautiously, as forcing asynchronous loading may not always be desirable or safe in all contexts.
  2. Consider the implications on performance and game behavior when enabling this option.
  3. Use it primarily for debugging or specific optimization scenarios where asynchronous loading is beneficial.
  4. Be aware of its interaction with other loading-related settings, such as bForceSyncLoading in the ProtocolOptions.

Regarding the associated variable CVarForceAsyncLoad:

The purpose of CVarForceAsyncLoad is identical to GameFeaturePlugin.ForceAsyncLoad, as they are essentially the same variable. It’s the C++ implementation of the console variable that controls forced asynchronous loading of Game Feature Plugins.

CVarForceAsyncLoad is used directly in the code to check whether asynchronous loading should be allowed. For example, in the AllowAsyncLoading() function, it’s used in conjunction with other conditions to determine if async loading is permitted.

The value of CVarForceAsyncLoad is set through the console variable system, either programmatically or via console commands.

Developers should be aware that CVarForceAsyncLoad’s value is accessed using GetValueOnGameThread(), which ensures thread-safe access to the variable’s value.

Best practices for CVarForceAsyncLoad align with those of GameFeaturePlugin.ForceAsyncLoad, as they are functionally the same. Developers should use CVarForceAsyncLoad when they need to programmatically check or set the force async load behavior within C++ code.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturePluginStateMachine.cpp:71

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		TEXT("Enable to use aysnc loading"));

	static TAutoConsoleVariable<bool> CVarForceAsyncLoad(TEXT("GameFeaturePlugin.ForceAsyncLoad"),
		false,
		TEXT("Enable to force use of aysnc loading even if normally not allowed"));

	static TAutoConsoleVariable<bool> CVarAllowForceMonolithicShaderLibrary(TEXT("GameFeaturePlugin.AllowForceMonolithicShaderLibrary"),
		true,
		TEXT("Enable to force only searching for monolithic shader libs when possible"));

#Associated Variable and Callsites

This variable is associated with another variable named CVarForceAsyncLoad. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturePluginStateMachine.cpp:71

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		TEXT("Enable to use aysnc loading"));

	static TAutoConsoleVariable<bool> CVarForceAsyncLoad(TEXT("GameFeaturePlugin.ForceAsyncLoad"),
		false,
		TEXT("Enable to force use of aysnc loading even if normally not allowed"));

	static TAutoConsoleVariable<bool> CVarAllowForceMonolithicShaderLibrary(TEXT("GameFeaturePlugin.AllowForceMonolithicShaderLibrary"),
		true,
		TEXT("Enable to force only searching for monolithic shader libs when possible"));

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturePluginStateMachine.cpp:3675

Scope (from outer to inner):

file
function     bool FGameFeaturePluginStateMachineProperties::AllowAsyncLoading

Source code excerpt:

{
	// Ticking is required for async loading
	// The local bForceSyncLoading should take precedence over UE::GameFeatures::CVarForceAsyncLoad
	return
		!ProtocolOptions.bForceSyncLoading &&
		(!IsRunningCommandlet() || UE::GameFeatures::CVarForceAsyncLoad.GetValueOnGameThread());
}