p.Chaos.Collision.CCD.AllowClipping

p.Chaos.Collision.CCD.AllowClipping

#Overview

name: p.Chaos.Collision.CCD.AllowClipping

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Collision.CCD.AllowClipping is to control the behavior of Continuous Collision Detection (CCD) in the Chaos physics system of Unreal Engine 5. Specifically, it determines whether objects should be clipped at colliding positions when computation budgets are exhausted during CCD calculations.

This setting variable is primarily used in the Chaos physics subsystem, which is part of Unreal Engine’s experimental physics framework. It’s referenced in the CCDUtilities.cpp file, which handles CCD-related functionality.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized as true by default, but can be changed at runtime using console commands or through configuration files.

The associated variable bChaosCollisionCCDAllowClipping directly interacts with p.Chaos.Collision.CCD.AllowClipping. They share the same value and are used interchangeably in the code.

Developers must be aware that:

  1. Enabling this option (default) may result in visual velocity inconsistencies after CCD collisions, especially if ChaosCollisionCCDConstraintMaxProcessCount is set too low.
  2. Disabling this option might cause object tunneling, where fast-moving objects pass through other objects without detecting the collision.

Best practices when using this variable include:

  1. Keep it enabled (default) unless specific scenarios require it to be disabled.
  2. If disabled, ensure that ChaosCollisionCCDConstraintMaxProcessCount is set appropriately to minimize the risk of tunneling.
  3. Monitor performance and visual fidelity when adjusting this setting, as it can impact both.

Regarding the associated variable bChaosCollisionCCDAllowClipping:

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// NOTE: With this disabled, secondary collisions can be missed. When enabled, velocity will not be visually consistent after CCD collisions (if ChaosCollisionCCDConstraintMaxProcessCount is too low)
		bool bChaosCollisionCCDAllowClipping = true;
		FAutoConsoleVariableRef CVarChaosCollisionCCDAllowClipping(TEXT("p.Chaos.Collision.CCD.AllowClipping"), bChaosCollisionCCDAllowClipping, TEXT("This will clip the CCD object at colliding positions when computation budgets run out. Default is true. Turning this option off might cause tunneling."));

		// By default, we stop processing CCD contacts after a single CCD interaction
		// This will result in a visual velocity glitch when it happens, but usually this doesn't matter since the impact is very high energy anyway
		int32 ChaosCollisionCCDConstraintMaxProcessCount = 1;
		FAutoConsoleVariableRef CVarChaosCollisionCCDConstraintMaxProcessCount(TEXT("p.Chaos.Collision.CCD.ConstraintMaxProcessCount"), ChaosCollisionCCDConstraintMaxProcessCount, TEXT("The max number of times each constraint can be resolved when applying CCD constraints. Default is 2. The larger this number is, the more fully CCD constraints are resolved."));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:


		// NOTE: With this disabled, secondary collisions can be missed. When enabled, velocity will not be visually consistent after CCD collisions (if ChaosCollisionCCDConstraintMaxProcessCount is too low)
		bool bChaosCollisionCCDAllowClipping = true;
		FAutoConsoleVariableRef CVarChaosCollisionCCDAllowClipping(TEXT("p.Chaos.Collision.CCD.AllowClipping"), bChaosCollisionCCDAllowClipping, TEXT("This will clip the CCD object at colliding positions when computation budgets run out. Default is true. Turning this option off might cause tunneling."));

		// By default, we stop processing CCD contacts after a single CCD interaction
		// This will result in a visual velocity glitch when it happens, but usually this doesn't matter since the impact is very high energy anyway
		int32 ChaosCollisionCCDConstraintMaxProcessCount = 1;
		FAutoConsoleVariableRef CVarChaosCollisionCCDConstraintMaxProcessCount(TEXT("p.Chaos.Collision.CCD.ConstraintMaxProcessCount"), ChaosCollisionCCDConstraintMaxProcessCount, TEXT("The max number of times each constraint can be resolved when applying CCD constraints. Default is 2. The larger this number is, the more fully CCD constraints are resolved."));

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FCCDManager::ApplyIslandSweptConstraints

Source code excerpt:


			// If both particles are marked Done (due to clipping), continue
			if (CVars::bChaosCollisionCCDAllowClipping && (!CCDParticle0 || CCDParticle0->Done) && (!CCDParticle1 || CCDParticle1->Done))
			{
				ConstraintIndex++;
				continue;
			}
			
			ensure(CCDConstraint->ProcessedCount < CVars::ChaosCollisionCCDConstraintMaxProcessCount);

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FCCDManager::ApplyIslandSweptConstraints

Source code excerpt:

				* If collision detection is not perfect and does not give us all the secondary collision pairs, setting ChaosCollisionCCDConstraintMaxProcessCount to 1 will always prevent tunneling.
				*/ 
				if (CVars::bChaosCollisionCCDAllowClipping)
				{
					if (CCDParticle0)
					{
						if (CCDConstraint->FastMovingKinematicIndex != INDEX_NONE)
						{
							// @todo(chaos): can this just get the particle from the CCD constraint?

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FCCDManager::ApplyImpulse

Source code excerpt:

				const FReal TargetNormalV = -Restitution * NormalV;
				// If a particle is marked done, we treat it as static by setting InvM to 0. 
				const bool bInfMass0 = Rigid0 == nullptr || (CVars::bChaosCollisionCCDAllowClipping && CCDConstraint->Particle[0] && CCDConstraint->Particle[0]->Done);
				const bool bInfMass1 = Rigid1 == nullptr || (CVars::bChaosCollisionCCDAllowClipping && CCDConstraint->Particle[1] && CCDConstraint->Particle[1]->Done);
				const FReal InvM0 = bInfMass0 ? 0.f : Rigid0->InvM();
				const FReal InvM1 = bInfMass1 ? 0.f : Rigid1->InvM();
				const FVec3 Impulse = (TargetNormalV - NormalV) * Normal / (InvM0 + InvM1);
				if (InvM0 > 0.f)
				{
					Rigid0->SetV(Rigid0->GetV() + Impulse * InvM0);