p.Chaos.Collision.Manifold.MatchNormalTolerance

p.Chaos.Collision.Manifold.MatchNormalTolerance

#Overview

name: p.Chaos.Collision.Manifold.MatchNormalTolerance

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.MatchNormalTolerance is to define a tolerance value for comparing normal vectors in collision detection within the Chaos physics system of Unreal Engine 5. This setting is specifically used in the collision manifold generation process.

This setting variable is primarily used by the Chaos physics subsystem, which is part of Unreal Engine’s experimental physics framework. It is referenced in the PBDCollisionConstraint module, which handles collision constraints for Position Based Dynamics (PBD) in the Chaos system.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 0.02f, which represents a dot product tolerance. This value can be modified at runtime using the console command system.

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

Developers must be aware that this variable affects the sensitivity of collision detection. A higher value will make the system more lenient in considering two contact points as the same based on their normal vectors, while a lower value will make it more strict.

Best practices when using this variable include:

  1. Fine-tuning it based on the specific requirements of your physics simulation.
  2. Testing thoroughly after adjusting the value to ensure it doesn’t introduce unwanted behavior in collision detection.
  3. Considering the interplay between this variable and other collision-related settings.

Regarding the associated variable Chaos_Manifold_MatchNormalTolerance:

This variable is the internal representation of the console variable p.Chaos.Collision.Manifold.MatchNormalTolerance. It’s used directly in the collision detection code, specifically in the AreMatchingContactPoints function of the FPBDCollisionConstraint class.

The purpose of Chaos_Manifold_MatchNormalTolerance is the same as p.Chaos.Collision.Manifold.MatchNormalTolerance - to provide a tolerance value for comparing normal vectors in collision detection.

It’s used to determine if two contact points are considered the same based on their normal vectors. If the dot product of two contact normals is less than (1.0 - Chaos_Manifold_MatchNormalTolerance), the contacts are considered different.

Developers should be aware that modifying p.Chaos.Collision.Manifold.MatchNormalTolerance will directly affect Chaos_Manifold_MatchNormalTolerance, and thus the behavior of the collision detection system.

Best practices for using this variable include carefully considering the implications on collision detection accuracy and performance when adjusting its value, and thoroughly testing any changes in various collision 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/Collision/PBDCollisionConstraint.cpp:30

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	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_MatchNormalTolerance. They share the same value. See the following C++ source code.

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

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(""));

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

Scope (from outer to inner):

file
namespace    Chaos
function     bool FPBDCollisionConstraint::AreMatchingContactPoints

Source code excerpt:

			return false;
		}
		const FReal NormalTolerance = Chaos_Manifold_MatchNormalTolerance;

		// If normal has changed a lot, it is a different contact
		// (This was only here to detect bad normals - it is not right for edge-edge contact tracking, but we don't do a good job of that yet anyway!)
		FReal NormalDot = FVec3::DotProduct(A.ShapeContactNormal, B.ShapeContactNormal);
		if (NormalDot < 1.0f - NormalTolerance)
		{