p.ClusterDistanceThreshold

p.ClusterDistanceThreshold

#Overview

name: p.ClusterDistanceThreshold

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.ClusterDistanceThreshold is to define the proximity threshold for cluster children to break off from their parent cluster during collision events in the Chaos physics system of Unreal Engine 5.

This setting variable is primarily used in the Chaos physics module, which is part of Unreal Engine’s experimental physics system. It’s specifically utilized in the rigid body clustering functionality, which is responsible for managing the behavior of clustered rigid bodies during simulations.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. The initial value is set to 100.0f, but this can be changed dynamically.

The p.ClusterDistanceThreshold interacts closely with its associated variable ClusterDistanceThreshold. They share the same value, with p.ClusterDistanceThreshold being the console variable name and ClusterDistanceThreshold being the actual C++ variable used in the code.

Developers must be aware that this variable directly affects the break-off behavior of clustered rigid bodies. A lower value will cause cluster children to break off more easily, while a higher value will keep them together for longer during collisions.

Best practices when using this variable include:

  1. Adjusting it based on the scale and nature of your physics simulations.
  2. Testing different values to find the right balance between realistic break-off behavior and performance.
  3. Considering the impact on gameplay and visual fidelity when modifying this value.

Regarding the associated variable ClusterDistanceThreshold:

The purpose of ClusterDistanceThreshold is to serve as the actual C++ variable that stores the distance threshold value used in the clustering calculations.

It is used directly in the Chaos physics system, specifically in the FRigidClustering::ComputeStrainFromCollision function. This function is responsible for calculating the strain on clustered rigid bodies during collisions.

The value of ClusterDistanceThreshold is set by the p.ClusterDistanceThreshold console variable, allowing for runtime adjustments.

This variable interacts with the FAABB3 (Axis-Aligned Bounding Box) class to create a thickened bounding box around contact points during collision calculations.

Developers should be aware that changes to ClusterDistanceThreshold will directly affect the collision response and break-off behavior of clustered rigid bodies in the simulation.

Best practices for using ClusterDistanceThreshold include:

  1. Ensuring that its value is appropriate for the scale of your physics objects.
  2. Monitoring performance impact when adjusting this value, as it can affect the number of collision checks performed.
  3. Considering the visual and gameplay implications of different threshold values in your specific use case.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	//
	FRealSingle ClusterDistanceThreshold = 100.f;
	FAutoConsoleVariableRef CVarClusterDistance(TEXT("p.ClusterDistanceThreshold"), ClusterDistanceThreshold, TEXT("How close a cluster child must be to a contact to break off"));

	int32 UseConnectivity = 1;
	FAutoConsoleVariableRef CVarUseConnectivity(TEXT("p.UseConnectivity"), UseConnectivity, TEXT("Whether to use connectivity graph when breaking up clusters"));

	bool bCheckForInterclusterEdgesOnRelease = true;
	FAutoConsoleVariableRef CVarCheckForInterclusterEdgesOnRelease(TEXT("p.Chaos.CheckForInterclusterEdgesOnRelease"), bCheckForInterclusterEdgesOnRelease, TEXT("Whether to check for intercluster edges when removing a child from its parent cluster so that we can add the particle back into a cluster union."));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	//  Connectivity PVar
	//
	FRealSingle ClusterDistanceThreshold = 100.f;
	FAutoConsoleVariableRef CVarClusterDistance(TEXT("p.ClusterDistanceThreshold"), ClusterDistanceThreshold, TEXT("How close a cluster child must be to a contact to break off"));

	int32 UseConnectivity = 1;
	FAutoConsoleVariableRef CVarUseConnectivity(TEXT("p.UseConnectivity"), UseConnectivity, TEXT("Whether to use connectivity graph when breaking up clusters"));

	bool bCheckForInterclusterEdgesOnRelease = true;
	FAutoConsoleVariableRef CVarCheckForInterclusterEdgesOnRelease(TEXT("p.Chaos.CheckForInterclusterEdgesOnRelease"), bCheckForInterclusterEdgesOnRelease, TEXT("Whether to check for intercluster edges when removing a child from its parent cluster so that we can add the particle back into a cluster union."));

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FRigidClustering::ComputeStrainFromCollision
lambda-function

Source code excerpt:

						const FVec3 ContactLocationClusterLocal = WorldToClusterTM.InverseTransformPosition(ContactWorldLocation);
						FAABB3 ContactBox(ContactLocationClusterLocal, ContactLocationClusterLocal);
						ContactBox.Thicken(ClusterDistanceThreshold);
						if (Cluster->GetChildrenSpatial())
						{
							// todo(chaos): FindAllIntersectingChildren may return an unfiltered list of children ( when num children is under a certain threshold )   
							const TArray<FPBDRigidParticleHandle*> Intersections = Cluster->GetChildrenSpatial()->FindAllIntersectingChildren(ContactBox);
							for (FPBDRigidParticleHandle* Child : Intersections)
							{