p.Chaos.CCD.EnableThresholdBoundsScale

p.Chaos.CCD.EnableThresholdBoundsScale

#Overview

name: p.Chaos.CCD.EnableThresholdBoundsScale

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.CCD.EnableThresholdBoundsScale is to control when Continuous Collision Detection (CCD) is activated in the Chaos physics system of Unreal Engine 5. It is used to determine the threshold at which CCD should be employed based on an object’s movement relative to its size.

This setting variable is primarily used in the Chaos physics subsystem, which is part of Unreal Engine’s experimental physics framework. It’s specifically utilized in the CCD utilities and collision constraint components of the Chaos system.

The value of this variable is set through a console variable (CVar) system, allowing it to be adjusted at runtime. It’s initialized with a default value of 0.4f in the CCDUtilities.cpp file.

The associated variable CCDEnableThresholdBoundsScale interacts directly with p.Chaos.CCD.EnableThresholdBoundsScale, as they share the same value. This associated variable is used in the actual implementation of the CCD logic.

Developers must be aware that:

  1. A value of 0 will always use CCD.
  2. Values less than 0 disable CCD entirely.
  3. For positive values, CCD is activated when an object’s position change exceeds its smallest bound’s extent multiplied by this scale factor.

Best practices when using this variable include:

  1. Carefully tuning the value to balance performance and collision accuracy.
  2. Ensuring it’s greater than the CCDAllowedDepthBoundsScale to prevent logical inconsistencies.
  3. Monitoring its impact on performance, especially in scenes with many dynamic objects.

Regarding the associated variable CCDEnableThresholdBoundsScale: Its purpose is identical to p.Chaos.CCD.EnableThresholdBoundsScale, serving as the actual variable used in the CCD calculations within the Chaos physics system. It’s used directly in the DeltaExceedsThreshold function to determine if CCD should be applied to an object’s movement. The same considerations and best practices apply to this variable as to the CVar it’s associated with.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/CCDUtilities.cpp:31

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// Determines when CCD is switched on
		FRealSingle CCDEnableThresholdBoundsScale = 0.4f;
		FAutoConsoleVariableRef  CVarCCDEnableThresholdBoundsScale(TEXT("p.Chaos.CCD.EnableThresholdBoundsScale"), CCDEnableThresholdBoundsScale , TEXT("CCD is used when object position is changing > smallest bound's extent * BoundsScale. 0 will always Use CCD. Values < 0 disables CCD."));

		// Determines how much penetration CCD leaves after rewinding to TOI. Must be less than CCDEnableThresholdBoundsScale
		Chaos::FRealSingle CCDAllowedDepthBoundsScale = 0.2f;
		FAutoConsoleVariableRef CVarCCDAllowedDepthBoundsScale(TEXT("p.Chaos.CCD.AllowedDepthBoundsScale"), CCDAllowedDepthBoundsScale, TEXT("When rolling back to TOI, allow (smallest bound's extent) * AllowedDepthBoundsScale, instead of rolling back to exact TOI w/ penetration = 0."));

		// When enabled, CCD TOI is set to the first contact which gets a depth of (CCDAllowedDepthBoundsScale * Object Size).

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/CCDUtilities.cpp:30

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:


		// Determines when CCD is switched on
		FRealSingle CCDEnableThresholdBoundsScale = 0.4f;
		FAutoConsoleVariableRef  CVarCCDEnableThresholdBoundsScale(TEXT("p.Chaos.CCD.EnableThresholdBoundsScale"), CCDEnableThresholdBoundsScale , TEXT("CCD is used when object position is changing > smallest bound's extent * BoundsScale. 0 will always Use CCD. Values < 0 disables CCD."));

		// Determines how much penetration CCD leaves after rewinding to TOI. Must be less than CCDEnableThresholdBoundsScale
		Chaos::FRealSingle CCDAllowedDepthBoundsScale = 0.2f;
		FAutoConsoleVariableRef CVarCCDAllowedDepthBoundsScale(TEXT("p.Chaos.CCD.AllowedDepthBoundsScale"), CCDAllowedDepthBoundsScale, TEXT("When rolling back to TOI, allow (smallest bound's extent) * AllowedDepthBoundsScale, instead of rolling back to exact TOI w/ penetration = 0."));

		// When enabled, CCD TOI is set to the first contact which gets a depth of (CCDAllowedDepthBoundsScale * Object Size).
		// When disabled, CCD will find the first contact, ignoreing the rest, and then fix the TOI to result in the specified depth.
		// This fixes the issue where (when disabled) we would set TOI to some value that would leave us penetrating another (later) object. This

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/CCDUtilities.cpp:1090

Scope (from outer to inner):

file
namespace    Chaos
function     bool FCCDHelpers::DeltaExceedsThreshold

Source code excerpt:

	bool FCCDHelpers::DeltaExceedsThreshold(const FVec3& AxisThreshold, const FVec3& DeltaX, const FQuat& R, FVec3& OutAbsLocalDelta, FVec3& OutAxisThresholdScaled, FVec3& OutAxisThresholdDiff)
	{
		if (CVars::CCDEnableThresholdBoundsScale < 0.f) { return false; }
		if (CVars::CCDEnableThresholdBoundsScale == 0.f) { return true; }

		// Get per-component absolute value of position delta in local space.
		// This is how much we've moved on each principal axis (but not which
		// direction on that axis that we've moved in).
		OutAbsLocalDelta = R.UnrotateVector(DeltaX).GetAbs();

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/CCDUtilities.cpp:1102

Scope (from outer to inner):

file
namespace    Chaos
function     bool FCCDHelpers::DeltaExceedsThreshold

Source code excerpt:

		// how much further we've moved on each axis than should be allowed by
		// the CCD bounds.
		OutAxisThresholdScaled = AxisThreshold * CVars::CCDEnableThresholdBoundsScale;
		OutAxisThresholdDiff = OutAbsLocalDelta - OutAxisThresholdScaled;

		// That is, if any element of ExtentsDiff is greater than zero, then that
		// means DeltaX has exceeded the scaled extents
		return OutAxisThresholdDiff.GetMax() > 0.f;
	}

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

	namespace CVars
	{
		extern FRealSingle CCDEnableThresholdBoundsScale;
		extern FRealSingle CCDAllowedDepthBoundsScale;
	}

	extern bool bChaos_Collision_EnableManifoldGJKInject;
	extern bool bChaos_Collision_EnableManifoldGJKReplace;

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDCollisionConstraint::InitCCDThreshold

Source code excerpt:

		// regular collision detection at T=1 (i.e., as if CCD is not enabled for this tick).
		// If this is zero, then we will always perform CCD rewind when we get a sweep hit.
		CCDEnablePenetration = MinBounds * CVars::CCDEnableThresholdBoundsScale;
		
		// If we have a CCD sweep hit above the enable penetration, we will rewind the body so
		// that the penetration depth CCDTargetPenetration (or less). A new contact manifold is then calculated.
		// NOTE: this can be zero but if it is we will get very poor behaviour because there will be
		// nothing for the contact resolution to do since we fully depenetrated in the CCD rewind.
		CCDTargetPenetration = MinBounds * CVars::CCDAllowedDepthBoundsScale;