p.Chaos.ImmPhys.DisableInactiveByIndex

p.Chaos.ImmPhys.DisableInactiveByIndex

#Overview

name: p.Chaos.ImmPhys.DisableInactiveByIndex

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.ImmPhys.DisableInactiveByIndex is to control the method of disabling inactive bodies in the Chaos Immediate Physics system. This setting variable is part of the physics simulation subsystem in Unreal Engine 5, specifically for the Chaos physics engine.

The Unreal Engine subsystem that relies on this setting variable is the Immediate Physics simulation within the Chaos physics engine. This can be seen from the file location and the namespace used in the code snippets provided.

The value of this variable is set through a console variable, as evidenced by the FAutoConsoleVariableRef declaration. This allows developers to change the value at runtime or through configuration files.

This variable interacts directly with its associated variable ChaosImmediate_DisableInactiveByIndex. They share the same value and are used interchangeably in the code.

Developers must be aware that when this variable is set to a non-zero value, the system will disable inactive bodies based on their index rather than just their count. This can affect the performance and behavior of the physics simulation.

Best practices when using this variable include:

  1. Consider the performance implications of enabling this feature, as it may require additional processing to check indices.
  2. Use this setting when you need more fine-grained control over which bodies are disabled.
  3. Test thoroughly to ensure that the desired physics behavior is achieved when this setting is enabled.

Regarding the associated variable ChaosImmediate_DisableInactiveByIndex:

The purpose of ChaosImmediate_DisableInactiveByIndex is the same as p.Chaos.ImmPhys.DisableInactiveByIndex, as they share the same value and functionality.

It is used within the Chaos Immediate Physics system to determine how inactive bodies are disabled.

The value of this variable is set to 1 by default, as seen in the code snippet.

This variable is directly used in the SetNumActiveBodies function of the FSimulation class to control the logic for enabling or disabling bodies based on their activity status.

Developers should be aware that changing this value will affect how the physics simulation handles inactive bodies, potentially impacting performance and simulation accuracy.

Best practices for using this variable include:

  1. Consider leaving it at the default value of 1 unless there’s a specific need to change it.
  2. If changed, thoroughly test the physics simulation to ensure desired behavior is maintained.
  3. Use in conjunction with other Chaos Immediate Physics settings for optimal performance and accuracy.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ImmediatePhysics/ImmediatePhysicsChaos/ImmediatePhysicsSimulation_Chaos.cpp:50

Scope: file

Source code excerpt:

FAutoConsoleVariableRef CVarChaosImmPhysVelocityIterations(TEXT("p.Chaos.ImmPhys.VelocityIterations"), ChaosImmediate_Evolution_VelocityIterations, TEXT("Override number of velocity iteration loops in immediate physics (if >= 0)"));
FAutoConsoleVariableRef CVarChaosImmPhysProjectionIterations(TEXT("p.Chaos.ImmPhys.ProjectionIterations"), ChaosImmediate_Evolution_ProjectionIterations, TEXT("Override number of projection iteration loops in immediate physics (if >= 0)"));
FAutoConsoleVariableRef CVarChaosImmPhysDisableInactiveByIndex(TEXT("p.Chaos.ImmPhys.DisableInactiveByIndex"), ChaosImmediate_DisableInactiveByIndex, TEXT("Disable bodies that are no longer active based on the index, rather than just count."));
FAutoConsoleVariableRef CVarChaosImmPhysNumCollisionsPerBlock(TEXT("p.Chaos.ImmPhys.NumCollisionsPerBlock"), ChaosImmediate_Evolution_NumCollisionsPerBlock, TEXT("The number of collision in a block in the collision pool. Higher values give better cache efficieny but waste memory if you do not need that many"));

