p.Chaos.Solver.Joint.TransferCollisions

p.Chaos.Solver.Joint.TransferCollisions

#Overview

name: p.Chaos.Solver.Joint.TransferCollisions

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.Chaos.Solver.Joint.TransferCollisions is to control whether joints can apply collisions from the child to the parent when the Joint’s TransferCollisionScale is not 0. This setting variable is part of Unreal Engine’s Chaos physics system, specifically related to joint constraint handling in the physics solver.

The Chaos physics subsystem within Unreal Engine 5 relies on this setting variable. It is particularly used in the PBDRigidsEvolutionGBF (Position Based Dynamics Rigid Evolution) module, which is responsible for simulating rigid body dynamics.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be modified at runtime through console commands or configuration files. Its default value is true.

This variable interacts closely with other related variables:

  1. TransferCollisionsLimit: Sets the maximum number of constraints allowed to transfer to the parent.
  2. TransferCollisionsKinematicScale: Defines the scale applied to collision transfers between kinematic bodies.

Developers must be aware that enabling this feature (which is the default) allows for more realistic physics simulations, especially in scenarios involving connected bodies with large mass differences. However, it may also impact performance, particularly if there are many joints in the scene.

Best practices when using this variable include:

  1. Consider disabling it if performance is a priority and the additional physical accuracy is not crucial.
  2. Use in conjunction with TransferCollisionsLimit to balance between accuracy and performance.
  3. Adjust TransferCollisionsKinematicScale when dealing with kinematic bodies to fine-tune the behavior.

Regarding the associated variable DoTransferJointConstraintCollisions:

The purpose of DoTransferJointConstraintCollisions is to serve as the actual boolean flag that controls the joint collision transfer behavior in the physics simulation code.

This variable is used directly in the TransferJointConstraintCollisions function of the FPBDRigidsEvolutionGBF class. It determines whether the function will proceed with transferring joint constraint collisions.

The value of this variable is set by the p.Chaos.Solver.Joint.TransferCollisions console variable, allowing for runtime configuration.

Developers should be aware that this variable directly affects the physics simulation loop. Changing its value at runtime will immediately impact the behavior of jointed physics objects.

Best practices for using this variable include:

  1. Use it in conjunction with the console variable for easy runtime tweaking and debugging.
  2. Consider exposing it in game settings if you want to give users control over physics fidelity vs. performance.
  3. Be cautious when changing its value during gameplay, as it may cause sudden changes in physics behavior.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolutionGBF.cpp:83

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:


		bool DoTransferJointConstraintCollisions = true;
		FAutoConsoleVariableRef CVarDoTransferJointConstraintCollisions(TEXT("p.Chaos.Solver.Joint.TransferCollisions"), DoTransferJointConstraintCollisions, TEXT("Allows joints to apply collisions to the parent from the child when the Joints TransferCollisionScale is not 0 [def:true]"));

		int32 TransferCollisionsLimit = INT_MAX;
		FAutoConsoleVariableRef CVarTransferCollisionsMultiply(TEXT("p.Chaos.Solver.Joint.TransferCollisionsLimit"), TransferCollisionsLimit, TEXT("Maximum number of constraints that are allowed to transfer to the parent. Lowering this will improve performance but reduce accuracy. [def:INT_MAX]"));

		FRealSingle TransferCollisionsKinematicScale = 1.0f;
		FAutoConsoleVariableRef CVarTransferCollisionsKinematicScale(TEXT("p.Chaos.Solver.Joint.TransferCollisionsKinematicScale"), TransferCollisionsKinematicScale, TEXT("Scale to apply to collision transfers between kinematic bodies [def:1.0]"));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolutionGBF.cpp:82

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		FAutoConsoleVariableRef CVarChaosSolverChaosCharacterGroundConstraintPriority(TEXT("p.Chaos.Solver.CharacterGroundConstraint.Priority"), ChaosSolverCharacterGroundConstraintPriority, TEXT("Set constraint priority. Larger values are evaluated later [def:0]"));

		bool DoTransferJointConstraintCollisions = true;
		FAutoConsoleVariableRef CVarDoTransferJointConstraintCollisions(TEXT("p.Chaos.Solver.Joint.TransferCollisions"), DoTransferJointConstraintCollisions, TEXT("Allows joints to apply collisions to the parent from the child when the Joints TransferCollisionScale is not 0 [def:true]"));

		int32 TransferCollisionsLimit = INT_MAX;
		FAutoConsoleVariableRef CVarTransferCollisionsMultiply(TEXT("p.Chaos.Solver.Joint.TransferCollisionsLimit"), TransferCollisionsLimit, TEXT("Maximum number of constraints that are allowed to transfer to the parent. Lowering this will improve performance but reduce accuracy. [def:INT_MAX]"));

		FRealSingle TransferCollisionsKinematicScale = 1.0f;
		FAutoConsoleVariableRef CVarTransferCollisionsKinematicScale(TEXT("p.Chaos.Solver.Joint.TransferCollisionsKinematicScale"), TransferCollisionsKinematicScale, TEXT("Scale to apply to collision transfers between kinematic bodies [def:1.0]"));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/PBDRigidsEvolutionGBF.cpp:1153

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsEvolutionGBF::TransferJointConstraintCollisions

Source code excerpt:

	// chassis without having to worry about making the joint connecting them very stiff
	// which is quite difficult for large mass ratios and would require many iterations.
	if (DoTransferJointConstraintCollisions)
	{
		Private::FCollisionConstraintAllocator& CollisionAllocator = CollisionConstraints.GetConstraintAllocator();

		// @todo(chaos): we should only visit the joints that have ContactTransferScale > 0 
		for (int32 JointConstraintIndex = 0; JointConstraintIndex < GetJointConstraints().NumConstraints(); ++JointConstraintIndex)
		{