GameFeaturePlugin.WaitForDependencyDeactivation

GameFeaturePlugin.WaitForDependencyDeactivation

#Overview

name: GameFeaturePlugin.WaitForDependencyDeactivation

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

• type: Var
• help: Enable to make block deactivation until all dependencies are deactivated. Warning - this can lead to failure to unload

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of GameFeaturePlugin.WaitForDependencyDeactivation is to control the deactivation behavior of game feature plugins with respect to their dependencies. It is specifically related to the Game Features system in Unreal Engine 5.

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

The value of this variable is set as a console variable (cvar) using TAutoConsoleVariable. It is initialized to false by default, meaning the behavior it controls is not enabled by default.

The associated variable CVarWaitForDependencyDeactivation directly interacts with GameFeaturePlugin.WaitForDependencyDeactivation. They share the same value and purpose.

Developers must be aware of several important aspects when using this variable:

1. When enabled (set to true), it forces the deactivation process to wait until all dependencies of a game feature plugin are deactivated.
2. The description warns that enabling this feature can lead to failure to unload, which could potentially cause memory leaks or other issues.
3. This setting can significantly impact the behavior of game feature plugin deactivation, potentially altering the order and timing of plugin shutdowns.

Best practices when using this variable include:

1. Keep it disabled (false) by default unless there’s a specific need for sequential dependency deactivation.
2. If enabled, thoroughly test the deactivation process to ensure no plugins get stuck in an unloadable state.
3. Use this in conjunction with proper dependency management in your game feature plugins to avoid circular dependencies that could lead to deactivation issues.
4. Monitor performance and memory usage when this feature is enabled, as it may impact shutdown times and resource management.

Regarding the associated variable CVarWaitForDependencyDeactivation:

This is the actual console variable object that controls the behavior. It’s used internally by the Game Features system to check whether the wait-for-dependency behavior should be applied. The ShouldWaitForDependencies() function uses this variable to determine the runtime behavior of the deactivation process.

Developers should be aware that changing this variable at runtime (through console commands or code) will immediately affect the behavior of game feature plugin deactivation. Care should be taken when modifying this value, especially in a shipping game, as it could lead to unexpected behavior or stability issues if not properly tested.

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

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		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"));

	bool ShouldSkipVerify(const FString& PluginName)
	{
		static const FAsciiSet Wildcards("*?");

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    UE::GameFeatures

Source code excerpt:

		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"));

	bool ShouldSkipVerify(const FString& PluginName)
	{
		static const FAsciiSet Wildcards("*?");

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

Scope (from outer to inner):

file
function     static bool ShouldWaitForDependencies

Source code excerpt:

	static bool ShouldWaitForDependencies()
	{
		return UE::GameFeatures::CVarWaitForDependencyDeactivation.GetValueOnGameThread();
	}
};

struct FGameFeaturePluginState_DeactivatingDependencies : public FTransitionDependenciesGameFeaturePluginState<FDeactivatingDependenciesTransitionPolicy>
{
	FGameFeaturePluginState_DeactivatingDependencies(FGameFeaturePluginStateMachineProperties& InStateProperties)