p.gc.BuildGeometryForChildrenOnGT

p.gc.BuildGeometryForChildrenOnGT

#Overview

name: p.gc.BuildGeometryForChildrenOnGT

This variable is created as a Console Variable (cvar).

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.gc.BuildGeometryForChildrenOnGT is to control the timing of geometry building for children in the Geometry Collection system within Unreal Engine’s Chaos physics engine. Specifically, it determines whether to build all children geometry on the Game Thread at initialization time or wait until destruction occurs.

This setting variable is primarily used in the Chaos physics module, which is part of Unreal Engine’s experimental physics system. It affects the behavior of the Geometry Collection Physics Proxy, which is responsible for managing the physical representation of Geometry Collections.

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

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

Developers should be aware of the following when using this variable:

  1. Setting it to true will cause all children geometry to be built on the Game Thread at initialization time, which may impact performance during level loading or object spawning.
  2. Setting it to false will defer geometry building until destruction occurs, which may improve initial performance but could lead to delays during object destruction.

Best practices when using this variable include:

  1. Consider the trade-offs between initial load time and destruction performance when deciding whether to enable or disable this feature.
  2. Use in conjunction with other related variables like p.gc.CreateGTParticlesForChildren to fine-tune the behavior of Geometry Collections.
  3. Profile your game’s performance with different settings to determine the optimal configuration for your specific use case.

Regarding the associated variable bBuildGeometryForChildrenOnGT:

This variable is used directly in the code to control the behavior of geometry building and particle creation. It’s used in conjunction with bCreateGTParticleForChildren to determine when and how to create particles and build geometry for Geometry Collection children. The variable affects the initialization process of FGeometryCollectionPhysicsProxy and the creation of GT (Game Thread) particles.

Developers should be aware that this variable can significantly impact the performance and behavior of Geometry Collections, especially during initialization and destruction phases. It’s important to consider the implications of enabling or disabling this feature based on the specific requirements of your project and the performance characteristics you’re aiming for.

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

Scope: file

Source code excerpt:


bool bBuildGeometryForChildrenOnGT = true;
FAutoConsoleVariableRef CVarbBuildGeometryForChildrenOnGT(TEXT("p.gc.BuildGeometryForChildrenOnGT"), bBuildGeometryForChildrenOnGT, TEXT("If true build all children geometry  on Game Thread at initilaization time, otherwise wait until destruction occurs."));

bool bCreateGTParticleForChildren = true;
FAutoConsoleVariableRef CVarCreateGTParticleForChildren(TEXT("p.gc.CreateGTParticlesForChildren"), bCreateGTParticleForChildren, TEXT("If true create all children particles at initilaization time, otherwise wait until destruction occurs."));

bool bRemoveImplicitsInDynamicCollections = false;
FAutoConsoleVariableRef CVarbRemoveImplicitsInDynamicCollections(TEXT("p.gc.RemoveImplicitsInDynamicCollections"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

FAutoConsoleVariableRef CVarbBuildGeometryForChildrenOnPT(TEXT("p.gc.BuildGeometryForChildrenOnPT"), bBuildGeometryForChildrenOnPT, TEXT("If true build all children geometry on Physics Thread at initilaization time, otherwise wait until destruction occurs."));

bool bBuildGeometryForChildrenOnGT = true;
FAutoConsoleVariableRef CVarbBuildGeometryForChildrenOnGT(TEXT("p.gc.BuildGeometryForChildrenOnGT"), bBuildGeometryForChildrenOnGT, TEXT("If true build all children geometry  on Game Thread at initilaization time, otherwise wait until destruction occurs."));

bool bCreateGTParticleForChildren = true;
FAutoConsoleVariableRef CVarCreateGTParticleForChildren(TEXT("p.gc.CreateGTParticlesForChildren"), bCreateGTParticleForChildren, TEXT("If true create all children particles at initilaization time, otherwise wait until destruction occurs."));

bool bRemoveImplicitsInDynamicCollections = false;
FAutoConsoleVariableRef CVarbRemoveImplicitsInDynamicCollections(TEXT("p.gc.RemoveImplicitsInDynamicCollections"),

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

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::Initialize

Source code excerpt:

	{
		constexpr bool bInitializationTime = true;
		bHasBuiltGeometryOnGT = bBuildGeometryForChildrenOnGT;
		CreateGTParticles(Implicits, Evolution, bInitializationTime);

		// Skip simplicials, as they're owned by unique pointers.
		static const FAttributeAndGroupId SkipList[] =
		{
			{ FGeometryDynamicCollection::SimplicialsAttribute, FTransformCollection::TransformGroup },

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

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::Initialize

Source code excerpt:

	}
	// If GT particle have been created, we can use directly the UniqueIdx from the GTParticle, then free up some space.
	if (bBuildGeometryForChildrenOnGT || bCreateGTParticleForChildren)
	{
		UniqueIdxs.Empty();
	}
}

void FGeometryCollectionPhysicsProxy::CreateGTParticles(TManagedArray<Chaos::FImplicitObjectPtr>& Implicits, Chaos::FPBDRigidsEvolutionBase* Evolution, bool bInitializationTime)

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

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::CreateGTParticles

Source code excerpt:


	TArray<int32> ChildrenToCheckForParentFix;
	if (!bInitializationTime && !bCreateGTParticleForChildren && !bBuildGeometryForChildrenOnGT)
	{
		GTParticlesToTransformGroupIndex.Reserve(NumEffectiveParticles);
	}

	for (int32 ParticleIndex = 0; ParticleIndex < NumEffectiveParticles; ++ParticleIndex)
	{

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

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::CreateGTParticles

Source code excerpt:


		if ((bInitializationTime && TransformIndex == Parameters.InitialRootIndex) || // When initializing always create particle for the root
			((bInitializationTime && (bCreateGTParticleForChildren || bBuildGeometryForChildrenOnGT)) || // When initializing create all particles if one of the flag is true 
				(!bInitializationTime && TransformIndex != Parameters.InitialRootIndex && !bCreateGTParticleForChildren && !bBuildGeometryForChildrenOnGT))) // When not initializing create other particles if flag was set to not create
		{
			GTParticles[ParticleIndex] = FParticle::CreateParticle();
			P = GTParticles[ParticleIndex].Get();
			GTParticlesToTransformGroupIndex.Add(P, TransformIndex);
			GTParticles[ParticleIndex]->SetUniqueIdx(UniqueIdxs[ParticleIndex]);
#if CHAOS_DEBUG_NAME

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

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::CreateGTParticles

Source code excerpt:

			P->SetGeometry(ImplicitGeometry);
		}
		else if (bInitializationTime == (TransformIndex == Parameters.InitialRootIndex) || bBuildGeometryForChildrenOnGT)
		{
			Chaos::FImplicitObjectPtr ImplicitGeometry = Implicits[TransformIndex];
			if (ImplicitGeometry && !Scale.Equals(FVector::OneVector))
			{
				ImplicitGeometry = ImplicitGeometry->CopyGeometryWithScale(Scale);
			}

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

Scope (from outer to inner):

file
function     void FGeometryCollectionPhysicsProxy::CreateGTParticles

Source code excerpt:

		}

		if (bInitializationTime == (TransformIndex == Parameters.InitialRootIndex) || bBuildGeometryForChildrenOnGT)
		{
			if (DynamicCollectionAnchoringFacade.IsAnchored(TransformIndex))
			{
				P->SetObjectState(Chaos::EObjectStateType::Kinematic, false, false);
			}