p.KinematicDeferralUpdateExternalAccelerationStructure

p.KinematicDeferralUpdateExternalAccelerationStructure

#Overview

name: p.KinematicDeferralUpdateExternalAccelerationStructure

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.KinematicDeferralUpdateExternalAccelerationStructure is to control whether the physics engine processes operations in PendingSpatialOperations_External before performing deferred kinematic updates. This setting is primarily related to the physics system in Unreal Engine 5.

Based on the callsites, this setting variable is used in the Chaos physics engine, which is part of Unreal Engine’s physics subsystem. Specifically, it’s used in the FPhysScene_Chaos class, which is responsible for managing the physics scene in Chaos.

The value of this variable is set through an FAutoConsoleVariableRef, which means it can be changed at runtime through the console or configuration files. By default, it is set to false.

This variable interacts closely with other kinematic deferral-related variables, such as GKinematicDeferralCheckValidBodies and GKinematicDeferralLogInvalidBodies. These variables work together to control the behavior of deferred kinematic updates in the physics system.

Developers should be aware that enabling this variable may have performance implications. The comment in the code suggests that this feature was implemented to address a specific issue (FORT-564602) but is no longer needed and may be removed in future releases.

Best practices when using this variable include:

  1. Keeping it disabled (false) unless there’s a specific need to process external acceleration structure operations before kinematic updates.
  2. Monitoring performance when enabled, as it may introduce additional processing overhead.
  3. Being prepared for its potential removal in future engine versions, as indicated by the TODO comment in the code.

Regarding the associated variable GKinematicDeferralUpdateExternalAccelerationStructure:

This is the actual boolean variable that stores the value controlled by the p.KinematicDeferralUpdateExternalAccelerationStructure console variable. It’s used directly in the UpdateKinematicsOnDeferredSkelMeshes function of FPhysScene_Chaos to determine whether to call CopySolverAccelerationStructure().

The purpose of GKinematicDeferralUpdateExternalAccelerationStructure is the same as p.KinematicDeferralUpdateExternalAccelerationStructure, serving as the internal representation of the setting within the engine’s code.

Developers should treat this variable as read-only in their code, as its value is managed by the console variable system. Any changes to this variable should be made through the console variable p.KinematicDeferralUpdateExternalAccelerationStructure rather than directly modifying GKinematicDeferralUpdateExternalAccelerationStructure.

#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:55

Scope: file

Source code excerpt:


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."));

float GReplicationCacheLingerForNSeconds = 3.f;
FAutoConsoleVariableRef CVar_ReplicationCacheLingerForNSeconds(TEXT("np2.ReplicationCache.LingerForNSeconds"), GReplicationCacheLingerForNSeconds, TEXT("How long to keep data in the replication cache without the actor accessing it, after this we stop caching the actors state until it tries to access it again."));

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

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."));

float GReplicationCacheLingerForNSeconds = 3.f;
FAutoConsoleVariableRef CVar_ReplicationCacheLingerForNSeconds(TEXT("np2.ReplicationCache.LingerForNSeconds"), GReplicationCacheLingerForNSeconds, TEXT("How long to keep data in the replication cache without the actor accessing it, after this we stop caching the actors state until it tries to access it again."));

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

Scope (from outer to inner):

file
function     void FPhysScene_Chaos::UpdateKinematicsOnDeferredSkelMeshes

Source code excerpt:

	// (aka, FORT-564602)
	// Update: This fix was speculative and not needed anymore. The Gamethread Acceleration structure deletes should be up to date at this point, so no need to waste performance here.
	// Setting GKinematicDeferralUpdateExternalAccelerationStructure to false TODO: remove option entirely after a release
	if (GKinematicDeferralUpdateExternalAccelerationStructure)
	{
		CopySolverAccelerationStructure();
	}

	UpdateActorsInAccelerationStructure(TeleportActorsPool);