GameFeaturePlugin.AsyncLoad

GameFeaturePlugin.AsyncLoad

#Overview

name: GameFeaturePlugin.AsyncLoad

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of GameFeaturePlugin.AsyncLoad is to control whether Game Feature Plugins should be loaded asynchronously or synchronously. It is primarily used for managing the loading behavior of Game Feature Plugins in Unreal Engine 5.

This setting variable is utilized by the Game Features subsystem, which is part of the Runtime Game Features plugin. Based on the callsites, it’s clear that this variable is used within the GameFeatures module of Unreal Engine.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of true, meaning asynchronous loading is enabled by default.

The associated variable CVarAsyncLoad directly interacts with GameFeaturePlugin.AsyncLoad. They share the same value and purpose.

Developers must be aware of the following when using this variable:

  1. It affects the loading behavior of Game Feature Plugins.
  2. It can be overridden in certain scenarios, such as for initially loaded plugins.
  3. Changing this value may impact game performance and loading times.

Best practices when using this variable include:

  1. Consider the trade-offs between asynchronous and synchronous loading for your specific use case.
  2. Be aware that forcing synchronous loading for initially loaded plugins may be necessary in some cases.
  3. Use in conjunction with other related variables like GameFeaturePlugin.ForceAsyncLoad for fine-tuned control.

Regarding the associated variable CVarAsyncLoad: The purpose of CVarAsyncLoad is to provide a runtime-configurable way to enable or disable asynchronous loading of Game Feature Plugins. It is used internally by the Game Features subsystem to determine whether to use asynchronous loading.

CVarAsyncLoad is set using the TAutoConsoleVariable system, which allows it to be changed at runtime through console commands.

Other variables that interact with CVarAsyncLoad include GameFeaturePlugin.ForceAsyncLoad, which can override the behavior in certain situations.

Developers should be aware that:

  1. The value of CVarAsyncLoad can be queried at runtime to determine the current loading behavior.
  2. It’s used in conjunction with other checks to determine the final loading behavior.

Best practices for using CVarAsyncLoad include:

  1. Use it in combination with other Game Feature Plugin settings for comprehensive control over loading behavior.
  2. Consider exposing it as a configurable option in your game’s settings if dynamic control over loading behavior is desired.
  3. Be cautious when changing its value during gameplay, as it may affect performance and behavior.

#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:67

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		TEXT("True if we should defer loading the localization data until 'loading' (new behavior), or false to load it on 'mounting' (old behavior)."));

	static TAutoConsoleVariable<bool> CVarAsyncLoad(TEXT("GameFeaturePlugin.AsyncLoad"),
		true,
		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"));

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturesProjectPolicies.cpp:13

Scope (from outer to inner):

file
function     void UDefaultGameFeaturesProjectPolicies::InitGameFeatureManager
lambda-function

Source code excerpt:

	auto AdditionalFilter = [&](const FString& PluginFilename, const FGameFeaturePluginDetails& PluginDetails, FBuiltInGameFeaturePluginBehaviorOptions& OutOptions) -> bool
	{
		// By default, force all initially loaded plugins to synchronously load, this overrides the behavior of GameFeaturePlugin.AsyncLoad which will be used for later loads
		OutOptions.bForceSyncLoading = true;

		// By default, no plugins are filtered so we expect all built-in dependencies to be created before their parent GFPs
		OutOptions.bLogWarningOnForcedDependencyCreation = true;

		return true;

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		TEXT("True if we should defer loading the localization data until 'loading' (new behavior), or false to load it on 'mounting' (old behavior)."));

	static TAutoConsoleVariable<bool> CVarAsyncLoad(TEXT("GameFeaturePlugin.AsyncLoad"),
		true,
		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"));

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

Scope (from outer to inner):

file
function     bool FGameFeaturePluginState::UseAsyncLoading

Source code excerpt:

bool FGameFeaturePluginState::UseAsyncLoading() const
{
	return AllowAsyncLoading() && UE::GameFeatures::CVarAsyncLoad.GetValueOnGameThread();
}

/*
=========================================================
  States
=========================================================