p.Clustering.ParticleReleaseThrottlingMinCount

p.Clustering.ParticleReleaseThrottlingMinCount

#Overview

name: p.Clustering.ParticleReleaseThrottlingMinCount

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

• type: Var
• help: Minimum number of active geometry collection to reach before clustering start to disable a percentage of the released particle per cluster

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Clustering.ParticleReleaseThrottlingMinCount is to control the throttling of particle release in the Chaos physics engine’s clustering system. Specifically, it sets the minimum number of active geometry collections that must be present before the system starts to disable a percentage of released particles per cluster.

This setting variable is primarily used in the Chaos physics engine, which is part of Unreal Engine’s experimental physics simulation system. It’s utilized within the PBDRigidClustering module, which handles the physics behavior of clustered rigid bodies.

The value of this variable is set through the Unreal Engine’s console variable system, as evidenced by the FAutoConsoleVariableRef declaration. This allows the value to be adjusted at runtime or through configuration files.

This variable interacts closely with another variable, ClusteringParticleReleaseThrottlingMaxCount. Together, these variables define a range for controlling particle release throttling based on the number of active geometry collections.

Developers should be aware that this variable is part of an experimental feature and its behavior might change in future engine versions. It’s also important to note that this variable uses INDEX_NONE as its default value, which typically indicates that the feature is disabled by default.

Best practices when using this variable include:

1. Carefully tuning it alongside ClusteringParticleReleaseThrottlingMaxCount to achieve the desired performance and visual results.
2. Monitoring performance impacts when adjusting this value, as it can affect the number of active particles in the simulation.
3. Using it in conjunction with other Chaos physics settings for optimal results.

Regarding the associated variable ClusteringParticleReleaseThrottlingMinCount:

This is the actual integer variable that stores the value set by p.Clustering.ParticleReleaseThrottlingMinCount. It’s used in the implementation to determine when to start throttling particle release.

The purpose of this variable is the same as p.Clustering.ParticleReleaseThrottlingMinCount - it defines the minimum number of active geometry collections before particle release throttling begins.

It’s used in the Chaos physics engine, specifically in the PBDRigidClustering module.

The value is set through the console variable system and can be accessed directly in the C++ code.

It interacts with ClusteringParticleReleaseThrottlingMaxCount to define the range for particle release throttling.

Developers should be aware that this variable is checked against INDEX_NONE to determine if the feature is enabled.

Best practices include using this variable in performance-critical code paths and ensuring it’s properly initialized before use.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	int32 ClusteringParticleReleaseThrottlingMinCount = INDEX_NONE;
	FAutoConsoleVariableRef CVarClusteringParticleReleaseThrottlingMinCount(TEXT("p.Clustering.ParticleReleaseThrottlingMinCount"), ClusteringParticleReleaseThrottlingMinCount, TEXT("Minimum number of active geometry collection to reach before clustering start to disable a percentage of the released particle per cluster"));

	int32 ClusteringParticleReleaseThrottlingMaxCount = INDEX_NONE;
	FAutoConsoleVariableRef CVarClusteringParticleReleaseThrottlingMaxCount(TEXT("p.Clustering.ParticleReleaseThrottlingMaxCount"), ClusteringParticleReleaseThrottlingMaxCount, TEXT("Maximum number of active geometry collection to reach before all released clustering disable all released particle instantly"));

	namespace CVars
	{

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarRestoreBreakingMomentumPercent(TEXT("p.RestoreBreakingMomentumPercent"), RestoreBreakingMomentumPercent, TEXT("When a rigid cluster is broken, objects that its in contact with will receive an impulse to restore this percent of their momentum prior to the break."));

	int32 ClusteringParticleReleaseThrottlingMinCount = INDEX_NONE;
	FAutoConsoleVariableRef CVarClusteringParticleReleaseThrottlingMinCount(TEXT("p.Clustering.ParticleReleaseThrottlingMinCount"), ClusteringParticleReleaseThrottlingMinCount, TEXT("Minimum number of active geometry collection to reach before clustering start to disable a percentage of the released particle per cluster"));

	int32 ClusteringParticleReleaseThrottlingMaxCount = INDEX_NONE;
	FAutoConsoleVariableRef CVarClusteringParticleReleaseThrottlingMaxCount(TEXT("p.Clustering.ParticleReleaseThrottlingMaxCount"), ClusteringParticleReleaseThrottlingMaxCount, TEXT("Maximum number of active geometry collection to reach before all released clustering disable all released particle instantly"));

	namespace CVars
	{

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    anonymous
function     bool CVarShouldThrottleParticleRelease

Source code excerpt:

		bool CVarShouldThrottleParticleRelease()
		{
			return (ClusteringParticleReleaseThrottlingMinCount >= 0 && ClusteringParticleReleaseThrottlingMaxCount >= 0);
		}

		// compute a ratio (between 0 and 1) of released particles to release
		float GetRatioOfReleasedParticlesToDisable(const FRigidClustering::FRigidEvolution& Evolution)
		{
			const FPBDRigidsSOAs& ParticleStructures = Evolution.GetParticles();

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    anonymous
function     float GetRatioOfReleasedParticlesToDisable

Source code excerpt:

			NumActiveParticles += ParticleStructures.GetDynamicGeometryCollectionArray().Num();

			const int32 Range = FMath::Max(0, (ClusteringParticleReleaseThrottlingMaxCount - ClusteringParticleReleaseThrottlingMinCount));
			const int32 OverMinCount = FMath::Max(0, (NumActiveParticles - ClusteringParticleReleaseThrottlingMinCount));

			if (Range > 0)
			{
				// clamp to 1, as OverMinCount can get larger than Range
				return FMath::Min(1.f, ((float)OverMinCount / (float)Range));
			}