p.ClusterSnapDistance

p.ClusterSnapDistance

#Overview

name: p.ClusterSnapDistance

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.ClusterSnapDistance is to define a threshold distance for snapping or cleaning collision particles in the Chaos physics system of Unreal Engine 5. This setting variable is primarily used in the rigid body clustering algorithm, which is part of the experimental Chaos physics module.

The Unreal Engine subsystem that relies on this setting variable is the Chaos physics system, specifically the rigid clustering algorithm within the experimental Chaos module.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. It is initialized with a default value of 1.0f.

The p.ClusterSnapDistance variable interacts directly with the ClusterSnapDistance variable. They share the same value, with p.ClusterSnapDistance being the console variable name and ClusterSnapDistance being the actual variable used in the code.

Developers must be aware that this variable affects the cleaning of collision particles in the clustering algorithm. It determines the distance threshold for considering particles as part of a cluster. Changing this value can impact the performance and accuracy of the physics simulation, particularly for clustered rigid bodies.

Best practices when using this variable include:

  1. Carefully adjusting the value based on the scale and requirements of your specific physics simulation.
  2. Testing different values to find the optimal balance between performance and accuracy.
  3. Considering the impact on both visual fidelity and computational performance when modifying this value.

Regarding the associated variable ClusterSnapDistance:

The purpose of ClusterSnapDistance is to store the actual value used in the physics calculations. It is directly linked to the p.ClusterSnapDistance console variable.

This variable is used within the Chaos physics system, specifically in the UpdateGeometry function of the rigid clustering algorithm.

The value of ClusterSnapDistance is set through the p.ClusterSnapDistance console variable, allowing for runtime modification.

ClusterSnapDistance is used in the CleanCollisionParticles function, which suggests it plays a role in optimizing or simplifying the collision geometry of clustered particles.

Developers should be aware that modifying ClusterSnapDistance will directly affect the behavior of the rigid clustering algorithm, potentially changing how particles are grouped and how collisions are calculated.

Best practices for using ClusterSnapDistance include:

  1. Ensuring that any modifications to p.ClusterSnapDistance are reflected in the behavior of the physics simulation as expected.
  2. Considering the scale of your game world when setting this value, as it represents a distance threshold.
  3. Monitoring performance and visual results when adjusting this value, as it can affect both the accuracy and efficiency of the physics simulation.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidClusteringAlgo.cpp:34

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	FRealSingle ClusterSnapDistance = 1.f;
	FAutoConsoleVariableRef CVarClusterSnapDistance2(TEXT("p.ClusterSnapDistance"), ClusterSnapDistance, TEXT(""));

	DECLARE_CYCLE_STAT(TEXT("TPBDRigidClustering<>::UpdateClusterMassProperties()"), STAT_UpdateClusterMassProperties, STATGROUP_Chaos);
	void UpdateClusterMassProperties(
		FPBDRigidClusteredParticleHandle* Parent,
		const TSet<FPBDRigidParticleHandle*>& Children)
	{

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarMinCleanedPointsBeforeRemovingInternals2(TEXT("p.MinCleanedPointsBeforeRemovingInternals"), MinCleanedPointsBeforeRemovingInternals, TEXT("If we only have this many clean points, don't bother removing internal points as the object is likely very small"));

	FRealSingle ClusterSnapDistance = 1.f;
	FAutoConsoleVariableRef CVarClusterSnapDistance2(TEXT("p.ClusterSnapDistance"), ClusterSnapDistance, TEXT(""));

	DECLARE_CYCLE_STAT(TEXT("TPBDRigidClustering<>::UpdateClusterMassProperties()"), STAT_UpdateClusterMassProperties, STATGROUP_Chaos);
	void UpdateClusterMassProperties(
		FPBDRigidClusteredParticleHandle* Parent,
		const TSet<FPBDRigidParticleHandle*>& Children)
	{

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidClusteringAlgo.cpp:357

Scope (from outer to inner):

file
namespace    Chaos
function     void UpdateGeometry

Source code excerpt:

			CleanedPoints =
				Parameters.bCleanCollisionParticles ?
				CleanCollisionParticles(OriginalPoints, ClusterSnapDistance) :
				OriginalPoints;
		}

		// ignore unions for now as we don't yet support deep copy of it
		// on the GT they are only used by clusters that aggregate their children shapes ( see GeometryCollectionPhysicsProxy.cpp )
		// by failing artificially this condition thmake sure we create a FImplicitObjectUnionClustered for this particle