p.Chaos.Solver.Joint.TransferCollisionsKinematicScale

p.Chaos.Solver.Joint.TransferCollisionsKinematicScale

#Overview

name: p.Chaos.Solver.Joint.TransferCollisionsKinematicScale

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

• type: Var
• help: Scale to apply to collision transfers between kinematic bodies [def:1.0]

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Solver.Joint.TransferCollisionsKinematicScale is to scale the collision transfers between kinematic bodies in the Chaos physics solver of Unreal Engine 5. This setting variable is part of the physics simulation system, specifically the joint collision handling in the Chaos solver.

This setting variable is primarily used in the Chaos module of Unreal Engine 5, which is responsible for physics simulations. Based on the callsites, it’s utilized in the PBDRigidsEvolutionGBF.cpp file, which is likely part of the Position Based Dynamics (PBD) implementation for rigid body evolution.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be adjusted via console commands or configuration files. Its default value is 1.0f.

This variable interacts closely with other physics-related variables such as TransferCollisionsStiffnessClamp and TransferCollisionsDebugTestAgainstMaxClamp. It’s used in conjunction with these variables to control the behavior of collision transfers in the physics simulation.

Developers must be aware that this variable directly affects the stiffness of collision constraints, particularly for kinematic bodies. A value of 1.0 means no scaling, while values greater than 1.0 will increase the stiffness of collision transfers between kinematic bodies, and values less than 1.0 will decrease it.

Best practices when using this variable include:

1. Ensure the value is always positive, as indicated by the error check in the code.
2. Use it in conjunction with TransferCollisionsStiffnessClamp to maintain stability in the physics simulation.
3. Adjust it carefully, as it can significantly impact the behavior of kinematic bodies in collision scenarios.

Regarding the associated variable TransferCollisionsKinematicScale:

This is actually the same variable as p.Chaos.Solver.Joint.TransferCollisionsKinematicScale. It’s declared as a local variable in the CVars namespace and then exposed as a console variable. It’s used directly in the physics calculations to scale the collision constraint stiffness for kinematic bodies.

The purpose and usage are the same as described above. It’s important to note that changes to this variable via console commands will directly affect the physics simulations in real-time, allowing for dynamic tuning of the 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:89

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

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

		FRealSingle TransferCollisionsStiffnessClamp = 1.0f;
		FAutoConsoleVariableRef CVarTransferCollisionsStiffnessClamp(TEXT("p.Chaos.Solver.Joint.TransferCollisionsStiffnessClamp"), TransferCollisionsStiffnessClamp, TEXT("Clamp of maximum value of the stiffness clamp[def:1.0]"));

		bool TransferCollisionsDebugTestAgainstMaxClamp = false;
		FAutoConsoleVariableRef CVarTransferCollisionsDebugTestAgainstMaxClamp(TEXT("p.Chaos.Solver.Joint.TransferCollisionsDebugTestAgainstMaxClamp"), TransferCollisionsDebugTestAgainstMaxClamp, TEXT("Force all joint collision constraint settings to max clamp value to validate stability [def:false]"));

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

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

		FRealSingle TransferCollisionsStiffnessClamp = 1.0f;
		FAutoConsoleVariableRef CVarTransferCollisionsStiffnessClamp(TEXT("p.Chaos.Solver.Joint.TransferCollisionsStiffnessClamp"), TransferCollisionsStiffnessClamp, TEXT("Clamp of maximum value of the stiffness clamp[def:1.0]"));

		bool TransferCollisionsDebugTestAgainstMaxClamp = false;
		FAutoConsoleVariableRef CVarTransferCollisionsDebugTestAgainstMaxClamp(TEXT("p.Chaos.Solver.Joint.TransferCollisionsDebugTestAgainstMaxClamp"), TransferCollisionsDebugTestAgainstMaxClamp, TEXT("Force all joint collision constraint settings to max clamp value to validate stability [def:false]"));

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

Scope (from outer to inner):

file
lambda-function

Source code excerpt:

						if (CollisionParticleA.Get() && CollisionParticleA->ObjectState() != EObjectStateType::Dynamic)
						{
							if (ensureMsgf(TransferCollisionsKinematicScale > 0, TEXT("Zero or Negative TransferCollisionsKinematicScale")))
							{
								CollisionConstraintStiffness *= TransferCollisionsKinematicScale;
							}
						}
						TransferedConstraint->SetStiffness(FMath::Clamp(CollisionConstraintStiffness, (FReal)0.f, TransferCollisionsStiffnessClamp));

						FParticlePairMidPhase* MidPhase = CollisionAllocator.GetParticlePairMidPhase(CollisionParticleA->Handle(), CollisionParticleB->Handle());
						MidPhase->InjectCollision(*TransferedConstraint);