cpfuo.UseAggressiveReferenceReplacment

cpfuo.UseAggressiveReferenceReplacment

#Overview

name: cpfuo.UseAggressiveReferenceReplacment

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 cpfuo.UseAggressiveReferenceReplacment is to control whether aggressive reference replacement should be used during object copying operations in Unreal Engine. This setting is primarily related to the object management and reference handling system within the engine.

This setting variable is used in the Engine module, specifically in the UnrealEngine.cpp file. It’s part of the core engine functionality that deals with object copying and reference management.

The value of this variable is set through a console variable (CVarUseAggressiveReferenceReplacement) using the TAutoConsoleVariable template. It’s initialized with a default value of 0 (false), indicating that aggressive reference replacement is disabled by default.

The associated variable CVarUseAggressiveReferenceReplacement directly interacts with this setting. It’s used to retrieve the current value of the setting in the code.

Developers must be aware that this feature is being deprecated, as indicated in the description text. It’s left as a toggle-able option in case issues arise with the new behavior. This suggests that the engine is moving away from aggressive reference replacement, but provides a fallback option if needed.

Best practices when using this variable include:

  1. Generally, leave it disabled (default setting) unless specific issues are encountered that require the old behavior.
  2. If enabled, thoroughly test the impact on your project, especially in areas involving object copying and reference management.
  3. Plan for its eventual removal, as it’s marked for deprecation.

Regarding the associated variable CVarUseAggressiveReferenceReplacement:

The purpose of CVarUseAggressiveReferenceReplacement is to provide programmatic access to the cpfuo.UseAggressiveReferenceReplacment setting within the C++ code.

This variable is used in the Engine module, specifically in the UEngine::CopyPropertiesForUnrelatedObjects function.

The value of this variable is set by the console variable system based on the cpfuo.UseAggressiveReferenceReplacment setting.

It directly interacts with the cpfuo.UseAggressiveReferenceReplacment setting, essentially serving as its in-code representation.

Developers should be aware that this variable is used to control behavior in object copying operations. Its value is retrieved using the GetValueOnAnyThread() method, suggesting it can be accessed from multiple threads.

Best practices for using this variable include:

  1. Use it for read-only purposes in most cases, as changing its value directly may lead to unexpected behavior.
  2. Be cautious when relying on its value, as the aggressive replacement behavior is being phased out.
  3. Consider adding fallback behavior in code that uses this variable to prepare for its eventual removal.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:17142

Scope: file

Source code excerpt:


TAutoConsoleVariable<bool> CVarUseAggressiveReferenceReplacement(
	TEXT("cpfuo.UseAggressiveReferenceReplacment"),
	0,
	TEXT("Whether to aggressively replace references. This behavior is being deprecated but being left with the ability to toggle back on in case issues arise.\n"),
	ECVF_Default);

class FAggressiveReplacementAuditArchive : public FArchiveReplaceOrClearExternalReferences<UObject>
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:17141

Scope: file

Source code excerpt:

	ECVF_Cheat);

TAutoConsoleVariable<bool> CVarUseAggressiveReferenceReplacement(
	TEXT("cpfuo.UseAggressiveReferenceReplacment"),
	0,
	TEXT("Whether to aggressively replace references. This behavior is being deprecated but being left with the ability to toggle back on in case issues arise.\n"),
	ECVF_Default);

class FAggressiveReplacementAuditArchive : public FArchiveReplaceOrClearExternalReferences<UObject>

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:17285

Scope (from outer to inner):

file
function     void UEngine::CopyPropertiesForUnrelatedObjects

Source code excerpt:

	constexpr bool bAuditAggressiveReplacement = false;
#endif
	const bool bDoAggressiveReplacement = CVarUseAggressiveReferenceReplacement.GetValueOnAnyThread();

	{
		CollectAllSubobjects( NewObject, ComponentsOnNewObject );

		// populate the ReferenceReplacementMap 
		for (int32 Index = 0; Index < ComponentsOnNewObject.Num(); Index++)