r.MaterialsDuplicateVerbatim

r.MaterialsDuplicateVerbatim

#Overview

name: r.MaterialsDuplicateVerbatim

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.MaterialsDuplicateVerbatim is to control the behavior of material and material function duplication in Unreal Engine 5, specifically regarding the StateId of these assets.

This setting variable is primarily used in the materials system of Unreal Engine. It affects how materials and material functions are handled when they are duplicated.

The value of this variable is set through the console variable system. It’s defined as a TAutoConsoleVariable in the Engine/Source/Runtime/Engine/Private/Materials/Material.cpp file, with a default value of false.

The variable interacts closely with the StateId property of materials and material functions. When r.MaterialsDuplicateVerbatim is false (the default), duplicating a material or material function will generate a new StateId. When it’s true, the StateId will be preserved during duplication.

Developers should be aware that this variable affects the Derived Data Cache (DDC) keys for materials and material functions. Changing this setting could impact asset caching and loading behavior.

Best practices when using this variable include:

  1. Generally, leave it at its default value (false) unless you have a specific reason to change it.
  2. If you enable it, be aware that duplicated materials will have the same StateId, which could lead to unexpected behavior with the DDC.
  3. Use this setting carefully in production environments, as it can affect how materials are cached and loaded.

The associated variable CVarMaterialsDuplicateVerbatim is the actual console variable object that stores and manages the r.MaterialsDuplicateVerbatim setting. It’s used in the same way and for the same purpose as r.MaterialsDuplicateVerbatim.

This variable is checked in the PostDuplicate functions of both UMaterial and UMaterialFunctionInterface classes. When duplicating these assets, the code checks the value of CVarMaterialsDuplicateVerbatim to determine whether to generate a new StateId or keep the existing one.

Developers should use CVarMaterialsDuplicateVerbatim when they need to programmatically check or set the value of this setting in C++ code. For example, they might use CVarMaterialsDuplicateVerbatim->GetValueOnAnyThread() to retrieve the current value of the setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/Material.cpp:122

Scope: file

Source code excerpt:

	
static TAutoConsoleVariable<bool> CVarMaterialsDuplicateVerbatim(
	TEXT("r.MaterialsDuplicateVerbatim"),
	false,
	TEXT("When enabled, when a material or material function is duplicated, it will not change StateId (which influences DDC keys) pre-emptively.\n")
	TEXT("Default: false"),
	ECVF_Default);

namespace MaterialImpl

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialExpressions.cpp:14458

Scope (from outer to inner):

file
function     void UMaterialFunctionInterface::PostDuplicate

Source code excerpt:

	Super::PostDuplicate(bDuplicateForPIE);

	static const auto CVarDuplicateVerbatim = IConsoleManager::Get().FindTConsoleVariableDataBool(TEXT("r.MaterialsDuplicateVerbatim"));
	const bool bKeepStateId = StateId.IsValid() && HasAnyFlags(RF_WasLoaded) && CVarDuplicateVerbatim->GetValueOnAnyThread();
	if (!bKeepStateId)
	{
		// Initialize StateId to something unique, in case this is a new function
		StateId = FGuid::NewGuid();
	}

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/Material.cpp:121

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);
	
static TAutoConsoleVariable<bool> CVarMaterialsDuplicateVerbatim(
	TEXT("r.MaterialsDuplicateVerbatim"),
	false,
	TEXT("When enabled, when a material or material function is duplicated, it will not change StateId (which influences DDC keys) pre-emptively.\n")
	TEXT("Default: false"),
	ECVF_Default);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/Material.cpp:2931

Scope (from outer to inner):

file
function     void UMaterial::PostDuplicate

Source code excerpt:

	Super::PostDuplicate(bDuplicateForPIE);

	if (!CVarMaterialsDuplicateVerbatim.GetValueOnAnyThread())
	{
		// Reset the StateId on duplication since it needs to be unique for each material.
		FPlatformMisc::CreateGuid(StateId);
	}
}