p.Chaos.Collision.Manifold.MinFaceSearchDistance

p.Chaos.Collision.Manifold.MinFaceSearchDistance

#Overview

name: p.Chaos.Collision.Manifold.MinFaceSearchDistance

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Collision.Manifold.MinFaceSearchDistance is to set a minimum search distance for face detection in collision manifolds within the Chaos physics system of Unreal Engine 5. This setting is primarily used in the collision detection and resolution process, specifically for convex shape collisions.

This setting variable is utilized by the Chaos physics subsystem, which is part of Unreal Engine’s experimental features. It’s specifically used in the collision detection module, as evidenced by its location in the “CollisionOneShotManifolds.cpp” file.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. Its default value is 1.0f.

The associated variable Chaos_Collision_Manifold_MinFaceSearchDistance directly interacts with p.Chaos.Collision.Manifold.MinFaceSearchDistance. They share the same value and are used interchangeably in the code.

Developers should be aware that this variable affects the precision and performance of collision detection, particularly in edge cases where objects are very close to each other or touching. Setting this value too low might lead to missed collisions, while setting it too high could result in false positives or performance issues.

Best practices when using this variable include:

  1. Adjusting it carefully based on the scale and nature of your game’s physics interactions.
  2. Testing thoroughly with different values to find the optimal balance between accuracy and performance.
  3. Considering the relationship between this variable and other collision-related settings in the Chaos system.

Regarding the associated variable Chaos_Collision_Manifold_MinFaceSearchDistance:

The purpose of this variable is the same as p.Chaos.Collision.Manifold.MinFaceSearchDistance, serving as its internal representation within the Chaos physics system.

It’s used directly in the collision detection algorithms, specifically in the SelectContactPlane functions for both regular and scaled convex objects.

The value is set through the console variable system and is used as a fallback minimum distance when the actual distance between objects is very small or zero.

This variable interacts closely with other collision parameters, such as InMaxDistance, to determine the appropriate search distance for contact points.

Developers should be aware that this variable directly affects the behavior of the collision system at a low level. Changes to this value can have significant impacts on both the accuracy and performance of collision detection.

Best practices include:

  1. Monitoring this variable’s value during physics simulations to ensure it’s behaving as expected.
  2. Considering this variable when debugging collision issues, especially those related to very close or touching objects.
  3. Understanding that this variable may need to be adjusted based on the scale of objects in your game world.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	FRealSingle Chaos_Collision_Manifold_MinFaceSearchDistance = 1.0f;
	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;

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarChaosCollisioConvexManifoldCullDistanceMarginMultiplier(TEXT("p.Chaos.Collision.Manifold.CullDistanceMarginMultiplier"), Chaos_Collision_Manifold_CullDistanceMarginMultiplier, TEXT(""));

	FRealSingle Chaos_Collision_Manifold_MinFaceSearchDistance = 1.0f;
	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;

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Collisions
function     int32 SelectContactPlane

Source code excerpt:

			// Handle InMaxDistance = 0. We expect that the X is actually on the surface in this case, so the search distance just needs to be some reasonable tolerance.
			// @todo(chaos): this should probable be dependent on the size of the objects...
			const FReal MinFaceSearchDistance = Chaos_Collision_Manifold_MinFaceSearchDistance;
			const FReal MaxDistance = FMath::Max(InMaxDistance, MinFaceSearchDistance);

			int32 BestPlaneIndex = INDEX_NONE;
			FReal BestPlaneDot = 1.0f;
			{
				int32 PlaneIndices[3] = {INDEX_NONE, INDEX_NONE, INDEX_NONE};

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Collisions
function     int32 SelectContactPlane<TImplicitObjectScaled<FConvex>>

Source code excerpt:

			// Handle InMaxDistance = 0. We expect that the X is actually on the surface in this case, so the search distance just needs to be some reasonable tolerance.
			// @todo(chaos): this should probable be dependent on the size of the objects...
			const FConvexReal MinFaceSearchDistance = Chaos_Collision_Manifold_MinFaceSearchDistance;
			const FConvexReal MaxDistance = FMath::Max(FConvexReal(InMaxDistance), MinFaceSearchDistance);

			// LWC_TODO: Precision Loss
			// Scale precision is ok as long as we only support large positions and not large sizes...
			// N precision is ok with floats (normalized)
			// X precision is ok as long as we don't try to find the exact separation of objects that are separated by LWC distances