GameFeaturePlugin.ForceSyncAssetRegistryAppend

GameFeaturePlugin.ForceSyncAssetRegistryAppend

#Overview

name: GameFeaturePlugin.ForceSyncAssetRegistryAppend

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.ForceSyncAssetRegistryAppend is to control the behavior of asset registry appending in the Game Features plugin system of Unreal Engine 5. Specifically, it forces calls to IAssetRegistry::AppendState to happen on the game thread when enabled.

This setting variable is primarily used within the Game Features plugin, which is part of Unreal Engine’s modular game development system. Based on the callsites, it’s clear that this variable is utilized in the GameFeaturePluginStateMachine, which manages the lifecycle and states of game feature plugins.

The value of this variable is set through a console variable (CVar) system. It’s initialized as a static TAutoConsoleVariable with a default value of false. This means that by default, asset registry appending is not forced to happen on the game thread.

The associated variable CVarForceSyncAssetRegistryAppend directly interacts with GameFeaturePlugin.ForceSyncAssetRegistryAppend. They share the same value and purpose, with CVarForceSyncAssetRegistryAppend being the actual C++ variable used in the code to access the setting.

Developers must be aware that enabling this variable can impact performance and threading behavior. Forcing asset registry appending to happen on the game thread can potentially cause frame rate drops or hitches, especially when dealing with large asset registries or during periods of high game thread activity.

Best practices when using this variable include:

  1. Keep it disabled by default for optimal performance.
  2. Only enable it when debugging issues related to asset registry synchronization or when experiencing race conditions related to asset registration.
  3. Monitor performance closely when enabled, as it can potentially cause bottlenecks on the game thread.
  4. Use it in conjunction with profiling tools to understand its impact on your specific game’s performance.

Regarding the associated variable CVarForceSyncAssetRegistryAppend:

The purpose of CVarForceSyncAssetRegistryAppend is to provide programmatic access to the GameFeaturePlugin.ForceSyncAssetRegistryAppend setting within the C++ code.

This variable is used directly in the Game Features plugin, specifically in the UpdateState_LoadAssetRegistry function of the GameFeaturePluginStateMachine. It’s retrieved using the GetValueOnGameThread() method, indicating that its value is important for game thread operations.

The value of CVarForceSyncAssetRegistryAppend is set through the console variable system, matching the value of GameFeaturePlugin.ForceSyncAssetRegistryAppend.

It interacts closely with the asset loading and registration process, potentially affecting how and when asset states are appended to the main asset registry.

Developers should be aware that changing this variable’s value at runtime will affect the behavior of asset registration, which could lead to unexpected results if not properly managed.

Best practices for using CVarForceSyncAssetRegistryAppend include:

  1. Use it consistently with GameFeaturePlugin.ForceSyncAssetRegistryAppend, as they represent the same setting.
  2. Consider the performance implications when enabling it, especially in performance-critical sections of your game.
  3. Use it as a debugging tool rather than a permanent solution for asset registration issues.
  4. Document any use of this variable in your project, as it represents a deviation from the default engine 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:83

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		TEXT("Enable to force shaderlibs to be opened on the game thread"));

	static TAutoConsoleVariable<bool> CVarForceSyncAssetRegistryAppend(TEXT("GameFeaturePlugin.ForceSyncAssetRegistryAppend"),
		false,
		TEXT("Enable to force calls to IAssetRegistry::AppendState to happen on the game thread"));

	static TAutoConsoleVariable<bool> CVarWaitForDependencyDeactivation(TEXT("GameFeaturePlugin.WaitForDependencyDeactivation"),
		false,
		TEXT("Enable to make block deactivation until all dependencies are deactivated. Warning - this can lead to failure to unload"));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		TEXT("Enable to force shaderlibs to be opened on the game thread"));

	static TAutoConsoleVariable<bool> CVarForceSyncAssetRegistryAppend(TEXT("GameFeaturePlugin.ForceSyncAssetRegistryAppend"),
		false,
		TEXT("Enable to force calls to IAssetRegistry::AppendState to happen on the game thread"));

	static TAutoConsoleVariable<bool> CVarWaitForDependencyDeactivation(TEXT("GameFeaturePlugin.WaitForDependencyDeactivation"),
		false,
		TEXT("Enable to make block deactivation until all dependencies are deactivated. Warning - this can lead to failure to unload"));

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

Scope (from outer to inner):

file
function     void UpdateState_LoadAssetRegistry

Source code excerpt:

		}

		const bool bForceSyncAssetRegistryAppend = UE::GameFeatures::CVarForceSyncAssetRegistryAppend.GetValueOnGameThread();
		UE::Tasks::Launch(UE_SOURCE_LOCATION, [this, PluginAssetRegistry=MoveTemp(PluginAssetRegistry), bForceSyncAssetRegistryAppend]
		{
			bool bSuccess = false;
			TSharedPtr<FAssetRegistryState> PluginAssetRegistryState = MakeShared<FAssetRegistryState>();
			if (FAssetRegistryState::LoadFromDisk(*PluginAssetRegistry, FAssetRegistryLoadOptions(), *PluginAssetRegistryState))
			{