p.ReportTooManyChildrenNum

p.ReportTooManyChildrenNum

#Overview

name: p.ReportTooManyChildrenNum

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

• type: Var
• help: Issue warning if more than this many children exist in a single cluster

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.ReportTooManyChildrenNum is to set a threshold for issuing a warning when a single cluster in a geometry collection contains more children than the specified number. This setting is primarily used in the physics system, specifically for geometry collections and clustering in Unreal Engine’s Chaos physics engine.

The Unreal Engine subsystem that relies on this setting variable is the Experimental Chaos physics module, particularly the GeometryCollectionPhysicsProxy component.

The value of this variable is set through a console variable (CVar) named “p.ReportTooManyChildrenNum”. It is initialized with a default value of -1, which means the warning is disabled by default.

The associated variable ReportTooManyChildrenNum interacts directly with p.ReportTooManyChildrenNum. They share the same value, with ReportTooManyChildrenNum being the actual variable used in the code, while p.ReportTooManyChildrenNum is the console variable name used to set its value.

Developers must be aware of the following when using this variable:

1. A value of -1 (default) disables the warning.
2. Setting a positive value will enable the warning system for clusters with more children than the specified number.
3. This variable is used in the context of geometry collection initialization and clustering.

Best practices when using this variable include:

1. Use it for debugging and optimization purposes to identify potentially problematic clusters with too many children.
2. Set an appropriate threshold based on your specific use case and performance requirements.
3. Consider the performance implications of having clusters with a large number of children and use this variable to help identify such cases.

Regarding the associated variable ReportTooManyChildrenNum:

• It is the actual integer variable used in the code to store the threshold value.
• It is used in the FGeometryCollectionPhysicsProxy::InitializeBodiesPT function to check if the number of rigid children in a cluster exceeds the specified threshold.
• When the threshold is exceeded and the feature is enabled (ReportTooManyChildrenNum >= 0), a warning message is logged using UE_LOG.
• Developers should use this variable in conjunction with p.ReportTooManyChildrenNum to fine-tune their geometry collection’s performance and identify potential issues with cluster hierarchy.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/GeometryCollectionPhysicsProxy.cpp:1037

Scope: file

Source code excerpt:

int32 ReportTooManyChildrenNum = -1;
FAutoConsoleVariableRef CVarReportTooManyChildrenNum(TEXT("p.ReportTooManyChildrenNum"), ReportTooManyChildrenNum, TEXT("Issue warning if more than this many children exist in a single cluster"));

void FGeometryCollectionPhysicsProxy::CreateNonClusteredParticles(Chaos::FPBDRigidsSolver* RigidsSolver, const FGeometryCollection& RestCollection, const FGeometryDynamicCollection& DynamicCollection)
{
	LLM_SCOPE_BYNAME(TEXT("Physics/NonClusteredParticles"));
	const TManagedArray<bool>& SimulatableParticles = DynamicCollection.SimulatableParticles;
	

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/GeometryCollectionPhysicsProxy.cpp:1036

Scope: file

Source code excerpt:

}

int32 ReportTooManyChildrenNum = -1;
FAutoConsoleVariableRef CVarReportTooManyChildrenNum(TEXT("p.ReportTooManyChildrenNum"), ReportTooManyChildrenNum, TEXT("Issue warning if more than this many children exist in a single cluster"));

void FGeometryCollectionPhysicsProxy::CreateNonClusteredParticles(Chaos::FPBDRigidsSolver* RigidsSolver, const FGeometryCollection& RestCollection, const FGeometryDynamicCollection& DynamicCollection)
{
	LLM_SCOPE_BYNAME(TEXT("Physics/NonClusteredParticles"));
	const TManagedArray<bool>& SimulatableParticles = DynamicCollection.SimulatableParticles;
	

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/GeometryCollectionPhysicsProxy.cpp:1474

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::InitializeBodiesPT

Source code excerpt:

				if (ParticleIndex != INDEX_NONE && SolverParticleHandles[ParticleIndex] == nullptr)
				{
					if (ReportTooManyChildrenNum >= 0 && RigidChildren.Num() > ReportTooManyChildrenNum)
					{
						UE_LOG(LogChaos, Warning, TEXT("Too many children (%d) in a single cluster:%s"), 
							RigidChildren.Num(), *Parameters.Name);
					}

					Chaos::FClusterCreationParameters CreationParameters;