UnloadGameFeaturePlugin

UnloadGameFeaturePlugin

#Overview

name: UnloadGameFeaturePlugin

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

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of UnloadGameFeaturePlugin is to unload a specific game feature plugin from the Unreal Engine 5 runtime environment. It is part of the Game Features system, which allows for modular and dynamic loading/unloading of game content and functionality.

This setting variable is primarily used within the GameFeatures subsystem, specifically in the UGameFeaturesSubsystem class. It’s an essential part of the Game Features plugin, which is a core module in Unreal Engine 5 for managing modular game content.

The value of this variable is not set directly, but rather it’s used as a command name for a console command. It’s registered with the console command system in the Initialize function of UGameFeaturesSubsystem.

UnloadGameFeaturePlugin interacts with other functions and variables within the GameFeatures subsystem, such as UnloadAndKeepRegisteredGameFeaturePlugin and ReleaseGameFeaturePlugin. These functions provide different levels of unloading and management for game feature plugins.

Developers must be aware that:

1. This command can be used to unload plugins at runtime, which can significantly affect game behavior.
2. There’s an option to keep the plugin registered while unloading (bKeepRegistered parameter), which allows for quicker reloading if needed.
3. Unloading a plugin might have cascading effects on game systems that depend on that plugin.

Best practices when using this variable include:

1. Ensure that all dependencies are properly managed when unloading a plugin.
2. Use the bKeepRegistered option if you plan to reload the plugin soon, as it can improve performance.
3. Always test thoroughly after unloading plugins to ensure game stability.
4. Consider using this in conjunction with error handling and logging to track plugin management during development and live operations.
5. Be cautious when exposing this functionality in production builds, as it could potentially be misused or cause instability if not properly managed.

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

Scope (from outer to inner):

file
function     void UGameFeaturesSubsystem::Initialize

Source code excerpt:

	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))
			{
				UGameFeaturesSubsystem::Get().UnloadGameFeaturePlugin(PluginURL.GetValue());
			}
		}),
		ECVF_Cheat);

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

	IConsoleManager::Get().RegisterConsoleCommand(
		TEXT("ReleaseGameFeaturePlugin"),

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

Scope (from outer to inner):

file
function     void UGameFeaturesSubsystem::UnloadGameFeaturePlugin

Source code excerpt:

}

void UGameFeaturesSubsystem::UnloadGameFeaturePlugin(const FString& PluginURL, bool bKeepRegistered /*= false*/)
{
	UnloadGameFeaturePlugin(PluginURL, FGameFeaturePluginUnloadComplete(), bKeepRegistered);
}

void UGameFeaturesSubsystem::UnloadGameFeaturePlugin(const FString& PluginURL, const FGameFeaturePluginUnloadComplete& CompleteDelegate, bool bKeepRegistered /*= false*/)
{
	if (UGameFeaturePluginStateMachine* StateMachine = FindGameFeaturePluginStateMachine(PluginURL))
	{
		EGameFeaturePluginState TargetPluginState = bKeepRegistered ? EGameFeaturePluginState::Registered : EGameFeaturePluginState::Installed;
		ChangeGameFeatureDestination(StateMachine, FGameFeaturePluginStateRange(EGameFeaturePluginState::Terminal, TargetPluginState), CompleteDelegate);
	}

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

Scope (from outer to inner):

file
class        class UGameFeaturesSubsystem : public UEngineSubsystem

Source code excerpt:

	/** 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. */
	void ReleaseGameFeaturePlugin(const FString& PluginURL);
	void ReleaseGameFeaturePlugin(const FString& PluginURL, const FGameFeaturePluginReleaseComplete& CompleteDelegate);

	/** Uninstalls any game data stored for this GameFeaturePlugin and terminates the GameFeaturePlugin.