p.Chaos.Collision.GJKEpsilon

p.Chaos.Collision.GJKEpsilon

#Overview

name: p.Chaos.Collision.GJKEpsilon

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.Collision.GJKEpsilon is to set the tolerance value for the Gilbert-Johnson-Keerthi (GJK) algorithm used in collision detection within Unreal Engine’s Chaos physics system. This variable defines the precision of the GJK algorithm, which is crucial for determining when objects are in contact or penetrating each other.

The Chaos physics system, which is part of Unreal Engine’s experimental features, relies on this setting variable. Specifically, it is used in the collision detection subsystem for accurate contact point calculations.

The value of this variable is initially set to 1.e-6f (0.000001) in the C++ code, but it can be modified at runtime through the console variable system (CVarChaos_Collision_GJKEpsilon).

This variable interacts closely with another variable called Chaos_Collision_EPAEpsilon, which is used for the Expanding Polytope Algorithm (EPA), another part of the collision detection process.

Developers must be aware that this variable directly affects the precision of collision detection. A smaller value will result in more accurate collisions but may increase computational cost, while a larger value might improve performance at the cost of accuracy.

Best practices when using this variable include:

  1. Only modify it if you understand the implications on collision detection accuracy and performance.
  2. Test thoroughly after any changes to ensure desired collision behavior is maintained.
  3. Consider the scale of your game world when adjusting this value, as very large or very small worlds might require different epsilon values.

Regarding the associated variable Chaos_Collision_GJKEpsilon:

The purpose of Chaos_Collision_GJKEpsilon is the same as p.Chaos.Collision.GJKEpsilon. It’s the actual variable that stores the GJK epsilon value used in the collision detection calculations.

This variable is used directly in the Chaos physics subsystem, particularly in functions related to contact point calculation and GJK penetration tests.

The value of Chaos_Collision_GJKEpsilon is set through the console variable p.Chaos.Collision.GJKEpsilon, allowing for runtime modification.

It interacts closely with Chaos_Collision_EPAEpsilon, as both are often used together in collision detection algorithms.

Developers should be aware that this is the actual variable used in calculations, while p.Chaos.Collision.GJKEpsilon is the console variable used to modify it.

Best practices include:

  1. Treat this variable as read-only in most cases, modifying it through the console variable instead.
  2. When debugging collision issues, consider logging or watching this variable to ensure it has the expected value.
  3. Remember that changes to this variable will affect all collision detection using the GJK algorithm in the Chaos system.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FRealSingle Chaos_Collision_GJKEpsilon = 1.e-6f;
	FRealSingle Chaos_Collision_EPAEpsilon = 1.e-6f;
	FAutoConsoleVariableRef CVarChaos_Collision_GJKEpsilon(TEXT("p.Chaos.Collision.GJKEpsilon"), Chaos_Collision_GJKEpsilon, TEXT(""));
	FAutoConsoleVariableRef CVarChaos_Collision_EPAEpsilon(TEXT("p.Chaos.Collision.EPAEpsilon"), Chaos_Collision_EPAEpsilon, TEXT(""));

	// Whether to prune spurious edge contacts in trimesh and heighfield contacts (pretty much essential)
	bool bChaos_Collision_EnableEdgePrune = true;
	FRealSingle Chaos_Collision_EdgePrunePlaneDistance = 3.0;
	FAutoConsoleVariableRef CVarChaos_Collision_EnableEdgePrune(TEXT("p.Chaos.Collision.EnableEdgePrune"), bChaos_Collision_EnableEdgePrune, TEXT(""));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

namespace Chaos
{
	extern FRealSingle Chaos_Collision_GJKEpsilon;
	extern FRealSingle Chaos_Collision_EPAEpsilon;

	// Check whether the convex-triangle edge pair form part of the Minkowski Sum. Only edge pairs
	// that contribute to the Minkowki Sum surface need to be checked for separation. The inputs
	// are the convex normals for the two faces that share the convex edge, and the normal and
	// edge vector of the triangle.

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

Scope (from outer to inner):

file
namespace    Chaos::Private
function     bool ConvexTriangleContactPoint

Source code excerpt:

		FReal Penetration;
		FVec3 ConvexClosest, TriangleClosest, ConvexNormal;
		const FReal GJKEpsilon = Chaos_Collision_GJKEpsilon;
		const FReal EPAEpsilon = Chaos_Collision_EPAEpsilon;

		FVec3 InitialGJKDir = FVec3(1, 0, 0);

		const bool bHaveContact = GJKPenetrationSameSpace(
			GJKConvex,

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	// See GJKContactPointMargin for comments on why these matter
	// LWC_TODO: These needs to be a larger values for float builds (1.e-3f)
	FRealSingle Chaos_Collision_GJKEpsilon = 1.e-6f;
	FRealSingle Chaos_Collision_EPAEpsilon = 1.e-6f;
	FAutoConsoleVariableRef CVarChaos_Collision_GJKEpsilon(TEXT("p.Chaos.Collision.GJKEpsilon"), Chaos_Collision_GJKEpsilon, TEXT(""));
	FAutoConsoleVariableRef CVarChaos_Collision_EPAEpsilon(TEXT("p.Chaos.Collision.EPAEpsilon"), Chaos_Collision_EPAEpsilon, TEXT(""));

	// Whether to prune spurious edge contacts in trimesh and heighfield contacts (pretty much essential)
	bool bChaos_Collision_EnableEdgePrune = true;
	FRealSingle Chaos_Collision_EdgePrunePlaneDistance = 3.0;
	FAutoConsoleVariableRef CVarChaos_Collision_EnableEdgePrune(TEXT("p.Chaos.Collision.EnableEdgePrune"), bChaos_Collision_EnableEdgePrune, TEXT(""));

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Collisions
function     FContactPoint GJKContactPointMargin

Source code excerpt:

			// EPA Tolerance of about 1e-6 to avoid this in our test cases. It may need to be smaller.
			//const FReal Epsilon = 3.e-3f;	// original value for float implementation
			const FReal GJKEpsilon = Chaos_Collision_GJKEpsilon;
			const FReal EPAEpsilon = Chaos_Collision_EPAEpsilon;

			const TGJKCoreShape<GeometryA> AWithMargin(A, MarginA);
			const TGJKCoreShape<GeometryB> BWithMargin(B, MarginB);

			bool bHaveContact = false;

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    Collisions
function     FContactPoint GJKContactPointSameSpace

Source code excerpt:


			// GJK and EPA tolerances. See comments in GJKContactPointMargin
			const FReal GJKEpsilon = Chaos_Collision_GJKEpsilon;
			const FReal EPAEpsilon = Chaos_Collision_EPAEpsilon;

			bool bHaveContact = false;
			if (bChaos_Collision_UseGJK2)
			{
				bHaveContact = GJKPenetrationSameSpace2(A, B, Penetration, ClosestA, ClosestB, Normal, VertexIndexA, VertexIndexB, OutMaxMarginDelta, InitialGJKDir, GJKEpsilon, EPAEpsilon);