p.chaos.clustering.breakonlystrained

p.chaos.clustering.breakonlystrained

#Overview

name: p.chaos.clustering.breakonlystrained

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.breakonlystrained is to control the behavior of cluster breaking in Unreal Engine’s Chaos physics system. Specifically, it determines whether the system should process only strained clusters for breaks or check all clusters.

This setting variable is primarily used in the Chaos physics subsystem, which is part of Unreal Engine’s experimental physics features. It is referenced in the PBDRigidClustering.cpp file, which suggests it’s related to Position Based Dynamics (PBD) and rigid body clustering.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands or configuration files. By default, it is set to 1 (enabled).

This variable interacts directly with GClusterBreakOnlyStrained, which is the actual integer variable used in the code logic. They share the same value, with p.chaos.clustering.breakonlystrained serving as the console-accessible name for the setting.

Developers must be aware that:

  1. When enabled (set to 1), only strained clusters are processed for breaks.
  2. When disabled (set to 0), all clusters are traversed and checked for potential breaks.

Best practices when using this variable include:

  1. Use it to optimize performance in scenes with many clusters by only processing strained ones.
  2. Consider disabling it (setting to 0) if you need more precise physics simulation at the cost of performance.
  3. Test your game with both settings to ensure it behaves correctly in all scenarios.

Regarding the associated variable GClusterBreakOnlyStrained:

The purpose of GClusterBreakOnlyStrained is to serve as the actual integer value used in the code logic for controlling cluster breaking behavior.

It is used directly in the Chaos physics subsystem, specifically in the FRigidClustering::AdvanceClustering function.

The value of this variable is set by the p.chaos.clustering.breakonlystrained console variable.

It interacts with the logic in the AdvanceClustering function to determine whether to process only strained clusters or all clusters for potential breaks.

Developers should be aware that this variable directly affects the performance and accuracy of the physics simulation for clustered objects.

Best practices for using GClusterBreakOnlyStrained include:

  1. Avoid modifying it directly in code; instead, use the p.chaos.clustering.breakonlystrained console variable.
  2. When profiling performance, pay attention to how different values affect both the physics simulation accuracy and performance.
  3. Consider exposing this setting to users or designers if fine-tuning of physics behavior is needed for different scenarios in your game.

#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:1652

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	static int32 GClusterBreakOnlyStrained = 1;
	FAutoConsoleVariableRef CVarBreakMode(TEXT("p.chaos.clustering.breakonlystrained"), GClusterBreakOnlyStrained, 
										  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"));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	}

	static int32 GClusterBreakOnlyStrained = 1;
	FAutoConsoleVariableRef CVarBreakMode(TEXT("p.chaos.clustering.breakonlystrained"), GClusterBreakOnlyStrained, 
										  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"));

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FRigidClustering::AdvanceClustering

Source code excerpt:

				// Call our breaking model
				// #TODO convert to visitor pattern to avoid TArray allocations above.
				if(GClusterBreakOnlyStrained == 1)
				{
					// call break model for each particle and only count the ones we breaks
					// some may strained parent may result in non breaking clusters if strain modifier has changed the strain values
					// todo(chaos): we should certainly try to have the strain modifier providing a list of those instead of preemptively process thenm to realise that there's nothoing to break
					int32 NumBreaks = 0;
					int32 LastProcessedIndex = 0;