p.Chaos.Collision.ConvexZeroMargin

p.Chaos.Collision.ConvexZeroMargin

#Overview

name: p.Chaos.Collision.ConvexZeroMargin

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.ConvexZeroMargin is to set a minimum margin value for convex collision shapes in the Chaos physics system. It is primarily used in the collision detection and resolution process within Unreal Engine’s Chaos physics module.

This setting variable is relied upon by the Chaos physics subsystem, specifically within the collision constraint handling part of the system. It is defined and used in the PBDCollisionConstraint.cpp file, which is part of the Experimental Chaos runtime module.

The value of this variable is set to 0.0f by default, as seen in the source code. It’s important to note that the comment suggests this feature is currently disabled due to issues with convex-trimesh collisions.

The variable interacts directly with its associated variable Chaos_Collision_ConvexZeroMargin. They share the same value and are used interchangeably in the code.

Developers must be aware that:

  1. This variable is currently disabled in the default implementation.
  2. It’s intended to prevent issues with the EPA (Expanding Polytope Algorithm) in degenerate cases.
  3. Modifying this value could impact the behavior of convex collision detection, especially in edge cases.

Best practices when using this variable include:

  1. Thoroughly testing any changes to this value, as it can significantly impact collision behavior.
  2. Considering the trade-offs between precise collision detection and performance.
  3. Being cautious when enabling or modifying this value, as it may introduce new issues, especially with convex-trimesh collisions.

Regarding the associated variable Chaos_Collision_ConvexZeroMargin:

The purpose of Chaos_Collision_ConvexZeroMargin is identical to p.Chaos.Collision.ConvexZeroMargin. It serves as the internal representation of the console variable within the Chaos physics system.

This variable is used directly in the collision constraint initialization process, specifically in the InitMarginsAndTolerances function of the FPBDCollisionConstraint class. It sets the minimum margin for collision shapes when both shapes have a margin.

The value of this variable is set through the console variable p.Chaos.Collision.ConvexZeroMargin.

Developers should be aware that this variable directly influences the collision margin calculations in the Chaos physics system. Changes to this value will affect how closely objects can approach each other before a collision is detected and resolved.

Best practices for using Chaos_Collision_ConvexZeroMargin include:

  1. Modifying it through the console variable p.Chaos.Collision.ConvexZeroMargin rather than directly in the code.
  2. Carefully monitoring the effects of any changes on overall physics behavior in the game.
  3. Considering performance implications when adjusting this value, as it may affect the frequency and complexity of collision checks.

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

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

	// A collision solver stiffness override if >= 0. A value < 0 means use ths config setting.
	FRealSingle Chaos_Collision_Stiffness = -1.0f;
	FAutoConsoleVariableRef CVarChaos_Collision_Stiffness(TEXT("p.Chaos.Collision.Stiffness"), Chaos_Collision_Stiffness, TEXT("Override the collision solver stiffness (if >= 0)"));

	// Enable/Disable the one-way interaction system for collisions

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

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

	// A collision solver stiffness override if >= 0. A value < 0 means use ths config setting.
	FRealSingle Chaos_Collision_Stiffness = -1.0f;
	FAutoConsoleVariableRef CVarChaos_Collision_Stiffness(TEXT("p.Chaos.Collision.Stiffness"), Chaos_Collision_Stiffness, TEXT("Override the collision solver stiffness (if >= 0)"));

	// Enable/Disable the one-way interaction system for collisions

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDCollisionConstraint::InitMarginsAndTolerances

Source code excerpt:

			// If both shapes have a margin, use the smaller margin on both shapes. E.g., Box-Box
			// We should never see both shapes with zero margin, but if we did we'd end up with a zero margin
			const FRealSingle MinMargin = Chaos_Collision_ConvexZeroMargin;
			if (DynamicMargin0 == FRealSingle(0))
			{
				CollisionMargins[0] = 0;
				CollisionMargins[1] = FMath::Max(MinMargin, DynamicMargin1);
			}
			else if (DynamicMargin1 == FRealSingle(0))