p.Chaos.Collision.MinCullDistanceScale

p.Chaos.Collision.MinCullDistanceScale

#Overview

name: p.Chaos.Collision.MinCullDistanceScale

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

• type: Var
• help: ``

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Collision.MinCullDistanceScale is to set a minimum scale factor for the culling distance in the Chaos physics engine’s collision system. This variable is part of Unreal Engine 5’s Chaos physics simulation system, specifically within the collision detection subsystem.

The Chaos physics engine, which is part of Unreal Engine’s Experimental module, relies on this setting variable for optimizing collision detection. Based on the callsites, we can see that it’s used in the ParticlePairMidPhase.cpp file, which is responsible for handling mid-phase collision detection between particles.

The value of this variable is set through an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands. The default value is set to 1.0f.

This variable interacts closely with another variable named Chaos_Collision_CullDistanceScaleInverseSize. Together, these variables are used to calculate the culling distance scale for collision detection.

Developers must be aware that this variable sets a minimum threshold for the culling distance scale. Even if the calculated scale based on object sizes is smaller, the system will use this minimum value to ensure a certain level of accuracy in collision detection.

Best practices when using this variable include:

1. Adjusting it carefully, as it can affect both performance and collision accuracy.
2. Testing thoroughly after changes, as it impacts the entire collision system.
3. Considering the scale of your game world when setting this value.

Regarding the associated variable Chaos_Collision_MinCullDistanceScale:

This is the internal representation of the console variable. It’s initialized with the same default value (1.0f) and is used directly in the collision detection calculations.

In the InitThresholds function of FParticlePairMidPhase, we can see how this variable is used to ensure that the final CullDistanceScale is never smaller than MinCullDistanceScale. This helps maintain a minimum level of collision detection accuracy regardless of object sizes.

Developers should note that changes to p.Chaos.Collision.MinCullDistanceScale will directly affect this internal variable, and thus the collision detection behavior of the Chaos physics system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Collision/ParticlePairMidPhase.cpp:53

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		Chaos::FRealSingle Chaos_Collision_MinCullDistanceScale = 1.0f;
		FAutoConsoleVariableRef CVarChaos_Collision_CullDistanceReferenceSize(TEXT("p.Chaos.Collision.CullDistanceReferenceSize"), Chaos_Collision_CullDistanceScaleInverseSize, TEXT(""));
		FAutoConsoleVariableRef CVarChaos_Collision_MinCullDistanecScale(TEXT("p.Chaos.Collision.MinCullDistanceScale"), Chaos_Collision_MinCullDistanceScale, TEXT(""));

		// Whether we support the pre-flattened shape pair list which optimizes the common midphase case of collision between particles 
		// with only a small number implicit objects each. If so, how many shape pairs do we allow before switching to the generic version?
		bool bChaos_Collision_MidPhase_EnableShapePairs = true;
		int32 Chaos_Collision_MidPhase_MaxShapePairs = 100;
		FAutoConsoleVariableRef CVarChaos_Collision_EnableShapePairs(TEXT("p.Chaos.Collision.EnableShapePairs"), bChaos_Collision_MidPhase_EnableShapePairs, TEXT(""));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Collision/ParticlePairMidPhase.cpp:51

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

	{
		Chaos::FRealSingle Chaos_Collision_CullDistanceScaleInverseSize = 0.01f;	// 100cm
		Chaos::FRealSingle Chaos_Collision_MinCullDistanceScale = 1.0f;
		FAutoConsoleVariableRef CVarChaos_Collision_CullDistanceReferenceSize(TEXT("p.Chaos.Collision.CullDistanceReferenceSize"), Chaos_Collision_CullDistanceScaleInverseSize, TEXT(""));
		FAutoConsoleVariableRef CVarChaos_Collision_MinCullDistanecScale(TEXT("p.Chaos.Collision.MinCullDistanceScale"), Chaos_Collision_MinCullDistanceScale, TEXT(""));

		// Whether we support the pre-flattened shape pair list which optimizes the common midphase case of collision between particles 
		// with only a small number implicit objects each. If so, how many shape pairs do we allow before switching to the generic version?
		bool bChaos_Collision_MidPhase_EnableShapePairs = true;
		int32 Chaos_Collision_MidPhase_MaxShapePairs = 100;
		FAutoConsoleVariableRef CVarChaos_Collision_EnableShapePairs(TEXT("p.Chaos.Collision.EnableShapePairs"), bChaos_Collision_MidPhase_EnableShapePairs, TEXT(""));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Collision/ParticlePairMidPhase.cpp:930

Scope (from outer to inner):

file
namespace    Chaos
function     void FParticlePairMidPhase::InitThresholds

Source code excerpt:

		// @todo(chaos): Add a way to enforce a CullDistance big enough to support the reuse thresholds
		const FReal CullDistanceReferenceSizeInv = FReal(Chaos_Collision_CullDistanceScaleInverseSize);
		const FReal MinCullDistanceScale = FReal(Chaos_Collision_MinCullDistanceScale);
		const FReal MaxBoundsSize0 = (bIsDynamic0 && bIsBounded0) ? Particle0->LocalBounds().Extents().GetMax() : FReal(0);
		const FReal MaxBoundsSize1 = (bIsDynamic1 && bIsBounded1) ? Particle1->LocalBounds().Extents().GetMax() : FReal(0);
		const FReal CullDistanceScale0 = MaxBoundsSize0 * CullDistanceReferenceSizeInv;
		const FReal CullDistanceScale1 = MaxBoundsSize1 * CullDistanceReferenceSizeInv;
		CullDistanceScale = (FRealSingle)FMath::Max3(CullDistanceScale0, CullDistanceScale1, MinCullDistanceScale);
	}