p.KinematicDeferralCheckValidBodies

p.KinematicDeferralCheckValidBodies

#Overview

name: p.KinematicDeferralCheckValidBodies

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.KinematicDeferralCheckValidBodies is to control whether the physics system should check for valid bodies before attempting to update deferred kinematic skeletal mesh bodies. This setting is primarily used in the physics engine’s kinematic deferral system, which is part of Unreal Engine’s Chaos physics implementation.

This setting variable is mainly used in the Chaos physics subsystem, specifically within the FPhysScene_Chaos class, which is part of the Engine module. It is primarily utilized in the UpdateKinematicsOnDeferredSkelMeshes() function.

The value of this variable is set through a console variable (CVar) system, allowing it to be changed at runtime. It is initialized to true by default.

This variable interacts closely with another variable named GKinematicDeferralLogInvalidBodies. When both are true, the system will log warnings about invalid bodies encountered during kinematic updates.

Developers should be aware that:

  1. This variable affects performance and safety checks in the physics system.
  2. Disabling this check might lead to attempting updates on invalid or deleted physics bodies, potentially causing crashes or undefined behavior.
  3. Enabling this check adds some overhead but provides better stability and easier debugging.

Best practices when using this variable include:

  1. Keep it enabled (true) during development and testing to catch potential issues early.
  2. Consider disabling it in shipping builds if performance is critical and you’re confident that no invalid bodies will be encountered.
  3. Use in conjunction with p.KinematicDeferralLogInvalidBodies for more detailed debugging information.

Regarding the associated variable GKinematicDeferralCheckValidBodies:

This is the actual boolean variable that stores the state controlled by the p.KinematicDeferralCheckValidBodies console variable. It serves the same purpose as described above and is used directly in the C++ code to perform the validity checks.

The value of GKinematicDeferralCheckValidBodies is set by the console variable system and is used in multiple locations within the UpdateKinematicsOnDeferredSkelMeshes() function to guard against operations on potentially invalid bodies or actor handles.

Developers should treat GKinematicDeferralCheckValidBodies as the internal representation of the p.KinematicDeferralCheckValidBodies setting. They should not modify GKinematicDeferralCheckValidBodies directly but instead use the console variable to change its value.

Best practices for GKinematicDeferralCheckValidBodies are the same as for p.KinematicDeferralCheckValidBodies, as they are essentially two sides of the same coin - one being the console-accessible setting, and the other being its in-code representation.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/Experimental/PhysScene_Chaos.cpp:52

Scope: file

Source code excerpt:


bool GKinematicDeferralCheckValidBodies = true;
FAutoConsoleVariableRef CVar_KinematicDeferralCheckValidBodies(TEXT("p.KinematicDeferralCheckValidBodies"), GKinematicDeferralCheckValidBodies, TEXT("If true, don't attempt to update deferred kinematic skeletal mesh bodies which are pending delete."));

bool GKinematicDeferralUpdateExternalAccelerationStructure = false;
FAutoConsoleVariableRef CVar_KinematicDeferralUpdateExternalAccelerationStructure(TEXT("p.KinematicDeferralUpdateExternalAccelerationStructure"), GKinematicDeferralUpdateExternalAccelerationStructure, TEXT("If true, process any operations in PendingSpatialOperations_External before doing deferred kinematic updates."));
bool GKinematicDeferralLogInvalidBodies = false;
FAutoConsoleVariableRef CVar_KinematicDeferralLogInvalidBodies(TEXT("p.KinematicDeferralLogInvalidBodies"), GKinematicDeferralLogInvalidBodies, TEXT("If true and p.KinematicDeferralCheckValidBodies is true, log when an invalid body is found on kinematic update."));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/Experimental/PhysScene_Chaos.cpp:51

Scope: file

Source code excerpt:

FAutoConsoleVariableRef CVar_EnableKinematicDeferralStartPhysicsCondition(TEXT("p.EnableKinematicDeferralStartPhysicsCondition"), GEnableKinematicDeferralStartPhysicsCondition, TEXT("If is 1, allow kinematics to be deferred in start physics (probably only called from replication tick). If 0, no deferral in startphysics."));

