p.Chaos.Collision.Manifold.CapsuleDeepPenetrationFraction

p.Chaos.Collision.Manifold.CapsuleDeepPenetrationFraction

#Overview

name: p.Chaos.Collision.Manifold.CapsuleDeepPenetrationFraction

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.Manifold.CapsuleDeepPenetrationFraction is to define a threshold for detecting deep penetration between two capsules in collision detection within the Chaos physics system of Unreal Engine 5. This variable is used to determine when to generate a multi-point manifold for more accurate collision handling.

This setting variable is primarily used in the Chaos physics subsystem, specifically in the collision detection and manifold generation modules. It’s part of the Experimental Chaos namespace, indicating that it’s used in the newer Chaos physics engine.

The value of this variable is set to 0.05f by default, but it can be modified at runtime through the console variable system. It’s associated with the C++ variable Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction, which directly stores the value used in the code.

This variable interacts closely with other collision-related variables, such as Chaos_Collision_Manifold_CapsuleRadialContactFraction and Chaos_Collision_Manifold_CapsuleAxisAlignedThreshold. These variables work together to define the behavior of capsule collision detection and manifold generation.

Developers must be aware that this variable significantly impacts the precision and performance of capsule-capsule and sphere-capsule collision detection. A lower value will result in more frequent generation of multi-point manifolds, potentially increasing accuracy but also computational cost.

Best practices when using this variable include:

  1. Only modify it if you’re experiencing specific issues with capsule collision behavior.
  2. Test thoroughly after any modifications, as it can affect both collision accuracy and performance.
  3. Consider the trade-off between collision accuracy and performance when adjusting this value.

Regarding the associated variable Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction:

This is the actual C++ variable that stores the value used in the collision detection code. It’s initialized with the same default value (0.05f) as the console variable. The console variable system allows this value to be modified at runtime, providing flexibility for testing and tuning.

The variable is used in multiple places within the collision detection code, specifically in ConstructSphereCapsuleOneShotManifold and ConstructCapsuleCapsuleOneShotManifold functions. In these functions, it’s used to determine if the penetration depth between colliding objects is deep enough to warrant generating additional contact points.

Developers should note that changes to this variable will affect both sphere-capsule and capsule-capsule collisions. When modifying this value, it’s important to test both types of collisions to ensure desired behavior across all relevant scenarios.

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	// When two capsules penetrate by more than this fraction of the radius, generate a multi-point manifold
	FRealSingle Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction = 0.05f;
	FAutoConsoleVariableRef CVarChaos_Manifold_CapsuleDeepPenetrationFraction(TEXT("p.Chaos.Collision.Manifold.CapsuleDeepPenetrationFraction"), Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction, TEXT(""));

	// When two capsule lie on top of each other in an X, the extra manifold points are this fraction of the radius from the primary contact point
	FRealSingle Chaos_Collision_Manifold_CapsuleRadialContactFraction = 0.25f;
	FAutoConsoleVariableRef CVarChaos_Manifold_CapsuleRadialContactFraction(TEXT("p.Chaos.Collision.Manifold.CapsuleRadialContactFraction"), Chaos_Collision_Manifold_CapsuleRadialContactFraction, TEXT(""));

	// When a capsule-convex contact has points closer together than this fraction of radius, ignore one of the contacts

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/CollisionOneShotManifolds.cpp:29

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	// When two capsules penetrate by more than this fraction of the radius, generate a multi-point manifold
	FRealSingle Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction = 0.05f;
	FAutoConsoleVariableRef CVarChaos_Manifold_CapsuleDeepPenetrationFraction(TEXT("p.Chaos.Collision.Manifold.CapsuleDeepPenetrationFraction"), Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction, TEXT(""));

	// When two capsule lie on top of each other in an X, the extra manifold points are this fraction of the radius from the primary contact point
	FRealSingle Chaos_Collision_Manifold_CapsuleRadialContactFraction = 0.25f;
	FAutoConsoleVariableRef CVarChaos_Manifold_CapsuleRadialContactFraction(TEXT("p.Chaos.Collision.Manifold.CapsuleRadialContactFraction"), Chaos_Collision_Manifold_CapsuleRadialContactFraction, TEXT(""));

	// When a capsule-convex contact has points closer together than this fraction of radius, ignore one of the contacts

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/CollisionOneShotManifoldsMiscShapes.cpp:23

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	extern FRealSingle Chaos_Collision_Manifold_SphereCapsuleSizeThreshold;
	extern FRealSingle Chaos_Collision_Manifold_CapsuleAxisAlignedThreshold;
	extern FRealSingle Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction;
	extern FRealSingle Chaos_Collision_Manifold_CapsuleRadialContactFraction;

	namespace Collisions
	{

		void ConstructSphereSphereOneShotManifold(

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/CollisionOneShotManifoldsMiscShapes.cpp:156

Scope (from outer to inner):

file
namespace    Chaos
namespace    Collisions
function     void ConstructSphereCapsuleOneShotManifold

Source code excerpt:

					// Note: we only consider the radius of the dynamic object(s) when deciding what "deep" means because the extra contacts are only
					// to prevent excessive rotation from the single contact we have so far, and only the dynamic objects will rotate.
					const FReal DeepRadiusFraction = Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction;
					const bool bIsDeep = NearPhi < -DeepRadiusFraction * Capsule.GetRadius();
					if (!bIsDeep)
					{
						return;
					}

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/CollisionOneShotManifoldsMiscShapes.cpp:433

Scope (from outer to inner):

file
namespace    Chaos
namespace    Collisions
function     void ConstructCapsuleCapsuleOneShotManifold

Source code excerpt:

			// to prevent excessive rotation from the single contact we have so far, and only the dynamic objects will rotate.
			const FReal AxisDotMinimum = Chaos_Collision_Manifold_CapsuleAxisAlignedThreshold;
			const FReal DeepRadiusFraction = Chaos_Collision_Manifold_CapsuleDeepPenetrationFraction;
			const FReal MinDynamicRadius = FMath::Min(ADynamicRadius, BDynamicRadius);
			const bool bAreAligned = ADotB > AxisDotMinimum;
			const bool bIsDeep = ClosestPhi < -DeepRadiusFraction * MinDynamicRadius;
			if (!bAreAligned && !bIsDeep)
			{
				return;