ControlRig.Hierarchy.TraceOnSpawn

ControlRig.Hierarchy.TraceOnSpawn

#Overview

name: ControlRig.Hierarchy.TraceOnSpawn

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 ControlRig.Hierarchy.TraceOnSpawn is to set the number of frames to trace when a new hierarchy is spawned in the Control Rig system of Unreal Engine 5. This setting is primarily used for debugging and performance analysis of the Control Rig hierarchy.

The Control Rig plugin, which is part of Unreal Engine’s animation system, relies on this setting variable. Specifically, it is used in the RigHierarchy module of the Control Rig plugin.

The value of this variable is set as a console variable, which means it can be changed at runtime through the console or configuration files. It is defined in the RigHierarchy.cpp file as a static TAutoConsoleVariable.

This variable interacts with the tracing system of the Control Rig hierarchy. It determines how many frames of data will be collected when a new hierarchy is created, which can be useful for debugging and performance analysis.

Developers must be aware that enabling tracing can have performance implications, especially if set to a high value. It should primarily be used for debugging purposes and not in production builds.

Best practices when using this variable include:

  1. Only enable it when necessary for debugging or performance analysis.
  2. Use a reasonable number of frames to avoid excessive memory usage and performance overhead.
  3. Remember to disable it or set it back to 0 after debugging is complete.

Regarding the associated variable CVarControlRigHierarchyTraceOnSpawn:

This is the actual console variable object that stores and manages the ControlRig.Hierarchy.TraceOnSpawn setting. It is defined as a static TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime through the console.

The purpose and usage of CVarControlRigHierarchyTraceOnSpawn are the same as ControlRig.Hierarchy.TraceOnSpawn. It’s used in the URigHierarchy constructor to initialize the tracing system when a new hierarchy is created.

Developers should interact with this variable through the console or configuration files rather than directly in code, as it’s designed to be a runtime-configurable setting. When debugging issues related to hierarchy spawning or performance, adjusting this value can provide valuable insights into the behavior of the Control Rig system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Animation/ControlRig/Source/ControlRig/Private/Rigs/RigHierarchy.cpp:46

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceCallstack(TEXT("ControlRig.Hierarchy.TraceCallstack"), 0, TEXT("if nonzero we will record the callstack for any trace entry.\nOnly works if(ControlRig.Hierarchy.TraceEnabled != 0)"));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTracePrecision(TEXT("ControlRig.Hierarchy.TracePrecision"), 3, TEXT("sets the number digits in a float when tracing hierarchies."));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceOnSpawn(TEXT("ControlRig.Hierarchy.TraceOnSpawn"), 0, TEXT("sets the number of frames to trace when a new hierarchy is spawned"));
TAutoConsoleVariable<bool> CVarControlRigHierarchyEnableRotationOrder(TEXT("ControlRig.Hierarchy.EnableRotationOrder"), true, TEXT("enables the rotation order for controls"));
TAutoConsoleVariable<bool> CVarControlRigHierarchyEnableModules(TEXT("ControlRig.Hierarchy.Modules"), true, TEXT("enables the modular rigging functionality"));
static int32 sRigHierarchyLastTrace = INDEX_NONE;
static TCHAR sRigHierarchyTraceFormat[16];

// A console command to trace a single frame / single execution for a control rig anim node / control rig component

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Animation/ControlRig/Source/ControlRig/Private/Rigs/RigHierarchy.cpp:46

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceCallstack(TEXT("ControlRig.Hierarchy.TraceCallstack"), 0, TEXT("if nonzero we will record the callstack for any trace entry.\nOnly works if(ControlRig.Hierarchy.TraceEnabled != 0)"));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTracePrecision(TEXT("ControlRig.Hierarchy.TracePrecision"), 3, TEXT("sets the number digits in a float when tracing hierarchies."));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceOnSpawn(TEXT("ControlRig.Hierarchy.TraceOnSpawn"), 0, TEXT("sets the number of frames to trace when a new hierarchy is spawned"));
TAutoConsoleVariable<bool> CVarControlRigHierarchyEnableRotationOrder(TEXT("ControlRig.Hierarchy.EnableRotationOrder"), true, TEXT("enables the rotation order for controls"));
TAutoConsoleVariable<bool> CVarControlRigHierarchyEnableModules(TEXT("ControlRig.Hierarchy.Modules"), true, TEXT("enables the modular rigging functionality"));
static int32 sRigHierarchyLastTrace = INDEX_NONE;
static TCHAR sRigHierarchyTraceFormat[16];

// A console command to trace a single frame / single execution for a control rig anim node / control rig component

#Loc: <Workspace>/Engine/Plugins/Animation/ControlRig/Source/ControlRig/Private/Rigs/RigHierarchy.cpp:133

Scope (from outer to inner):

file
function     URigHierarchy::URigHierarchy

Source code excerpt:

	Reset();
#if WITH_EDITOR
	TraceFrames(CVarControlRigHierarchyTraceOnSpawn->GetInt());
#endif
}

void URigHierarchy::BeginDestroy()
{
	// reset needs to be in begin destroy since