p.Chaos.Collision.Manifold.ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance

p.Chaos.Collision.Manifold.ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance

#Overview

name: p.Chaos.Collision.Manifold.ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance

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

• type: Var
• help: If enabled, if one shot manifold hits edge/edge case, we will force a cull distance of zero. That means edge/edge contacts will be thrown out if separated at all. Only applies to Convex/Convex oneshot impl.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Collision.Manifold.ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance is to control the behavior of edge-edge collision detection in the Chaos physics system of Unreal Engine 5. Specifically, it forces a cull distance of zero for edge-edge cases in one-shot manifold collision detection.

This setting variable is primarily used by the Chaos physics system, which is part of Unreal Engine’s experimental physics framework. It’s specifically utilized in the collision detection subsystem, particularly for convex-convex and planar-convex-triangle collision scenarios.

The value of this variable is set through an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files. By default, it is set to false.

This variable interacts closely with the associated boolean variable ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance. They share the same value and are used interchangeably in the code.

Developers must be aware that when this variable is enabled (set to true), it significantly affects the behavior of edge-edge collision detection. Specifically:

1. For convex-convex collisions, if an edge-edge case is detected and the penetration depth (Phi) is positive, the collision will be ignored entirely.
2. For planar-convex-triangle collisions, the same behavior applies.

Best practices when using this variable include:

1. Use it cautiously, as it can potentially cause objects to pass through each other if not properly tuned.
2. Test thoroughly in various collision scenarios to ensure desired behavior.
3. Consider performance implications, as this may affect the overall physics simulation performance.

Regarding the associated variable ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance:

• It serves the same purpose as the console variable.
• It’s used directly in the collision detection code to check if edge-edge cases should be culled.
• Developers should treat it as equivalent to the console variable in terms of functionality and impact on the physics simulation.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	bool ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance = false;
	FAutoConsoleVariableRef CVarForceOneShotManifoldEdgeEdgeCaseZeroCullDistance(TEXT("p.Chaos.Collision.Manifold.ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance"), ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance,
	TEXT("If enabled, if one shot manifold hits edge/edge case, we will force a cull distance of zero. That means edge/edge contacts will be thrown out if separated at all. Only applies to Convex/Convex oneshot impl."));

	bool bChaos_Collision_EnableManifoldGJKReplace = false;
	bool bChaos_Collision_EnableManifoldGJKInject = false;
	FAutoConsoleVariableRef CVarChaos_Collision_EnableManifoldReplace(TEXT("p.Chaos.Collision.EnableManifoldGJKReplace"), bChaos_Collision_EnableManifoldGJKReplace, TEXT(""));
	FAutoConsoleVariableRef CVarChaos_Collision_EnableManifoldInject(TEXT("p.Chaos.Collision.EnableManifoldGJKInject"), bChaos_Collision_EnableManifoldGJKInject, TEXT(""));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarChaosCollisioConvexManifoldMinFaceSearchDistance(TEXT("p.Chaos.Collision.Manifold.MinFaceSearchDistance"), Chaos_Collision_Manifold_MinFaceSearchDistance, TEXT(""));

	bool ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance = false;
	FAutoConsoleVariableRef CVarForceOneShotManifoldEdgeEdgeCaseZeroCullDistance(TEXT("p.Chaos.Collision.Manifold.ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance"), ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance,
	TEXT("If enabled, if one shot manifold hits edge/edge case, we will force a cull distance of zero. That means edge/edge contacts will be thrown out if separated at all. Only applies to Convex/Convex oneshot impl."));

	bool bChaos_Collision_EnableManifoldGJKReplace = false;
	bool bChaos_Collision_EnableManifoldGJKInject = false;
	FAutoConsoleVariableRef CVarChaos_Collision_EnableManifoldReplace(TEXT("p.Chaos.Collision.EnableManifoldGJKReplace"), bChaos_Collision_EnableManifoldGJKReplace, TEXT(""));
	FAutoConsoleVariableRef CVarChaos_Collision_EnableManifoldInject(TEXT("p.Chaos.Collision.EnableManifoldGJKInject"), bChaos_Collision_EnableManifoldGJKInject, TEXT(""));

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Collisions
function     void ConstructConvexConvexOneShotManifold

Source code excerpt:

			if (!bIsPlaneContact)
			{
				if (ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance && GJKContactPoint.Phi > 0)
				{
					return;
				}

				// This is an edge-edge contact
				GJKContactPoint.ContactType = EContactPointType::EdgeEdge;

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Collisions
function     void ConstructPlanarConvexTriangleOneShotManifold

Source code excerpt:

			if (!bIsPlaneContact)
			{
				if (ForceOneShotManifoldEdgeEdgeCaseZeroCullDistance && GJKContactPoint.Phi > 0)
				{
					return;
				}

				// @todo(chaos): remove this if we ditch convex margins
				// We only need to find the best edges when we have convex margins enabled because then the GJK result