p.ClusterUnion.SyncBodiesMoveNewComponents

p.ClusterUnion.SyncBodiesMoveNewComponents

#Overview

name: p.ClusterUnion.SyncBodiesMoveNewComponents

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.ClusterUnion.SyncBodiesMoveNewComponents is to control the behavior of synchronizing new components added to a cluster union in the Unreal Engine’s physics system, specifically in the Chaos physics engine.

This setting variable is primarily used in the physics engine subsystem of Unreal Engine 5, particularly in the Chaos physics implementation. It is referenced in the PhysScene_Chaos.cpp file, which is part of the Engine’s runtime physics module.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be modified at runtime through the console. By default, it is set to true.

The associated variable bGClusterUnionSyncBodiesMoveNewComponents directly interacts with p.ClusterUnion.SyncBodiesMoveNewComponents. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the behavior of newly added components in a cluster union. When set to true, it ensures that new components are moved once on addition, even if the cluster itself is not moving. This can be crucial for maintaining proper physics synchronization in complex scenes with dynamic object hierarchies.

Best practices when using this variable include:

  1. Keep it enabled (true) unless there’s a specific reason to disable it, as it helps maintain consistent physics behavior.
  2. If performance issues are observed in scenes with many cluster unions, consider disabling it temporarily for testing, but be aware of potential side effects on physics accuracy.
  3. Use it in conjunction with other cluster union-related settings for fine-tuning physics behavior.

Regarding the associated variable bGClusterUnionSyncBodiesMoveNewComponents:

The purpose of bGClusterUnionSyncBodiesMoveNewComponents is to serve as the actual boolean flag that controls the behavior defined by p.ClusterUnion.SyncBodiesMoveNewComponents.

This variable is used directly in the physics engine code, specifically in the FPhysScene_Chaos::OnSyncBodies function. It determines whether to synchronize the cluster union for newly added components, even when the cluster hasn’t moved.

The value of this variable is set by the console variable p.ClusterUnion.SyncBodiesMoveNewComponents through the FAutoConsoleVariableRef mechanism.

Developers should be aware that modifying p.ClusterUnion.SyncBodiesMoveNewComponents will directly affect the behavior controlled by bGClusterUnionSyncBodiesMoveNewComponents. They should treat these variables as two sides of the same coin when considering physics behavior in their game.

Best practices for using bGClusterUnionSyncBodiesMoveNewComponents include:

  1. Avoid modifying it directly in code; instead, use the console variable p.ClusterUnion.SyncBodiesMoveNewComponents to change its value.
  2. When debugging physics issues related to cluster unions, check the value of this variable to ensure it’s set as expected.
  3. Consider exposing this setting in debug menus or configuration files for easier tweaking during development and testing.

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

Scope: file

Source code excerpt:


bool bGClusterUnionSyncBodiesMoveNewComponents = true;
FAutoConsoleVariableRef CVar_GClusterUnionSyncBodiesCheckDirtyFlag(TEXT("p.ClusterUnion.SyncBodiesMoveNewComponents"), bGClusterUnionSyncBodiesMoveNewComponents, TEXT("Enable a fix to ensure new components in a cluster union are moved once on add (even if the cluster is not moving)."));

DECLARE_CYCLE_STAT(TEXT("Update Kinematics On Deferred SkelMeshes"), STAT_UpdateKinematicsOnDeferredSkelMeshesChaos, STATGROUP_Physics);

struct FPendingAsyncPhysicsCommand
{
	int32 PhysicsStep;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

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

bool bGClusterUnionSyncBodiesMoveNewComponents = true;
FAutoConsoleVariableRef CVar_GClusterUnionSyncBodiesCheckDirtyFlag(TEXT("p.ClusterUnion.SyncBodiesMoveNewComponents"), bGClusterUnionSyncBodiesMoveNewComponents, TEXT("Enable a fix to ensure new components in a cluster union are moved once on add (even if the cluster is not moving)."));

DECLARE_CYCLE_STAT(TEXT("Update Kinematics On Deferred SkelMeshes"), STAT_UpdateKinematicsOnDeferredSkelMeshesChaos, STATGROUP_Physics);

struct FPendingAsyncPhysicsCommand
{
	int32 PhysicsStep;

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

Scope (from outer to inner):

file
function     void FPhysScene_Chaos::OnSyncBodies
function     void operator

Source code excerpt:

				}

				if (bHasMoved || !bGClusterUnionSyncBodiesMoveNewComponents)
				{
					ParentComponent->SyncClusterUnionFromProxy(NewTransform, nullptr);
				}
				else
				{
					// We must to call MoveComponent on any newly added component. The Cluster Union will take care of