p.Chaos.DebugDraw.ColorShapesByClusterUnion

p.Chaos.DebugDraw.ColorShapesByClusterUnion

#Overview

name: p.Chaos.DebugDraw.ColorShapesByClusterUnion

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.DebugDraw.ColorShapesByClusterUnion is to control the debug visualization of shapes in the Chaos physics system, specifically for coloring shapes based on their cluster union membership.

This setting variable is part of the Chaos physics system in Unreal Engine 5, which is an experimental physics engine. It is primarily used in the debug drawing functionality of Chaos, as evidenced by its location in the ChaosDebugDraw.cpp file.

The value of this variable is set through the Unreal Engine console variable system. It is declared as a boolean variable (bChaosDebugDebugDrawColorShapesByClusterUnion) and associated with the console variable “p.Chaos.DebugDraw.ColorShapesByClusterUnion” using FAutoConsoleVariableRef.

This variable interacts closely with the Chaos physics system’s clustering feature. When enabled, it extends the functionality of the ColorShapesByInternalCluster option. Instead of using a single color for every internal cluster, it uses a unique color per cluster union. Shapes that are not part of any cluster union are colored black.

Developers should be aware that this is a debug visualization tool and should only be used during development and debugging phases. It’s not intended for use in shipping game builds. Also, enabling this feature might have a performance impact, especially in scenes with many physics objects.

Best practices when using this variable include:

  1. Use it in conjunction with other Chaos debug drawing tools for a comprehensive view of the physics state.
  2. Be mindful of the performance impact when enabling this in complex scenes.
  3. Use this feature to verify the correct grouping of objects into cluster unions.

Regarding the associated variable bChaosDebugDebugDrawColorShapesByClusterUnion:

This is the actual boolean variable that stores the state of the debug drawing option. It is initialized to false by default, meaning this debug visualization is off unless explicitly enabled.

The variable is used in the DrawShapesImpl function to determine how to color shapes during debug drawing. If enabled and the particle is a clustered particle belonging to a cluster union, it will assign a unique color based on the cluster group index.

Developers should note that this variable directly controls the behavior specified by the console variable. Changes to this variable at runtime will immediately affect the debug visualization of cluster unions in 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/ChaosDebugDraw.cpp:70

Scope (from outer to inner):

file
namespace    Chaos
namespace    DebugDraw

Source code excerpt:


		bool bChaosDebugDebugDrawColorShapesByClusterUnion = false;
		FAutoConsoleVariableRef CVarChaosDebugDebugDrawColorShapesByClusterUnion(TEXT("p.Chaos.DebugDraw.ColorShapesByClusterUnion"), bChaosDebugDebugDrawColorShapesByClusterUnion, TEXT("An extension of the ColorShapesByInternalCluster option: instead of using a single color for every internal cluster, will use a unique color per cluster union. Non-cluster unions will be black."));

		bool bChaosDebugDebugDrawColorBoundsByShapeType = false;
		FAutoConsoleVariableRef CVarChaosDebugDebugDrawColorBoundsByShapeType(TEXT("p.Chaos.DebugDraw.ColorBoundsByShapeType"), bChaosDebugDebugDrawColorBoundsByShapeType, TEXT("Whether to use shape type to define the color of the bounds instead of using the particle state (if multiple shapes , will use the first one)"));

		bool bChaosDebugDebugDrawShowQueryOnlyShapes = true;
		FAutoConsoleVariableRef CVarChaosDebugDebugDrawShowQueryOnlyShapes(TEXT("p.Chaos.DebugDraw.ShowQueryOnly"), bChaosDebugDebugDrawShowQueryOnlyShapes, TEXT("Whether to show QueryOnly shapes"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ChaosDebugDraw.cpp:69

Scope (from outer to inner):

file
namespace    Chaos
namespace    DebugDraw

Source code excerpt:

		FAutoConsoleVariableRef CVarChaosDebugDebugDrawColorShapesByConvexType(TEXT("p.Chaos.DebugDraw.ColorShapesByConvexType"), bChaosDebugDebugDrawColorShapesByConvexType, TEXT("Whether to show with different colors shapes that are convex and simplified (simplified : green, normal : orange)"));

		bool bChaosDebugDebugDrawColorShapesByClusterUnion = false;
		FAutoConsoleVariableRef CVarChaosDebugDebugDrawColorShapesByClusterUnion(TEXT("p.Chaos.DebugDraw.ColorShapesByClusterUnion"), bChaosDebugDebugDrawColorShapesByClusterUnion, TEXT("An extension of the ColorShapesByInternalCluster option: instead of using a single color for every internal cluster, will use a unique color per cluster union. Non-cluster unions will be black."));

		bool bChaosDebugDebugDrawColorBoundsByShapeType = false;
		FAutoConsoleVariableRef CVarChaosDebugDebugDrawColorBoundsByShapeType(TEXT("p.Chaos.DebugDraw.ColorBoundsByShapeType"), bChaosDebugDebugDrawColorBoundsByShapeType, TEXT("Whether to use shape type to define the color of the bounds instead of using the particle state (if multiple shapes , will use the first one)"));

		bool bChaosDebugDebugDrawShowQueryOnlyShapes = true;
		FAutoConsoleVariableRef CVarChaosDebugDebugDrawShowQueryOnlyShapes(TEXT("p.Chaos.DebugDraw.ShowQueryOnly"), bChaosDebugDebugDrawShowQueryOnlyShapes, TEXT("Whether to show QueryOnly shapes"));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ChaosDebugDraw.cpp:784

Scope (from outer to inner):

file
namespace    Chaos
namespace    DebugDraw
function     void DrawShapesImpl

Source code excerpt:

					if (const FPBDRigidClusteredParticleHandle* ClusteredParticle = Particle->CastToClustered())
					{
						if (bChaosDebugDebugDrawColorShapesByClusterUnion)
						{
							if (ClusteredParticle->PhysicsProxy()->GetType() == EPhysicsProxyType::ClusterUnionProxy)
							{
								ShapeColor = GetIndexColor(FMath::Abs(ClusteredParticle->ClusterGroupIndex()));
							}
						}