p.Chaos.Collision.SortMeshManifoldByDistance

p.Chaos.Collision.SortMeshManifoldByDistance

#Overview

name: p.Chaos.Collision.SortMeshManifoldByDistance

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.SortMeshManifoldByDistance is to enable sorting of large mesh manifold points by |RxN| (cross product of position vector and normal vector) for improved solver stability, particularly to reduce rotation in the first iteration of the physics solver.

This setting variable is primarily used in the Chaos physics system, which is part of Unreal Engine’s experimental physics simulation subsystem. It specifically affects the collision detection and resolution for large mesh objects.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized as false and can be changed at runtime using the console command system.

This variable interacts closely with the associated variable bChaos_Collision_MeshManifoldSortByDistance. They share the same value and are used interchangeably in the code.

Developers should be aware that enabling this variable can impact performance, as it introduces an additional sorting step in the collision resolution process. However, it can lead to more stable physics simulations, especially for large mesh objects or in scenarios where initial rotations are problematic.

Best practices when using this variable include:

  1. Enable it when dealing with large mesh objects that exhibit unstable behavior in physics simulations.
  2. Monitor performance impact when enabling this feature, especially in performance-critical scenarios.
  3. Use in conjunction with other Chaos physics settings to fine-tune collision behavior.

Regarding the associated variable bChaos_Collision_MeshManifoldSortByDistance:

The purpose of bChaos_Collision_MeshManifoldSortByDistance is identical to p.Chaos.Collision.SortMeshManifoldByDistance. It’s used internally within the Chaos physics system to control the sorting of contact points in mesh collisions.

This variable is used in the Chaos collision system, specifically in the contact point processing for triangle meshes.

The value of this variable is set through the console variable system, mirroring p.Chaos.Collision.SortMeshManifoldByDistance.

It directly affects the behavior of the FContactTriangleCollector::SortContactPointsForSolving function, where it determines whether contact points should be sorted based on their distance from the center of mass.

Developers should be aware that this variable can significantly impact the behavior of mesh collisions, potentially improving stability but at the cost of additional computational overhead.

Best practices for using this variable include:

  1. Use it in scenarios where mesh collision stability is a concern, especially for large or complex mesh objects.
  2. Consider the performance implications, particularly in scenes with many colliding mesh objects.
  3. Test thoroughly with both enabled and disabled states to ensure it provides the desired improvement in your specific use case.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	bool bChaos_Collision_MeshManifoldSortByDistance = false;
	FAutoConsoleVariableRef CVarChaos_Collision_LargeMeshManifoldSortByDistance(TEXT("p.Chaos.Collision.SortMeshManifoldByDistance"), bChaos_Collision_MeshManifoldSortByDistance, TEXT("Sort large mesh manifold points by |RxN| for improved solver stability (less rotation in first iteration)"));

	int32 Chaos_Collision_MeshManifoldHashSize = 256;
	FAutoConsoleVariableRef CVarChaos_Collision_MeshManifoldHashSize(TEXT("p.Chaos.Collision.MeshManifoldHashSize"), Chaos_Collision_MeshManifoldHashSize, TEXT("Hash table size to use in vertex and edge maps in convex-mesh collision"));

	// @todo(chaos): Temp while we test the new convex-mesh collision optimizations
	bool bChaos_Collision_EnableMeshManifoldOptimizedLoop = true;

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	extern bool bChaos_Collision_EnableLargeMeshManifolds;
	extern FRealSingle Chaos_Collision_MeshContactNormalThreshold;
	extern bool bChaos_Collision_MeshManifoldSortByDistance;


	void FContactTriangleCollector::SetNumContacts(const int32 NumContacts)
	{
		TriangleContactPoints.SetNum(NumContacts, EAllowShrinking::No);
		TriangleContactPointDatas.SetNum(NumContacts, EAllowShrinking::No);

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FContactTriangleCollector::SortContactPointsForSolving

Source code excerpt:

			TriangleContactPointDatas.Reset();

			if (bChaos_Collision_MeshManifoldSortByDistance)
			{
				// Sort contact points by distance from the center of mass (RxN) so that points closer to the center of
				// mass are solved first. This produces better solver results for low iterations because, if we were to 
				// solve the distant points first, we would get extra rotation applied. 
				//
				// E.g., consider a box landing on an inclined plane with 5 contact points biassed toward one side.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarChaos_Collision_MeshContactNormalRejectionThreshold(TEXT("p.Chaos.Collision.MeshContactNormalRejectionThreshold"), Chaos_Collision_MeshContactNormalRejectionThreshold, TEXT("Don't correct edge and vertex normals if they are beyond the valid range by more than this"));

	bool bChaos_Collision_MeshManifoldSortByDistance = false;
	FAutoConsoleVariableRef CVarChaos_Collision_LargeMeshManifoldSortByDistance(TEXT("p.Chaos.Collision.SortMeshManifoldByDistance"), bChaos_Collision_MeshManifoldSortByDistance, TEXT("Sort large mesh manifold points by |RxN| for improved solver stability (less rotation in first iteration)"));

	int32 Chaos_Collision_MeshManifoldHashSize = 256;
	FAutoConsoleVariableRef CVarChaos_Collision_MeshManifoldHashSize(TEXT("p.Chaos.Collision.MeshManifoldHashSize"), Chaos_Collision_MeshManifoldHashSize, TEXT("Hash table size to use in vertex and edge maps in convex-mesh collision"));

	// @todo(chaos): Temp while we test the new convex-mesh collision optimizations
	bool bChaos_Collision_EnableMeshManifoldOptimizedLoop = true;