p.Chaos.Collision.Manifold.EnableFrictionRestore

p.Chaos.Collision.Manifold.EnableFrictionRestore

#Overview

name: p.Chaos.Collision.Manifold.EnableFrictionRestore

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.EnableFrictionRestore is to control the friction restoration feature in the Chaos physics engine’s collision system. This setting variable is part of Unreal Engine 5’s physics simulation, specifically the Chaos physics solver.

The Chaos physics engine, which is an experimental module in Unreal Engine 5, relies on this setting variable. It is primarily used in the collision handling subsystem, particularly in the manifold generation and friction calculations.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. It is initialized to true by default.

This setting variable interacts directly with its associated boolean variable bChaos_Manifold_EnableFrictionRestore. They share the same value, and the console variable (p.Chaos.Collision.Manifold.EnableFrictionRestore) is used to control the associated boolean.

Developers must be aware that this variable affects the behavior of friction in collision manifolds. When enabled (set to true), it allows for friction restoration, which can potentially improve the accuracy of physical simulations, especially in scenarios where objects are in prolonged contact.

Best practices when using this variable include:

  1. Testing the simulation with both enabled and disabled states to determine which provides better results for your specific use case.
  2. Monitoring performance impacts, as enabling friction restoration may increase computational overhead.
  3. Using this in conjunction with other Chaos physics settings to fine-tune collision behavior.

Regarding the associated variable bChaos_Manifold_EnableFrictionRestore:

The purpose of bChaos_Manifold_EnableFrictionRestore is to act as the internal boolean flag that the Chaos physics engine checks when determining whether to apply friction restoration in collision manifolds.

This variable is used directly in the Chaos physics engine’s collision constraint solving code, specifically in the FPBDCollisionConstraint::FindSavedManifoldPoint function.

The value of this variable is set by the console variable p.Chaos.Collision.Manifold.EnableFrictionRestore, allowing for runtime modification.

It interacts closely with other variables in the manifold point handling code, such as Chaos_Manifold_FrictionExactPositionTolerance and Chaos_Manifold_FrictionNearPositionTolerance.

Developers should be aware that this flag directly impacts the behavior of the collision solver. When true, it enables a more detailed friction model which may be more physically accurate but potentially more computationally expensive.

Best practices include:

  1. Profiling the performance impact of enabling this flag in your specific scenarios.
  2. Considering the trade-off between simulation accuracy and performance when deciding whether to enable this feature.
  3. Testing collision behavior thoroughly when modifying this flag, as it can significantly affect how objects interact in 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/Collision/PBDCollisionConstraint.cpp:42

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	bool bChaos_Manifold_EnableFrictionRestore = true;
	FAutoConsoleVariableRef CVarChaos_Manifold_EnableFrictionRestore(TEXT("p.Chaos.Collision.Manifold.EnableFrictionRestore"), bChaos_Manifold_EnableFrictionRestore, TEXT(""));
	
	// The margin to use when we are colliding a convex shape against a zero-margin shape. E.g., Box-Triangle.
	// When both shapes have a margin we use the minimum margin, but we don't want to use a zero margin because we hit the EPA degenerate case
	// NOTE: This is currently disabled - margins for convex-trimesh cause bigger problems than the EPA issue
	FRealSingle Chaos_Collision_ConvexZeroMargin = 0.0f;
	FAutoConsoleVariableRef CVarChaos_Collision_ConvexZeroMargin(TEXT("p.Chaos.Collision.ConvexZeroMargin"), Chaos_Collision_ConvexZeroMargin, TEXT(""));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarChaos_GBFCharacteristicTimeRatio(TEXT("p.Chaos.Collision.GBFCharacteristicTimeRatio"), Chaos_GBFCharacteristicTimeRatio, TEXT("The ratio between characteristic time and Dt"));

	bool bChaos_Manifold_EnableFrictionRestore = true;
	FAutoConsoleVariableRef CVarChaos_Manifold_EnableFrictionRestore(TEXT("p.Chaos.Collision.Manifold.EnableFrictionRestore"), bChaos_Manifold_EnableFrictionRestore, TEXT(""));
	
	// The margin to use when we are colliding a convex shape against a zero-margin shape. E.g., Box-Triangle.
	// When both shapes have a margin we use the minimum margin, but we don't want to use a zero margin because we hit the EPA degenerate case
	// NOTE: This is currently disabled - margins for convex-trimesh cause bigger problems than the EPA issue
	FRealSingle Chaos_Collision_ConvexZeroMargin = 0.0f;
	FAutoConsoleVariableRef CVarChaos_Collision_ConvexZeroMargin(TEXT("p.Chaos.Collision.ConvexZeroMargin"), Chaos_Collision_ConvexZeroMargin, TEXT(""));

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

Scope (from outer to inner):

file
namespace    Chaos
function     int32 FPBDCollisionConstraint::FindSavedManifoldPoint

Source code excerpt:

	int32 FPBDCollisionConstraint::FindSavedManifoldPoint(const int32 ManifoldPointIndex, int32* InOutAllowedSavedPointIndices, int32& InOutNumAllowedSavedPoints) const
	{
		if (bChaos_Manifold_EnableFrictionRestore)
		{
			const FManifoldPoint& ManifoldPoint = ManifoldPoints[ManifoldPointIndex];
			if (!ManifoldPoint.Flags.bDisabled)
			{
				const FRealSingle ExactDistanceToleranceSq = FMath::Square(Chaos_Manifold_FrictionExactPositionTolerance);
				const FRealSingle NearDistanceToleranceSq = FMath::Square(Chaos_Manifold_FrictionNearPositionTolerance);