p.Chaos.Clustering.PerAdvanceBreaksAllowed

p.Chaos.Clustering.PerAdvanceBreaksAllowed

#Overview

name: p.Chaos.Clustering.PerAdvanceBreaksAllowed

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 p.Chaos.Clustering.PerAdvanceBreaksAllowed is to control the number of breaks allowed to occur for each invocation of AdvanceClustering in the Chaos physics system of Unreal Engine 5.

This setting variable is primarily used in the Chaos physics subsystem, specifically in the rigid clustering module. It’s part of the experimental Chaos physics engine in Unreal Engine 5.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files.

The associated variable GPerAdvanceBreaksAllowed interacts directly with p.Chaos.Clustering.PerAdvanceBreaksAllowed. They share the same value, with GPerAdvanceBreaksAllowed being the actual integer variable used in the code.

Developers must be aware that this variable limits the number of breaks that can occur in a single frame during the clustering process. If the limit is reached, the process will stop and continue in the next frame.

Best practices when using this variable include:

  1. Setting it to a reasonable value to balance between physics accuracy and performance.
  2. Monitoring its impact on performance and adjusting as necessary.
  3. Considering the implications on gameplay if breaks are delayed to subsequent frames.

Regarding the associated variable GPerAdvanceBreaksAllowed:

The purpose of GPerAdvanceBreaksAllowed is to store the actual integer value used in the code to limit the number of breaks per advance in the clustering process.

It’s used directly in the AdvanceClustering function of the FRigidClustering class in the Chaos physics system.

The value of GPerAdvanceBreaksAllowed is set by the console variable system through p.Chaos.Clustering.PerAdvanceBreaksAllowed.

This variable interacts with the NumBreaks counter in the AdvanceClustering function. When NumBreaks reaches or exceeds GPerAdvanceBreaksAllowed, the clustering process for that frame stops.

Developers should be aware that modifying GPerAdvanceBreaksAllowed directly in the code is not recommended, as its value is controlled by the console variable system.

Best practices for GPerAdvanceBreaksAllowed include:

  1. Accessing its value through the console variable system rather than modifying it directly in code.
  2. Using it as a read-only variable in the clustering logic.
  3. Considering its impact on physics simulation when optimizing performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidClustering.cpp:1656

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	static int32 GPerAdvanceBreaksAllowed = TNumericLimits<int32>::Max();
	FAutoConsoleVariableRef CVarPerAdvanceBreaksAllowed(TEXT("p.Chaos.Clustering.PerAdvanceBreaksAllowed"), GPerAdvanceBreaksAllowed,
		TEXT("Number of breaks allowed to occur for each invokation of AdvanceClustering"));

	static int32 GPerAdvanceBreaksRescheduleLimit = TNumericLimits<int32>::Max();
	FAutoConsoleVariableRef CVarPerAdvanceBreaksRescheduleLimit(TEXT("p.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit"), GPerAdvanceBreaksRescheduleLimit,
		TEXT("Number of breaks allowed to be rescheduled for next frame if any "));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidClustering.cpp:1655

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

										  TEXT("If enabled we only process strained clusters for breaks, if disabled all clusters are traversed and checked"));

	static int32 GPerAdvanceBreaksAllowed = TNumericLimits<int32>::Max();
	FAutoConsoleVariableRef CVarPerAdvanceBreaksAllowed(TEXT("p.Chaos.Clustering.PerAdvanceBreaksAllowed"), GPerAdvanceBreaksAllowed,
		TEXT("Number of breaks allowed to occur for each invokation of AdvanceClustering"));

	static int32 GPerAdvanceBreaksRescheduleLimit = TNumericLimits<int32>::Max();
	FAutoConsoleVariableRef CVarPerAdvanceBreaksRescheduleLimit(TEXT("p.Chaos.Clustering.PerAdvanceBreaksRescheduleLimit"), GPerAdvanceBreaksRescheduleLimit,
		TEXT("Number of breaks allowed to be rescheduled for next frame if any "));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidClustering.cpp:1849

Scope (from outer to inner):

file
namespace    Chaos
function     void FRigidClustering::AdvanceClustering

Source code excerpt:

						{
							NumBreaks++;
							if (NumBreaks >= GPerAdvanceBreaksAllowed)
							{
								LastProcessedIndex = Index;
								break;
							}
						}
					}