p.GeometryCollection.AlwaysGenerateGTCollisionForClusters

p.GeometryCollection.AlwaysGenerateGTCollisionForClusters

#Overview

name: p.GeometryCollection.AlwaysGenerateGTCollisionForClusters

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.GeometryCollection.AlwaysGenerateGTCollisionForClusters is to control the generation of game thread-side collision for clusters in Geometry Collections within Unreal Engine 5’s physics system.

This setting variable is primarily used in the Experimental Chaos physics module of Unreal Engine 5. It affects the behavior of Geometry Collections, which are part of the physics and destruction system.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be changed at runtime through console commands. By default, it is set to true.

The associated variable bGeometryCollectionAlwaysGenerateGTCollisionForClusters directly interacts with this console variable. They share the same value and purpose.

Developers must be aware that:

  1. This variable affects performance and memory usage, as generating game thread-side collision for all clusters can be resource-intensive.
  2. It influences the behavior of Geometry Collections, particularly in how collision is handled for clusters.
  3. Changing this value can impact gameplay mechanics that rely on precise collision detection for Geometry Collection clusters.

Best practices when using this variable include:

  1. Consider performance implications when enabling this feature, especially for complex Geometry Collections or scenes with many Geometry Collections.
  2. Test thoroughly with both enabled and disabled states to ensure desired behavior and performance.
  3. Use in conjunction with other Geometry Collection settings for optimal results.

Regarding the associated variable bGeometryCollectionAlwaysGenerateGTCollisionForClusters:

Developers should be cautious when modifying this variable, as it can significantly impact both the physics simulation accuracy and performance of Geometry Collections in their game.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/GeometryCollectionPhysicsProxy.cpp:98

Scope: file

Source code excerpt:

bool bGeometryCollectionAlwaysGenerateGTCollisionForClusters = true;
FAutoConsoleVariableRef CVarGeometryCollectionAlwaysGenerateGTCollisionForClusters(
	TEXT("p.GeometryCollection.AlwaysGenerateGTCollisionForClusters"),
	bGeometryCollectionAlwaysGenerateGTCollisionForClusters,
	TEXT("When enabled, always generate a game thread side collision for clusters.[def: true]"));

bool bGeometryCollectionAlwaysGenerateConnectionGraph = false;
FAutoConsoleVariableRef CVarGeometryCollectionAlwaysGenerateConnectionGraph(
	TEXT("p.GeometryCollection.AlwaysGenerateConnectionGraph"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/GeometryCollectionPhysicsProxy.cpp:96

Scope: file

Source code excerpt:

	TEXT("Enable updates for driven, disabled, child bodies. Used for line trace results against geometry collections.[def: true]"));

bool bGeometryCollectionAlwaysGenerateGTCollisionForClusters = true;
FAutoConsoleVariableRef CVarGeometryCollectionAlwaysGenerateGTCollisionForClusters(
	TEXT("p.GeometryCollection.AlwaysGenerateGTCollisionForClusters"),
	bGeometryCollectionAlwaysGenerateGTCollisionForClusters,
	TEXT("When enabled, always generate a game thread side collision for clusters.[def: true]"));

bool bGeometryCollectionAlwaysGenerateConnectionGraph = false;
FAutoConsoleVariableRef CVarGeometryCollectionAlwaysGenerateConnectionGraph(
	TEXT("p.GeometryCollection.AlwaysGenerateConnectionGraph"),
	bGeometryCollectionAlwaysGenerateConnectionGraph,

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/GeometryCollectionPhysicsProxy.cpp:815

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::CreateGTParticles

Source code excerpt:

		}
		// this step is necessary for Phase 2 where we need to walk back the hierarchy from children to parent 
		if (bGeometryCollectionAlwaysGenerateGTCollisionForClusters && !GameThreadCollection.HasChildren(TransformIndex))
		{
			ChildrenToCheckForParentFix.Add(TransformIndex);
		}
	}

	if (bGeometryCollectionAlwaysGenerateGTCollisionForClusters)
	{
		// second phase: fixing parent geometries
		// @todo(chaos) this could certainly be done ahead at generation time rather than runtime
		TSet<int32> ParentToPotentiallyFix;
		while (ChildrenToCheckForParentFix.Num())
		{

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PhysicsProxy/GeometryCollectionPhysicsProxy.cpp:2922

Scope (from outer to inner):

file
function     TBitArray<> FGeometryCollectionPhysicsProxy::CalculateClustersToCreateFromChildren

Source code excerpt:

{
	// Generate a bitmask of all the particles that are clusters without any collision geometry, that have children with collision geometry
	// This is a workaround following the fix to not create particles that have no geometry. If bGeometryCollectionAlwaysGenerateGTCollisionForClusters
	// is set, we will be auto-generating cluster geometry from their children (if they have geometry)
	// @todo(chaos): this dupes functionality in FGeometryCollectionPhysicsProxy::Initialize
	TBitArray<> ClustersToGenerate;

	if (bGeometryCollectionAlwaysGenerateGTCollisionForClusters)
	{
		ClustersToGenerate.Init(false, NumTransforms);

		const TManagedArray<Chaos::FImplicitObjectPtr>& Implicits = DynamicCollection.GetAttribute<Chaos::FImplicitObjectPtr>(FGeometryDynamicCollection::ImplicitsAttribute, FTransformCollection::TransformGroup);

		// All the leaf objects