bool GKinematicDeferralCheckValidBodies = true;
FAutoConsoleVariableRef CVar_KinematicDeferralCheckValidBodies(TEXT("p.KinematicDeferralCheckValidBodies"), GKinematicDeferralCheckValidBodies, TEXT("If true, don't attempt to update deferred kinematic skeletal mesh bodies which are pending delete."));

bool GKinematicDeferralUpdateExternalAccelerationStructure = false;
FAutoConsoleVariableRef CVar_KinematicDeferralUpdateExternalAccelerationStructure(TEXT("p.KinematicDeferralUpdateExternalAccelerationStructure"), GKinematicDeferralUpdateExternalAccelerationStructure, TEXT("If true, process any operations in PendingSpatialOperations_External before doing deferred kinematic updates."));
bool GKinematicDeferralLogInvalidBodies = false;
FAutoConsoleVariableRef CVar_KinematicDeferralLogInvalidBodies(TEXT("p.KinematicDeferralLogInvalidBodies"), GKinematicDeferralLogInvalidBodies, TEXT("If true and p.KinematicDeferralCheckValidBodies is true, log when an invalid body is found on kinematic update."));

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/Experimental/PhysScene_Chaos.cpp:1857

Scope (from outer to inner):

file
function     void FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMeshes

Source code excerpt:

				{
					FBodyInstance* BodyInst = SkelComp->Bodies[i];
					if (GKinematicDeferralCheckValidBodies && (BodyInst == nullptr || !BodyInst->IsValidBodyInstance()))
					{
						if (GKinematicDeferralLogInvalidBodies)
						{
							UE_LOG(LogChaos, Warning, TEXT("\n"
								"Invalid FBodyInstance in FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMesh - Gathering Proxies\n"
								"SkeletalMesh: %s\n"

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/Experimental/PhysScene_Chaos.cpp:1872

Scope (from outer to inner):

file
function     void FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMeshes

Source code excerpt:


					FPhysicsActorHandle& ActorHandle = BodyInst->ActorHandle;
					if (GKinematicDeferralCheckValidBodies && (ActorHandle == nullptr || ActorHandle->GetSyncTimestamp() == nullptr || ActorHandle->GetMarkedDeleted()))
					{
						if (GKinematicDeferralLogInvalidBodies)
						{
							UE_LOG(LogChaos, Warning, TEXT("\n"
								"Invalid FPhysicsActorHandle in FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMesh - Gathering Proxies\n"
								"SkeletalMesh: %s\n"

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/Experimental/PhysScene_Chaos.cpp:1942

Scope (from outer to inner):

file
function     void FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMeshes
lambda-function

Source code excerpt:

				{
					FBodyInstance* BodyInst = SkelComp->Bodies[i];
					if (GKinematicDeferralCheckValidBodies && (BodyInst == nullptr || !BodyInst->IsValidBodyInstance()))
					{
						if (GKinematicDeferralLogInvalidBodies)
						{
							UE_LOG(LogChaos, Warning, TEXT("\n"
								"Invalid FBodyInstance in FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMesh - Add to Teleport Pool\n"
								"SkeletalMesh: %s\n"

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PhysicsEngine/Experimental/PhysScene_Chaos.cpp:1957

Scope (from outer to inner):

file
function     void FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMeshes
lambda-function

Source code excerpt:


					FPhysicsActorHandle& ActorHandle = BodyInst->ActorHandle;
					if (GKinematicDeferralCheckValidBodies && (ActorHandle == nullptr || ActorHandle->GetSyncTimestamp() == nullptr || ActorHandle->GetMarkedDeleted()))
					{
						if (GKinematicDeferralLogInvalidBodies)
						{
							UE_LOG(LogChaos, Warning, TEXT("\n"
								"Invalid FPhysicsActorHandle in FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMesh - Add to Teleport Pool\n"
								"SkeletalMesh: %s\n"