p.Chaos.Collision.Manifold.MatchPositionTolerance

p.Chaos.Collision.Manifold.MatchPositionTolerance

#Overview

name: p.Chaos.Collision.Manifold.MatchPositionTolerance

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Collision.Manifold.MatchPositionTolerance is to set a tolerance value used in collision detection within the Chaos physics system of Unreal Engine 5. Specifically, it’s used to determine if two contact points are considered the same during collision manifold generation.

This setting variable is primarily used by the Chaos physics system, which is an experimental physics engine in Unreal Engine 5. It’s part of the collision detection and resolution subsystem within Chaos.

The value of this variable is set through an FAutoConsoleVariableRef, which means it can be adjusted at runtime through the console or configuration files. Its default value is 0.3f, representing a fraction of the object’s size.

The variable interacts closely with another variable named Chaos_Manifold_MatchPositionTolerance. They share the same value and are used together in the collision detection process.

Developers should be aware that this variable affects the precision of collision detection. A higher value will consider contact points farther apart as the same, potentially reducing computational cost but decreasing accuracy. A lower value will be more precise but may increase computational overhead.

Best practices when using this variable include:

  1. Adjusting it based on the scale and nature of your game objects.
  2. Testing thoroughly when changing its value, as it can significantly impact physics behavior.
  3. Considering performance implications when setting it to very low values.

Regarding the associated variable Chaos_Manifold_MatchPositionTolerance:

This is the actual variable used in the code, while p.Chaos.Collision.Manifold.MatchPositionTolerance is the console variable that controls it. It’s used directly in the collision detection logic, specifically in the AreMatchingContactPoints function of the FPBDCollisionConstraint class.

The value of Chaos_Manifold_MatchPositionTolerance is multiplied by the size of the colliding objects to determine the distance tolerance for matching contact points. This allows the tolerance to scale with object size, which is generally more robust than using a fixed distance.

When working with this variable, developers should consider the range of object sizes in their game and how this tolerance might affect different scales of interaction. It’s also important to note that this variable works in conjunction with Chaos_Manifold_MatchNormalTolerance for a complete definition of when contact points are considered matching.

#References in C++ code

#Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FRealSingle Chaos_Manifold_MatchPositionTolerance = 0.3f;		// Fraction of object size position tolerance
	FRealSingle Chaos_Manifold_MatchNormalTolerance = 0.02f;		// Dot product tolerance
	FAutoConsoleVariableRef CVarChaos_Manifold_MatchPositionTolerance(TEXT("p.Chaos.Collision.Manifold.MatchPositionTolerance"), Chaos_Manifold_MatchPositionTolerance, TEXT("A tolerance as a fraction of object size used to determine if two contact points are the same"));
	FAutoConsoleVariableRef CVarChaos_Manifold_MatchNormalTolerance(TEXT("p.Chaos.Collision.Manifold.MatchNormalTolerance"), Chaos_Manifold_MatchNormalTolerance, TEXT("A tolerance on the normal dot product used to determine if two contact points are the same"));

	FRealSingle Chaos_Manifold_FrictionExactPositionTolerance = 0.2f;	// Distance a shape-relative contact point can move and we can still be sure it's the same point (don't look for better options)
	FRealSingle Chaos_Manifold_FrictionNearPositionTolerance = 1.0f;	// Distance a shape-relative contact point can move and still be considered the same point, if no better option exists
	FAutoConsoleVariableRef CVarChaos_Manifold_FrictionExactPositionTolerance(TEXT("p.Chaos.Collision.Manifold.FrictionExactPositionTolerance"), Chaos_Manifold_FrictionExactPositionTolerance, TEXT(""));
	FAutoConsoleVariableRef CVarChaos_Manifold_FrictionNearPositionTolerance(TEXT("p.Chaos.Collision.Manifold.FrictionNearPositionTolerance"), Chaos_Manifold_FrictionNearPositionTolerance, TEXT(""));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	extern bool bChaos_Collision_EnableManifoldGJKReplace;

	FRealSingle Chaos_Manifold_MatchPositionTolerance = 0.3f;		// Fraction of object size position tolerance
	FRealSingle Chaos_Manifold_MatchNormalTolerance = 0.02f;		// Dot product tolerance
	FAutoConsoleVariableRef CVarChaos_Manifold_MatchPositionTolerance(TEXT("p.Chaos.Collision.Manifold.MatchPositionTolerance"), Chaos_Manifold_MatchPositionTolerance, TEXT("A tolerance as a fraction of object size used to determine if two contact points are the same"));
	FAutoConsoleVariableRef CVarChaos_Manifold_MatchNormalTolerance(TEXT("p.Chaos.Collision.Manifold.MatchNormalTolerance"), Chaos_Manifold_MatchNormalTolerance, TEXT("A tolerance on the normal dot product used to determine if two contact points are the same"));

	FRealSingle Chaos_Manifold_FrictionExactPositionTolerance = 0.2f;	// Distance a shape-relative contact point can move and we can still be sure it's the same point (don't look for better options)
	FRealSingle Chaos_Manifold_FrictionNearPositionTolerance = 1.0f;	// Distance a shape-relative contact point can move and still be considered the same point, if no better option exists
	FAutoConsoleVariableRef CVarChaos_Manifold_FrictionExactPositionTolerance(TEXT("p.Chaos.Collision.Manifold.FrictionExactPositionTolerance"), Chaos_Manifold_FrictionExactPositionTolerance, TEXT(""));
	FAutoConsoleVariableRef CVarChaos_Manifold_FrictionNearPositionTolerance(TEXT("p.Chaos.Collision.Manifold.FrictionNearPositionTolerance"), Chaos_Manifold_FrictionNearPositionTolerance, TEXT(""));

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

Scope (from outer to inner):

file
namespace    Chaos
function     bool FPBDCollisionConstraint::AreMatchingContactPoints

Source code excerpt:

			const FReal Size0 = Particle[0]->GetGeometry()->BoundingBox().Extents().Max();
			const FReal Size1 = Particle[1]->GetGeometry()->BoundingBox().Extents().Max();
			DistanceTolerance = FMath::Min(Size0, Size1) * Chaos_Manifold_MatchPositionTolerance;
		}
		else if (Particle[0]->GetGeometry()->HasBoundingBox())
		{
			const FReal Size0 = Particle[0]->GetGeometry()->BoundingBox().Extents().Max();
			DistanceTolerance = Size0 * Chaos_Manifold_MatchPositionTolerance;
		}
		else if (Particle[1]->GetGeometry()->HasBoundingBox())
		{
			const FReal Size1 = Particle[1]->GetGeometry()->BoundingBox().Extents().Max();
			DistanceTolerance = Size1 * Chaos_Manifold_MatchPositionTolerance;
		}
		else
		{
			return false;
		}
		const FReal NormalTolerance = Chaos_Manifold_MatchNormalTolerance;