p.Chaos.AccelerationStructureIsolateQueryOnlyObjects

p.Chaos.AccelerationStructureIsolateQueryOnlyObjects

#Overview

name: p.Chaos.AccelerationStructureIsolateQueryOnlyObjects

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

It is referenced in 7 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.AccelerationStructureIsolateQueryOnlyObjects is to control the handling of query-only objects in the Chaos physics engine’s acceleration structures. It is primarily used for optimization in the physics simulation system.

This setting variable is primarily used in the Chaos physics engine, which is part of Unreal Engine’s experimental physics system. It is referenced in the following modules:

  1. Chaos (Experimental): The core physics simulation module
  2. PhysicsCore: The interface between the engine and the physics system

The value of this variable is set as a console variable (CVar) with a default value of 0. It can be changed at runtime through the console or configuration files.

This variable interacts closely with other acceleration structure-related variables, particularly AccelerationStructureSplitStaticAndDynamic. Together, they control how objects are organized in the physics simulation’s spatial acceleration structures.

Developers should be aware that:

  1. When set to 1, query-only objects will not be moved to acceleration structures on the Physics Thread.
  2. This setting can impact performance and simulation behavior, especially in scenes with many query-only objects.
  3. It works in conjunction with AccelerationStructureSplitStaticAndDynamic to determine how objects are sorted into different acceleration structures.

Best practices when using this variable include:

  1. Test performance with both 0 and 1 settings to determine which works best for your specific use case.
  2. Consider the number and distribution of query-only objects in your scene when deciding whether to enable this feature.
  3. Monitor physics performance metrics when changing this setting to ensure it’s having the desired effect.

Regarding the associated variable AccelerationStructureIsolateQueryOnlyObjects:

