p.Chaos.ClusterUnion.DoNotAddEmptyClusters

p.Chaos.ClusterUnion.DoNotAddEmptyClusters

#Overview

name: p.Chaos.ClusterUnion.DoNotAddEmptyClusters

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.ClusterUnion.DoNotAddEmptyClusters is to gate a risky bug fix in the Chaos physics system, specifically related to cluster unions in Unreal Engine 5.

This setting variable is primarily used in the Chaos physics subsystem, which is part of the Experimental module in Unreal Engine 5. It’s specifically related to the ClusterUnion functionality within Chaos.

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

The associated variable bChaosClusterUnionDoNotAddEmptyClusters directly interacts with p.Chaos.ClusterUnion.DoNotAddEmptyClusters. They share the same value, with bChaosClusterUnionDoNotAddEmptyClusters being the actual boolean variable used in the code logic.

Developers must be aware that this variable is gating a risky bug fix. When set to true, it prevents the addition of empty clusters to the cluster union. This behavior is particularly important in handling edge cases, such as when receiving an AddComponentToCluster operation on the same frame as a GC repdata that breaks all particles and releases its children.

Best practices when using this variable include:

  1. Carefully consider the implications of changing its value, as it affects the behavior of the cluster union system.
  2. Monitor the performance and stability of the physics system when modifying this variable.
  3. Use it in conjunction with thorough testing, especially in multiplayer scenarios where client-server synchronization is crucial.

Regarding the associated variable bChaosClusterUnionDoNotAddEmptyClusters:

This boolean variable is the actual implementation of the console variable p.Chaos.ClusterUnion.DoNotAddEmptyClusters. It’s used directly in the code logic, specifically in the HandleAddOperation function of the FClusterUnionManager class.

The purpose of bChaosClusterUnionDoNotAddEmptyClusters is to control whether empty clusters should be added to the cluster union. When set to true, it prevents the addition of clusters that are considered “broken” or empty.

This variable is crucial in handling edge cases in the Chaos physics system, particularly in networked environments where the timing of operations and data replication can lead to inconsistent states.

Developers should be aware that this variable directly affects the behavior of the ClusterUnion system. Changing its value could have significant impacts on physics simulations, especially in scenarios involving complex clustered objects or networked gameplay.

Best practices for using bChaosClusterUnionDoNotAddEmptyClusters include:

  1. Thoroughly testing any changes to its value across various gameplay scenarios.
  2. Monitoring physics performance and stability when modifying this variable.
  3. Considering its impact on both client and server-side physics simulations in networked games.
  4. Documenting any changes made to this variable, as it affects a core behavior of the Chaos physics system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ClusterUnionManager.cpp:27

Scope (from outer to inner):

file
namespace    Chaos
namespace    anonymous

Source code excerpt:

		bool bChaosClusterUnionDoNotAddEmptyClusters = true;
		FAutoConsoleVariableRef CVarChaosClusterUnionDoNotAddEmptyClusters(
			TEXT("p.Chaos.ClusterUnion.DoNotAddEmptyClusters"),
			bChaosClusterUnionDoNotAddEmptyClusters,
			TEXT("Gating a risky bug fix.")
		);

		FRigidTransform3 GetParticleRigidFrameInClusterUnion(FPBDRigidParticleHandle* Child, const FRigidTransform3& ClusterWorldTM)
		{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ClusterUnionManager.cpp:25

Scope (from outer to inner):

file
namespace    Chaos
namespace    anonymous

Source code excerpt:


		// @tmp: To be removed
		bool bChaosClusterUnionDoNotAddEmptyClusters = true;
		FAutoConsoleVariableRef CVarChaosClusterUnionDoNotAddEmptyClusters(
			TEXT("p.Chaos.ClusterUnion.DoNotAddEmptyClusters"),
			bChaosClusterUnionDoNotAddEmptyClusters,
			TEXT("Gating a risky bug fix.")
		);

		FRigidTransform3 GetParticleRigidFrameInClusterUnion(FPBDRigidParticleHandle* Child, const FRigidTransform3& ClusterWorldTM)
		{
			FRigidTransform3 Frame = FRigidTransform3::Identity;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ClusterUnionManager.cpp:605

Scope (from outer to inner):

file
namespace    Chaos
function     void FClusterUnionManager::HandleAddOperation

Source code excerpt:

				// This can happen on the client if we receive an AddComponentToCluster on the same frame when we receive a GC repdata
				// that breaks all the particles and releases its children. Unfortunately the Add operation has already been queued
				if (bChaosClusterUnionDoNotAddEmptyClusters)
				{
					const bool bIsClusterThatHadChildren = (ClusterHandle->GetParticleType() == EParticleType::Clustered);
					if (bIsClusterThatHadChildren && (ClusterHandle->Parent() == nullptr) && ClusterHandle->Disabled() && (ClusterHandle->ClusterIds().NumChildren == 0))
					{
						UE_LOG(LogChaos, Verbose, TEXT("FClusterUnionManager::HandleAddOperation rejecting particle because it is 'broken' %s"), *ClusterHandle->GetDebugName());
						continue;