AssetTools.UseHeaderPatchingAdvancedCopy

AssetTools.UseHeaderPatchingAdvancedCopy

#Overview

name: AssetTools.UseHeaderPatchingAdvancedCopy

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 AssetTools.UseHeaderPatchingAdvancedCopy is to enable header patching for advanced copy operations in the Asset Tools module of Unreal Engine 5. This setting is designed to optimize the asset copying process by using header patching instead of performing a full load of the assets.

This setting variable is primarily used in the AssetTools module, which is part of the Developer subsystem in Unreal Engine 5. It specifically affects the advanced copy functionality of assets.

The value of this variable is set through a console variable (CVar) system. It is initialized as false by default and can be changed at runtime using console commands or through configuration files.

The AssetTools.UseHeaderPatchingAdvancedCopy variable interacts directly with the boolean variable bEnableHeaderPatching. They share the same value, with the console variable acting as an interface to control the bEnableHeaderPatching flag.

Developers must be aware that enabling this variable will change the behavior of the advanced copy operation. Instead of fully loading assets during the copy process, it will use header patching, which can be faster but might have different implications depending on the asset types and project setup.

Best practices when using this variable include:

  1. Testing thoroughly after enabling it to ensure all assets are copied correctly.
  2. Using it in scenarios where performance during asset copying is a bottleneck.
  3. Being cautious when using it with complex assets or custom asset types that might not be fully compatible with header patching.

Regarding the associated variable bEnableHeaderPatching:

The purpose of bEnableHeaderPatching is to serve as the internal flag that controls whether header patching is used during advanced copy operations.

This variable is used within the AssetTools module, specifically in the AdvancedCopyPackages function of the UAssetToolsImpl class.

The value of bEnableHeaderPatching is set by the AssetTools.UseHeaderPatchingAdvancedCopy console variable.

It directly interacts with the console variable AssetTools.UseHeaderPatchingAdvancedCopy, serving as the actual boolean flag that the code checks to determine whether to use header patching.

Developers should be aware that this variable directly affects the behavior of the AdvancedCopyPackages function. When true, it triggers a different code path that uses header patching for copying assets.

Best practices for this variable include:

  1. Not modifying it directly in code, but rather using the console variable to control it.
  2. Considering its state when debugging issues related to asset copying in the engine.
  3. Being aware of its impact on performance and correctness when working on systems that involve asset copying or migration.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/AssetTools/Private/AssetTools.cpp:462

Scope (from outer to inner):

file
namespace    UE::AssetTools::Private

Source code excerpt:

	bool bEnableHeaderPatching = false;
	FAutoConsoleVariableRef CVarEnableHeaderPatching(
		TEXT("AssetTools.UseHeaderPatchingAdvancedCopy"),
		bEnableHeaderPatching,
		TEXT("If set to true, this will use Header Patching to copy the files instead of performing a full load."),
		ECVF_Default
	);

	// use a struct as a namespace to allow easier friend declarations

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Developer/AssetTools/Private/AssetTools.cpp:460

Scope (from outer to inner):

file
namespace    UE::AssetTools::Private

Source code excerpt:

	 * Default is false.
	 */
	bool bEnableHeaderPatching = false;
	FAutoConsoleVariableRef CVarEnableHeaderPatching(
		TEXT("AssetTools.UseHeaderPatchingAdvancedCopy"),
		bEnableHeaderPatching,
		TEXT("If set to true, this will use Header Patching to copy the files instead of performing a full load."),
		ECVF_Default
	);

	// use a struct as a namespace to allow easier friend declarations
	struct FPackageMigrationImpl

#Loc: <Workspace>/Engine/Source/Developer/AssetTools/Private/AssetTools.cpp:2314

Scope (from outer to inner):

file
function     bool UAssetToolsImpl::AdvancedCopyPackages

Source code excerpt:

		TUniquePtr<FScopedSlowTask> LoopProgress;

		if (UE::AssetTools::Private::bEnableHeaderPatching)
		{
			TRACE_CPUPROFILER_EVENT_SCOPE(AdvancedCopyPackages.HeaderPatching);

			std::atomic<int32> PatchAssetsCompletedCount = 0;
			UE::Tasks::FTaskEvent PatchAssetsCompletionTask{ UE_SOURCE_LOCATION };