This is the actual int32 variable that stores the value set by the console variable. It’s used directly in the code to control the behavior of the acceleration structures. The purpose and usage are the same as described for the console variable. Developers should be aware that modifying this variable directly in code will override the console variable setting, so it’s generally better to use the console variable for configuration unless there’s a specific need to change it programmatically.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolution.cpp:34

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:


	CHAOS_API int32 AccelerationStructureIsolateQueryOnlyObjects = 0;
	FAutoConsoleVariableRef CVarAccelerationStructureIsolateQueryOnlyObjects(TEXT("p.Chaos.AccelerationStructureIsolateQueryOnlyObjects"), AccelerationStructureIsolateQueryOnlyObjects, TEXT("Set to 1: QueryOnly Objects will not be moved to acceleration structures on the Physics Thread"));

	CHAOS_API int32 AccelerationStructureSplitStaticAndDynamic = 1;
	FAutoConsoleVariableRef CVarAccelerationStructureSplitStaticAndDynamic(TEXT("p.Chaos.AccelerationStructureSplitStaticDynamic"), AccelerationStructureSplitStaticAndDynamic, TEXT("Set to 1: Sort Dynamic and Static bodies into seperate acceleration structures, any other value will disable the feature"));

	CHAOS_API int32 AccelerationStructureUseDynamicTree = 1;
	FAutoConsoleVariableRef CVarAccelerationStructureUseDynamicTree(TEXT("p.Chaos.AccelerationStructureUseDynamicTree"), AccelerationStructureUseDynamicTree, TEXT("Use a dynamic BVH tree structure for dynamic objects"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolution.cpp:33

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

	FAutoConsoleVariableRef CVarFixBadAccelerationStructureRemoval(TEXT("p.FixBadAccelerationStructureRemoval"), FixBadAccelerationStructureRemoval, TEXT(""));

	CHAOS_API int32 AccelerationStructureIsolateQueryOnlyObjects = 0;
	FAutoConsoleVariableRef CVarAccelerationStructureIsolateQueryOnlyObjects(TEXT("p.Chaos.AccelerationStructureIsolateQueryOnlyObjects"), AccelerationStructureIsolateQueryOnlyObjects, TEXT("Set to 1: QueryOnly Objects will not be moved to acceleration structures on the Physics Thread"));

	CHAOS_API int32 AccelerationStructureSplitStaticAndDynamic = 1;
	FAutoConsoleVariableRef CVarAccelerationStructureSplitStaticAndDynamic(TEXT("p.Chaos.AccelerationStructureSplitStaticDynamic"), AccelerationStructureSplitStaticAndDynamic, TEXT("Set to 1: Sort Dynamic and Static bodies into seperate acceleration structures, any other value will disable the feature"));

	CHAOS_API int32 AccelerationStructureUseDynamicTree = 1;
	FAutoConsoleVariableRef CVarAccelerationStructureUseDynamicTree(TEXT("p.Chaos.AccelerationStructureUseDynamicTree"), AccelerationStructureUseDynamicTree, TEXT("Use a dynamic BVH tree structure for dynamic objects"));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolution.cpp:92

Scope (from outer to inner):

file
namespace    Chaos
function     TUniquePtr<ISpatialAccelerationCollection<FAccelerationStructureHandle, FReal, 3>> CreateEmptyCollection

Source code excerpt:


				// Always create this if QueryOnlyObjects are isolated to ensure all consecutive indices are created (within buckets)
				if (AccelerationStructureSplitStaticAndDynamic == 1 || AccelerationStructureIsolateQueryOnlyObjects == 1) 
				{
					// Non static bodies
					Collection->AddSubstructure(CreateAccelerationPerBucket_Threaded(Empty, BucketIdx, true, IsDynamicTree(FSpatialAccelerationIdx{BucketIdx, ESpatialAccelerationCollectionBucketInnerIdx::Dynamic }), true), BucketIdx, ESpatialAccelerationCollectionBucketInnerIdx::Dynamic);
				}
			}

			if (AccelerationStructureIsolateQueryOnlyObjects && NumBuckets == 1)
			{
				constexpr uint16 BucketIdx = 0;
				Collection->AddSubstructure(CreateAccelerationPerBucket_Threaded(Empty, BucketIdx, true, false, false), BucketIdx, ESpatialAccelerationCollectionBucketInnerIdx::DefaultQueryOnly);
				if (AccelerationStructureSplitStaticAndDynamic == 1)
				{
					// Non static bodies

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

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

namespace Chaos{
	extern int32 AccelerationStructureSplitStaticAndDynamic;
	extern int32 AccelerationStructureIsolateQueryOnlyObjects;
}

float CollisionParticlesPerObjectFractionDefault = 1.0f;
FAutoConsoleVariableRef CVarCollisionParticlesPerObjectFractionDefault(
	TEXT("p.CollisionParticlesPerObjectFractionDefault"), 
	CollisionParticlesPerObjectFractionDefault,

#Loc: <Workspace>/Engine/Source/Runtime/PhysicsCore/Private/ChaosEngineInterface.cpp:34

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

{
	extern CHAOS_API int32 AccelerationStructureSplitStaticAndDynamic;
	extern CHAOS_API int32 AccelerationStructureIsolateQueryOnlyObjects;
	extern CHAOS_API int32 SyncKinematicOnGameThread;
}

bool bEnableChaosJointConstraints = true;
FAutoConsoleVariableRef CVarEnableChaosJointConstraints(TEXT("p.ChaosSolverEnableJointConstraints"), bEnableChaosJointConstraints, TEXT("Enable Joint Constraints defined within the Physics Asset Editor"));

#Loc: <Workspace>/Engine/Source/Runtime/PhysicsCore/Private/ChaosEngineInterface.cpp:2085

Scope (from outer to inner):

file
function     void FChaosEngineInterface::CreateActor

Source code excerpt:

		if (AccelerationStructureSplitStaticAndDynamic == 1)
		{
			if (AccelerationStructureIsolateQueryOnlyObjects == 1)
			{
				if (InParams.bStatic && InParams.bQueryOnly)
				{
					SpatialIndex = FSpatialAccelerationIdx{0, ESpatialAccelerationCollectionBucketInnerIdx::DefaultQueryOnly};
				}
				else if (!InParams.bStatic && InParams.bQueryOnly)

#Loc: <Workspace>/Engine/Source/Runtime/PhysicsCore/Private/ChaosEngineInterface.cpp:2110

Scope (from outer to inner):

file
function     void FChaosEngineInterface::CreateActor

Source code excerpt:

		else
		{
			if (AccelerationStructureIsolateQueryOnlyObjects == 1)
			{
				if (InParams.bQueryOnly)
				{
					SpatialIndex = FSpatialAccelerationIdx{ 0, ESpatialAccelerationCollectionBucketInnerIdx::DefaultQueryOnly };
				}
			}