p.GeometryCollection.UseRootBrokenFlag

p.GeometryCollection.UseRootBrokenFlag

#Overview

name: p.GeometryCollection.UseRootBrokenFlag

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.GeometryCollection.UseRootBrokenFlag is to control the behavior of root transform checking in Geometry Collections within Unreal Engine’s Chaos physics system. It specifically determines whether the system should check if the root transform is broken in the physics proxy and disable the corresponding game thread (GT) particle if so.

This setting variable is primarily used in the Chaos physics system, which is part of Unreal Engine’s experimental physics module. It’s specifically utilized in the GeometryCollectionPhysicsProxy, which handles the synchronization between physics simulation and game thread representation of Geometry Collections.

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

The associated variable bGeometryCollectionUseRootBrokenFlag directly interacts with this console variable. They share the same value, with bGeometryCollectionUseRootBrokenFlag being the actual boolean used in the code logic.

Developers must be aware that this variable acts as a failsafe mechanism. The comment suggests that it should generally be enabled, and the console variable exists primarily to allow reverting the behavior if needed.

Best practices when using this variable include:

  1. Generally leaving it enabled unless specific issues arise.
  2. Understanding that disabling it might affect the accuracy of Geometry Collection simulations, particularly in cases where root transforms become invalid.
  3. Using it in conjunction with other Geometry Collection and Chaos physics settings for optimal performance and behavior.

Regarding the associated variable bGeometryCollectionUseRootBrokenFlag:

The purpose of bGeometryCollectionUseRootBrokenFlag is to serve as the actual boolean flag used in the code logic to determine whether to check for broken root transforms.

This variable is used directly in the Chaos physics system, specifically in the FGeometryCollectionPhysicsProxy class.

Its value is set by the p.GeometryCollection.UseRootBrokenFlag console variable.

It interacts directly with the physics simulation logic, particularly in the method PullNonInterpolatableDataFromSinglePhysicsState.

Developers should be aware that this variable directly affects the behavior of Geometry Collections in physics simulations. When true, it enables a check that can potentially disable particles in the game thread based on the state of the root transform in the physics simulation.

Best practices include:

  1. Monitoring its effects on performance and simulation accuracy.
  2. Considering its impact when debugging Geometry Collection behavior.
  3. Being cautious about changing its value, as it’s intended to be enabled by default for proper functionality.

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

Scope: file

Source code excerpt:

bool bGeometryCollectionUseRootBrokenFlag = true;
FAutoConsoleVariableRef CVarGeometryCollectionUseRootBrokenFlag(
	TEXT("p.GeometryCollection.UseRootBrokenFlag"),
	bGeometryCollectionUseRootBrokenFlag,
	TEXT("If enabled, check if the root transform is broken in the proxy and disable the GT particle if so. Should be enabled - cvar is a failsafe to revert behaviour"));

bool bPropagateInternalClusterDisableFlagToChildren = true;
FAutoConsoleVariableRef CVarPropagateInternalClusterDisableFlagToChildren(
	TEXT("p.GeometryCollection.PropagateInternalClusterDisableFlagToChildren"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	TEXT("Tolerance to detect if particle rotation has changed has changed when syncing PT to GT"));

bool bGeometryCollectionUseRootBrokenFlag = true;
FAutoConsoleVariableRef CVarGeometryCollectionUseRootBrokenFlag(
	TEXT("p.GeometryCollection.UseRootBrokenFlag"),
	bGeometryCollectionUseRootBrokenFlag,
	TEXT("If enabled, check if the root transform is broken in the proxy and disable the GT particle if so. Should be enabled - cvar is a failsafe to revert behaviour"));

bool bPropagateInternalClusterDisableFlagToChildren = true;
FAutoConsoleVariableRef CVarPropagateInternalClusterDisableFlagToChildren(
	TEXT("p.GeometryCollection.PropagateInternalClusterDisableFlagToChildren"),
	bPropagateInternalClusterDisableFlagToChildren,

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

Scope (from outer to inner):

file
function     bool FGeometryCollectionPhysicsProxy::PullNonInterpolatableDataFromSinglePhysicsState

Source code excerpt:

	// NOTE: We should never be returning to unbroken once broken although we aren't checking for that...
	const int32 RootIndex = Parameters.InitialRootIndex;
	if ((RootIndex != INDEX_NONE) && CurrentResults.IsRootBroken && GameThreadCollection.Active[RootIndex] && bGeometryCollectionUseRootBrokenFlag)
	{
		GameThreadCollection.Active[RootIndex] = false;
		const int32 ParticleIndex = FromTransformToParticleIndex[RootIndex];
		check(ParticleIndex != INDEX_NONE);
		if (GTParticles[ParticleIndex] != nullptr)
		{