Chaos::FRealSingle ChaosImmediate_Evolution_SimSpaceCentrifugalAlpha = 1.0f;
Chaos::FRealSingle ChaosImmediate_Evolution_SimSpaceCoriolisAlpha = 0.5f;
Chaos::FRealSingle ChaosImmediate_Evolution_SimSpaceEulerAlpha = 1.0f;
FAutoConsoleVariableRef CVarChaosImmPhysSimSpaceCentrifugalAlpha(TEXT("p.Chaos.ImmPhys.SimSpaceCentrifugalAlpha"), ChaosImmediate_Evolution_SimSpaceCentrifugalAlpha, TEXT("Settings for simulation space system for rigid body nodes"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ImmediatePhysics/ImmediatePhysicsChaos/ImmediatePhysicsSimulation_Chaos.cpp:41

Scope: file

Source code excerpt:

int32 ChaosImmediate_Evolution_VelocityIterations = -1;
int32 ChaosImmediate_Evolution_ProjectionIterations = -1;
int32 ChaosImmediate_DisableInactiveByIndex = 1;
int32 ChaosImmediate_Evolution_NumCollisionsPerBlock = 50;
FAutoConsoleVariableRef CVarChaosImmPhysStepTime(TEXT("p.Chaos.ImmPhys.StepTime"), ChaosImmediate_Evolution_StepTime, TEXT("Override step time (if not zero)"));
FAutoConsoleVariableRef CVarChaosImmPhysNumSteps(TEXT("p.Chaos.ImmPhys.NumSteps"), ChaosImmediate_Evolution_NumSteps, TEXT("Override num steps (if not zero)"));
FAutoConsoleVariableRef CVarChaosImmPhysInitialStepTime(TEXT("p.Chaos.ImmPhys.InitialStepTime"), ChaosImmediate_Evolution_InitialStepTime, TEXT("Initial step time (then calculated from rolling average)"));
FAutoConsoleVariableRef CVarChaosImmPhysDeltaTimeCount(TEXT("p.Chaos.ImmPhys.DeltaTimeCount"), ChaosImmediate_Evolution_DeltaTimeCount, TEXT("The number of ticks over which the moving average is calculated"));
FAutoConsoleVariableRef CVarChaosImmPhysPositionIterations(TEXT("p.Chaos.ImmPhys.PositionIterations"), ChaosImmediate_Evolution_PositionIterations, TEXT("Override number of position iteration loops in immediate physics (if >= 0)"));
FAutoConsoleVariableRef CVarChaosImmPhysVelocityIterations(TEXT("p.Chaos.ImmPhys.VelocityIterations"), ChaosImmediate_Evolution_VelocityIterations, TEXT("Override number of velocity iteration loops in immediate physics (if >= 0)"));
FAutoConsoleVariableRef CVarChaosImmPhysProjectionIterations(TEXT("p.Chaos.ImmPhys.ProjectionIterations"), ChaosImmediate_Evolution_ProjectionIterations, TEXT("Override number of projection iteration loops in immediate physics (if >= 0)"));
FAutoConsoleVariableRef CVarChaosImmPhysDisableInactiveByIndex(TEXT("p.Chaos.ImmPhys.DisableInactiveByIndex"), ChaosImmediate_DisableInactiveByIndex, TEXT("Disable bodies that are no longer active based on the index, rather than just count."));
FAutoConsoleVariableRef CVarChaosImmPhysNumCollisionsPerBlock(TEXT("p.Chaos.ImmPhys.NumCollisionsPerBlock"), ChaosImmediate_Evolution_NumCollisionsPerBlock, TEXT("The number of collision in a block in the collision pool. Higher values give better cache efficieny but waste memory if you do not need that many"));

Chaos::FRealSingle ChaosImmediate_Evolution_SimSpaceCentrifugalAlpha = 1.0f;
Chaos::FRealSingle ChaosImmediate_Evolution_SimSpaceCoriolisAlpha = 0.5f;
Chaos::FRealSingle ChaosImmediate_Evolution_SimSpaceEulerAlpha = 1.0f;
FAutoConsoleVariableRef CVarChaosImmPhysSimSpaceCentrifugalAlpha(TEXT("p.Chaos.ImmPhys.SimSpaceCentrifugalAlpha"), ChaosImmediate_Evolution_SimSpaceCentrifugalAlpha, TEXT("Settings for simulation space system for rigid body nodes"));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ImmediatePhysics/ImmediatePhysicsChaos/ImmediatePhysicsSimulation_Chaos.cpp:556

Scope (from outer to inner):

file
namespace    ImmediatePhysics_Chaos
function     void FSimulation::SetNumActiveBodies

Source code excerpt:

	void FSimulation::SetNumActiveBodies(int32 InNumActiveActorHandles, TArray<int32> ActiveBodyIndices)
	{
		if (InNumActiveActorHandles == Implementation->NumActiveDynamicActorHandles && ChaosImmediate_DisableInactiveByIndex == 0)
		{
			return;
		}

		// @todo(ccaulfield): can be optimized, but I think we end up with kinematic at the start and statics at the end of the 
		// list - maybe split them up or put kinematics at the end (in a way that does not impact particle order).

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/ImmediatePhysics/ImmediatePhysicsChaos/ImmediatePhysicsSimulation_Chaos.cpp:571

Scope (from outer to inner):

file
namespace    ImmediatePhysics_Chaos
function     void FSimulation::SetNumActiveBodies

Source code excerpt:

				continue;
			}
			if (ChaosImmediate_DisableInactiveByIndex != 0)
			{
				if (ActiveBodyIndices.Contains(ActorHandleIndex))
				{
					Handle->SetEnabled(true);
					++Implementation->NumActiveDynamicActorHandles;
				}