p.Chaos.Collision.UnionBVH.Enabled

p.Chaos.Collision.UnionBVH.Enabled

#Overview

name: p.Chaos.Collision.UnionBVH.Enabled

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

• type: Var
• help: Set to false to disable use of BVH during collision detection (without affecting creations and serialization)

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Collision.UnionBVH.Enabled is to control the creation and usage of Bounding Volume Hierarchies (BVHs) during collision detection in the Chaos physics system of Unreal Engine 5. Specifically, it enables or disables the use of BVHs for unions of implicit objects in collision detection.

This setting variable is primarily used in the Chaos physics system, which is part of Unreal Engine’s experimental features. It affects the collision detection subsystem within Chaos.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized to true by default but can be changed at runtime using the console command system.

The associated variable bChaosUnionBVHEnabled directly interacts with p.Chaos.Collision.UnionBVH.Enabled. They share the same value and are used interchangeably in the code.

Developers must be aware that:

1. Disabling this variable will prevent BVHs from being created or used in collision detection for unions of implicit objects.
2. This setting affects runtime behavior but does not impact the creation or serialization of BVHs.
3. The variable is part of the experimental Chaos system and its behavior may change in future engine versions.

Best practices when using this variable include:

1. Keep it enabled by default for better performance in scenes with complex geometry.
2. Consider disabling it only if you encounter specific issues related to BVH usage in collision detection.
3. Test thoroughly after changing this setting, as it can significantly impact collision detection performance and behavior.

Regarding the associated variable bChaosUnionBVHEnabled:

• It’s used internally within the Chaos physics system to control BVH usage.
• It’s checked in various parts of the collision detection code to determine whether to use BVHs.
• When working with the Chaos physics system, developers should use this variable to conditionally execute BVH-related code.
• Any changes to p.Chaos.Collision.UnionBVH.Enabled will be reflected in bChaosUnionBVHEnabled, so they should be treated as equivalent in terms of functionality.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ImplicitObjectUnion.cpp:17

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// Set to false to prevent BVHs from being created in collision detection (or used, if disabled in the runtime after creation)
		bool bChaosUnionBVHEnabled = true;
		FAutoConsoleVariableRef CVarChaosUnionBVHEnabled(TEXT("p.Chaos.Collision.UnionBVH.Enabled"), bChaosUnionBVHEnabled, TEXT("Set to false to disable use of BVH during collision detection (without affecting creations and serialization)"));

		// If a geometry hierarchy has more shapes than this, create a BVH around it
		int32 ChaosUnionBVHMinShapes = 10;
		FAutoConsoleVariableRef CVarChaosUnionBVHMinShapes(TEXT("p.Chaos.Collision.UnionBVH.NumShapes"), ChaosUnionBVHMinShapes, TEXT("If a geometry hierarchy has this many shapes, wrap it in a BVH for collision detection (negative to disable BVH)"));

		// Maximum BVH depth. In general we want the BVH to generate leafs with a single item in them

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Collision/ParticlePairMidPhase.cpp:1251

Scope (from outer to inner):

file
namespace    Chaos
function     int32 FGenericParticlePairMidPhase::GenerateCollisionsImpl

Source code excerpt:

		const Private::FImplicitBVH* BVH0 = nullptr;
		const Private::FImplicitBVH* BVH1 = nullptr;
		if (CVars::bChaosUnionBVHEnabled)
		{
			if (const FImplicitObjectUnion* Union0 = Implicit0->template AsA<FImplicitObjectUnion>())
			{
				const bool bHasConvexOptimizer0 = (ConvexOptimizer0 != nullptr) && ConvexOptimizer0->IsValid();
				if(!bHasConvexOptimizer0)
				{

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ConvexOptimizer.cpp:141

Scope (from outer to inner):

file
namespace    Chaos
namespace    Private
function     void FConvexOptimizer::SimplifyRootConvexes

Source code excerpt:

	}

	if(CVars::bChaosUnionBVHEnabled)
	{
		if(BVH.IsValid())
		{
			BVH.Reset();
		}
		BVH = FImplicitBVH::TryMakeFromLeaves(MoveTemp(CollisionObjects->ImplicitObjects), CVars::ChaosUnionBVHMinShapes, CVars::ChaosUnionBVHMaxDepth);

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ImplicitObjectUnion.cpp:16

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

	{
		// Set to false to prevent BVHs from being created in collision detection (or used, if disabled in the runtime after creation)
		bool bChaosUnionBVHEnabled = true;
		FAutoConsoleVariableRef CVarChaosUnionBVHEnabled(TEXT("p.Chaos.Collision.UnionBVH.Enabled"), bChaosUnionBVHEnabled, TEXT("Set to false to disable use of BVH during collision detection (without affecting creations and serialization)"));

		// If a geometry hierarchy has more shapes than this, create a BVH around it
		int32 ChaosUnionBVHMinShapes = 10;
		FAutoConsoleVariableRef CVarChaosUnionBVHMinShapes(TEXT("p.Chaos.Collision.UnionBVH.NumShapes"), ChaosUnionBVHMinShapes, TEXT("If a geometry hierarchy has this many shapes, wrap it in a BVH for collision detection (negative to disable BVH)"));

		// Maximum BVH depth. In general we want the BVH to generate leafs with a single item in them

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ImplicitObjectUnion.cpp:100

Scope (from outer to inner):

file
namespace    Chaos
function     bool FImplicitObjectUnion::HasValidBVH

Source code excerpt:

{
	// No need to create BVH if we are using the simple shape
	return BVH.IsValid() && CVars::bChaosUnionBVHEnabled;
}
	
void FImplicitObjectUnion::Combine(TArray<Chaos::FImplicitObjectPtr>& OtherObjects)
{
	ensure(MObjects.Num());

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/ImplicitObjectUnion.cpp:165

Scope (from outer to inner):

file
namespace    Chaos
function     void FImplicitObjectUnion::CreateBVH

Source code excerpt:

void FImplicitObjectUnion::CreateBVH()
{
	if (Flags.bAllowBVH && CVars::bChaosUnionBVHEnabled)
	{
		const int32 MinBVHShapes = CVars::ChaosUnionBVHMinShapes;
		const int32 MaxBVHDepth = CVars::ChaosUnionBVHMaxDepth;
		
		BVH = Private::FImplicitBVH::TryMake(MakeArrayView(MObjects), MinBVHShapes, MaxBVHDepth);
		Flags.bHasBVH = BVH.IsValid();

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Public/Chaos/ImplicitObjectUnion.h:20

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

namespace CVars
{
	extern bool bChaosUnionBVHEnabled;
}

class FImplicitObjectUnion : public FImplicitObject
{
  public: