p.Chaos.Collision.EnableSubSurfaceCollisionPruning

p.Chaos.Collision.EnableSubSurfaceCollisionPruning

#Overview

name: p.Chaos.Collision.EnableSubSurfaceCollisionPruning

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.EnableSubSurfaceCollisionPruning is to control the subsurface collision pruning in the Chaos physics engine of Unreal Engine 5. This setting is part of the collision system within the Chaos physics module.

Based on the callsites, this variable is primarily used in the Chaos namespace, specifically within the PBDCollisionConstraints.cpp file. This indicates that it’s part of the Position Based Dynamics (PBD) collision system in the Chaos physics engine.

The value of this variable is set through an FAutoConsoleVariableRef, which means it can be dynamically adjusted at runtime through console commands or configuration files. By default, it is set to false.

This variable interacts closely with two other similar variables: bCollisionsEnableEdgeCollisionPruning and bCollisionsEnableMeshCollisionPruning. All three are part of the collision pruning system in Chaos.

Developers should be aware that this variable specifically controls subsurface collision pruning. When enabled, it affects how collisions are processed for objects that may have intersecting or overlapping surfaces.

Best practices for using this variable include:

  1. Only enable it when subsurface collision pruning is necessary for performance or gameplay reasons.
  2. Test thoroughly when enabling or disabling this feature, as it can significantly affect physics behavior.
  3. Consider the interaction with other collision pruning settings (edge and mesh) for a comprehensive collision strategy.

Regarding the associated variable bCollisionsEnableSubSurfaceCollisionPruning:

This is the actual boolean variable that controls the behavior, while p.Chaos.Collision.EnableSubSurfaceCollisionPruning is the console variable that allows runtime modification of this setting.

The purpose of bCollisionsEnableSubSurfaceCollisionPruning is to directly control whether subsurface collision pruning is active in the physics simulation.

It’s used within the FPBDCollisionConstraints::PruneEdgeCollisions function to determine whether to perform subsurface collision pruning for each particle.

When enabled, it creates a FParticleSubSurfaceCollisionPruner object and calls its Prune method with an up vector derived from the particle’s rotation.

Developers should be aware that this variable directly affects the physics simulation performance and accuracy. Enabling it may improve performance but could potentially lead to less accurate collision detection in some scenarios involving intersecting or thin surfaces.

Best practices for using this variable include:

  1. Carefully profile your application with this setting both on and off to understand its impact on performance and physics behavior.
  2. Use in conjunction with other collision pruning techniques for optimal results.
  3. Consider exposing this setting to technical artists or level designers if fine-tuning of physics behavior is required for specific game 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/PBDCollisionConstraints.cpp:84

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarCollisionsEnableEdgeCollisionPruning(TEXT("p.Chaos.Collision.EnableEdgeCollisionPruning"), bCollisionsEnableEdgeCollisionPruning, TEXT(""));
	FAutoConsoleVariableRef CVarCollisionsEnableMeshCollisionPruning(TEXT("p.Chaos.Collision.EnableMeshCollisionPruning"), bCollisionsEnableMeshCollisionPruning, TEXT(""));
	FAutoConsoleVariableRef CVarCollisionsEnableSubSurfaceCollisionPruning(TEXT("p.Chaos.Collision.EnableSubSurfaceCollisionPruning"), bCollisionsEnableSubSurfaceCollisionPruning, TEXT(""));

	bool DebugDrawProbeDetection = false;
	FAutoConsoleVariableRef CVarDebugDrawProbeDetection(TEXT("p.Chaos.Collision.DebugDrawProbeDetection"), DebugDrawProbeDetection, TEXT("Draw probe constraint detection."));

#if CHAOS_DEBUG_DRAW
	namespace CVars

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDCollisionConstraints.cpp:81

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	bool bCollisionsEnableEdgeCollisionPruning = true;
	bool bCollisionsEnableMeshCollisionPruning = true;
	bool bCollisionsEnableSubSurfaceCollisionPruning = false;
	FAutoConsoleVariableRef CVarCollisionsEnableEdgeCollisionPruning(TEXT("p.Chaos.Collision.EnableEdgeCollisionPruning"), bCollisionsEnableEdgeCollisionPruning, TEXT(""));
	FAutoConsoleVariableRef CVarCollisionsEnableMeshCollisionPruning(TEXT("p.Chaos.Collision.EnableMeshCollisionPruning"), bCollisionsEnableMeshCollisionPruning, TEXT(""));
	FAutoConsoleVariableRef CVarCollisionsEnableSubSurfaceCollisionPruning(TEXT("p.Chaos.Collision.EnableSubSurfaceCollisionPruning"), bCollisionsEnableSubSurfaceCollisionPruning, TEXT(""));

	bool DebugDrawProbeDetection = false;
	FAutoConsoleVariableRef CVarDebugDrawProbeDetection(TEXT("p.Chaos.Collision.DebugDrawProbeDetection"), DebugDrawProbeDetection, TEXT("Draw probe constraint detection."));

#if CHAOS_DEBUG_DRAW
	namespace CVars

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDCollisionConstraints.cpp:760

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDCollisionConstraints::PruneEdgeCollisions

Source code excerpt:

					}

					if (bCollisionsEnableSubSurfaceCollisionPruning)
					{
						const FVec3 UpVector = ParticleHandle.GetR().GetAxisZ();
						FParticleSubSurfaceCollisionPruner SubSurfacePruner(ParticleHandle.Handle());
						SubSurfacePruner.Prune(UpVector);
					}
				}