DeactivateGameFeaturePlugin

DeactivateGameFeaturePlugin

#Overview

name: DeactivateGameFeaturePlugin

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

• type: Cmd
• help: Deactivates a game feature plugin by PluginName or URL

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of DeactivateGameFeaturePlugin is to deactivate a specific game feature plugin within the Unreal Engine 5 game features subsystem. This function is part of the Game Features plugin, which allows developers to dynamically load and unload game content and functionality at runtime.

The Game Features subsystem, specifically the UGameFeaturesSubsystem class, relies on this function to manage the lifecycle of game feature plugins. It is primarily used in the GameFeatures module of Unreal Engine 5.

The value of this variable is not set directly, as it is a function rather than a variable. However, it is called in various parts of the engine, including the GameFeaturesSubsystem initialization and in game-specific code like the LyraExperienceManagerComponent.

This function interacts with other parts of the Game Features system, such as the GameFeaturePluginStateMachine, which manages the state of game feature plugins. It also works in conjunction with other functions like UnloadGameFeaturePlugin to manage the full lifecycle of game feature plugins.

Developers must be aware that:

1. This function is asynchronous and uses a callback mechanism (FGameFeaturePluginDeactivateComplete) to notify when the deactivation is complete.
2. It should be called when you want to disable a specific game feature without completely unloading it from memory.
3. The function requires a valid plugin URL to identify which plugin to deactivate.

Best practices when using this function include:

1. Always check if the plugin is active before attempting to deactivate it.
2. Use the overload that accepts a completion delegate if you need to perform actions after the plugin is deactivated.
3. Pair this function with proper activation calls to manage the lifecycle of your game features effectively.
4. Be cautious when deactivating plugins during gameplay, as it might affect the current game state.
5. Consider using this in conjunction with the game’s experience management system, as shown in the LyraExperienceManagerComponent example.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturesSubsystem.cpp:390

Scope (from outer to inner):

file
function     void UGameFeaturesSubsystem::Initialize

Source code excerpt:

	IConsoleManager::Get().RegisterConsoleCommand(
		TEXT("DeactivateGameFeaturePlugin"),
		TEXT("Deactivates a game feature plugin by PluginName or URL"),
		FConsoleCommandWithWorldArgsAndOutputDeviceDelegate::CreateLambda([](const TArray<FString>& Args, UWorld*, FOutputDevice& Ar)
		{
			if (TOptional<FString> PluginURL = UE::GameFeatures::GetPluginUrlForConsoleCommand(Args, Ar))
			{
				UGameFeaturesSubsystem::Get().DeactivateGameFeaturePlugin(PluginURL.GetValue(), FGameFeaturePluginLoadComplete());
			}
		}),
		ECVF_Cheat);

	IConsoleManager::Get().RegisterConsoleCommand(
		TEXT("UnloadGameFeaturePlugin"),
		TEXT("Unloads a game feature plugin by PluginName or URL"),
		FConsoleCommandWithWorldArgsAndOutputDeviceDelegate::CreateLambda([](const TArray<FString>& Args, UWorld*, FOutputDevice& Ar)
		{
			if (TOptional<FString> PluginURL = UE::GameFeatures::GetPluginUrlForConsoleCommand(Args, Ar))

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Private/GameFeaturesSubsystem.cpp:1522

Scope (from outer to inner):

file
function     void UGameFeaturesSubsystem::DeactivateGameFeaturePlugin

Source code excerpt:

}

void UGameFeaturesSubsystem::DeactivateGameFeaturePlugin(const FString& PluginURL)
{
	DeactivateGameFeaturePlugin(PluginURL, FGameFeaturePluginDeactivateComplete());
}

void UGameFeaturesSubsystem::DeactivateGameFeaturePlugin(const FString& PluginURL, const FGameFeaturePluginDeactivateComplete& CompleteDelegate)
{
	if (UGameFeaturePluginStateMachine* StateMachine = FindGameFeaturePluginStateMachine(PluginURL))
	{
		ChangeGameFeatureDestination(StateMachine, FGameFeaturePluginStateRange(EGameFeaturePluginState::Terminal, EGameFeaturePluginState::Loaded), CompleteDelegate);
	}
	else

#Loc: <Workspace>/Engine/Plugins/Runtime/GameFeatures/Source/GameFeatures/Public/GameFeaturesSubsystem.h:541

Scope (from outer to inner):

file
class        class UGameFeaturesSubsystem : public UEngineSubsystem

Source code excerpt:

	/** Deactivates the specified plugin */
	void DeactivateGameFeaturePlugin(const FString& PluginURL);
	void DeactivateGameFeaturePlugin(const FString& PluginURL, const FGameFeaturePluginDeactivateComplete& CompleteDelegate);

	/** Unloads the specified game feature plugin. */
	void UnloadGameFeaturePlugin(const FString& PluginURL, bool bKeepRegistered = false);
	void UnloadGameFeaturePlugin(const FString& PluginURL, const FGameFeaturePluginUnloadComplete& CompleteDelegate, bool bKeepRegistered = false);

	/** Releases any game data stored for this GameFeaturePlugin. Does not uninstall data and it will remain on disk. */

#Loc: <Workspace>/Projects/Lyra/Source/LyraGame/GameModes/LyraExperienceManagerComponent.cpp:387

Scope (from outer to inner):

file
function     void ULyraExperienceManagerComponent::EndPlay

Source code excerpt:

		if (ULyraExperienceManager::RequestToDeactivatePlugin(PluginURL))
		{
			UGameFeaturesSubsystem::Get().DeactivateGameFeaturePlugin(PluginURL);
		}
	}

	//@TODO: Ensure proper handling of a partially-loaded state too
	if (LoadState == ELyraExperienceLoadState::Loaded)
	{