p.Chaos.Collision.CullDistanceReferenceSize

p.Chaos.Collision.CullDistanceReferenceSize

#Overview

name: p.Chaos.Collision.CullDistanceReferenceSize

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.Collision.CullDistanceReferenceSize is to define a reference size for calculating the cull distance scale in the Chaos physics engine’s collision system. This setting is part of Unreal Engine 5’s physics simulation, specifically the Chaos physics solver.

This setting variable is primarily used in the Chaos physics module, which is part of Unreal Engine’s experimental features. It’s utilized in the collision detection system, particularly in the mid-phase collision checks.

The value of this variable is set through the Unreal Engine’s console variable system (CVars). It’s initialized with a default value of 0.01f, which corresponds to 100cm in the game world.

The associated variable Chaos_Collision_CullDistanceScaleInverseSize directly interacts with p.Chaos.Collision.CullDistanceReferenceSize. They share the same value, with Chaos_Collision_CullDistanceScaleInverseSize being the actual variable used in the code.

Developers must be aware that this variable affects the culling distance for collision checks. A smaller value will result in a larger culling distance, which might improve performance but could potentially miss some collisions. Conversely, a larger value will decrease the culling distance, potentially improving accuracy but at the cost of performance.

Best practices when using this variable include:

  1. Carefully adjusting it based on the scale of your game world and objects.
  2. Testing thoroughly to ensure a good balance between performance and collision accuracy.
  3. Considering the impact on both small and large objects in your game.

Regarding the associated variable Chaos_Collision_CullDistanceScaleInverseSize:

The purpose of Chaos_Collision_CullDistanceScaleInverseSize is to store the inverse of the reference size for cull distance calculations. It’s used directly in the code to compute the cull distance scale for collision checks.

This variable is used in the Chaos physics module, specifically in the ParticlePairMidPhase component of the collision system.

Its value is set through the console variable p.Chaos.Collision.CullDistanceReferenceSize and initialized to 0.01f (representing 100cm).

It interacts closely with other variables like Chaos_Collision_MinCullDistanceScale to determine the final cull distance scale.

Developers should be aware that this variable represents the inverse of the reference size, so smaller values result in larger cull distances.

Best practices include:

  1. Understanding its relationship with p.Chaos.Collision.CullDistanceReferenceSize.
  2. Considering its impact on both performance and accuracy when adjusting.
  3. Testing with various object sizes to ensure appropriate collision behavior across 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/Collision/ParticlePairMidPhase.cpp:52

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;

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

	namespace CVars
	{
		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;

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FParticlePairMidPhase::InitThresholds

Source code excerpt:

		// Currently this should not happen, but it is not explicitly ensured by the way the thresholds and CullDistanceScale are calculated.
		// @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);