p.AnimDynamics.GravityScale

p.AnimDynamics.GravityScale

#Overview

name: p.AnimDynamics.GravityScale

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.AnimDynamics.GravityScale is to provide a global multiplier for gravity in the Anim Dynamics system of Unreal Engine 5. This setting variable is used to adjust the gravity effect on all Anim Dynamics Nodes throughout the engine.

The Unreal Engine subsystem that relies on this setting variable is the Animation system, specifically the Anim Dynamics module within the AnimGraphRuntime. This can be seen from the file path where the variable is defined and used: ‘Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_AnimDynamics.cpp’.

The value of this variable is set as a console variable (CVar) with a default value of 1.0f. It can be modified at runtime through console commands or programmatically.

This variable interacts closely with the GravityScale property of individual Anim Dynamics nodes and the SimSpaceGravityOverride. It multiplies both the default gravity and any gravity overrides set on Anim Dynamics Nodes.

Developers must be aware that changing this variable will affect all Anim Dynamics Nodes in the project. It’s a global setting that can have wide-ranging effects on animation behavior.

Best practices when using this variable include:

  1. Use it for global adjustments to gravity across all animations.
  2. Be cautious when modifying it, as it can affect the behavior of all Anim Dynamics in the project.
  3. Consider using it for performance optimizations or stylistic adjustments that need to be applied project-wide.

Regarding the associated variable CVarGravityScale:

The purpose of CVarGravityScale is identical to p.AnimDynamics.GravityScale, as they are essentially the same variable. CVarGravityScale is the actual C++ variable that holds the value set by the console variable p.AnimDynamics.GravityScale.

This variable is used directly in the AnimNode_AnimDynamics class to modify gravity calculations. It’s retrieved using the GetValueOnAnyThread() method, suggesting it’s designed to be thread-safe for use in multi-threaded animation contexts.

The value of CVarGravityScale is applied in two main places within the AnimNode_AnimDynamics:

  1. In the EvaluateSkeletalControl_AnyThread function, where it scales both the SimSpaceGravityOverride and the individual GravityScale of the node.
  2. In the InitPhysics function, where it’s retrieved for use in initializing the physics simulation.

Developers should be aware that this variable is accessed on potentially any thread, so any modifications to it should be thread-safe.

Best practices for CVarGravityScale are the same as for p.AnimDynamics.GravityScale, as they are effectively the same setting exposed in different ways (console variable vs. C++ variable).

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_AnimDynamics.cpp:25

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarEnableWind(TEXT("p.AnimDynamicsWind"), 1, TEXT("Enables/Disables anim dynamics wind forces globally."), ECVF_Scalability);
TAutoConsoleVariable<float> CVarComponentAppliedLinearAccClampOverride(TEXT("p.AnimDynamics.ComponentAppliedLinearAccClampOverride"), -1.0f, TEXT("Override the per asset setting for all axis (X,Y & Z) of ComponentAppliedLinearAccClamp for all Anim Dynamics Nodes. Negative values are ignored."));
TAutoConsoleVariable<float> CVarGravityScale(TEXT("p.AnimDynamics.GravityScale"), 1.0f, TEXT("Multiplies the defalut gravity and the gravity override on all Anim Dynamics Nodes."));

// FindChainBones
// 
// Returns an ordered list of the names of all the bones in a chain between BeginBoneName and EndBoneName.
//
void FindChainBones(const FName BeginBoneName, const FName EndBoneName, TFunctionRef< FName (const FName) > GetParentBoneName, TArray<FName>& OutChainBoneNames)

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_AnimDynamics.cpp:25

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarEnableWind(TEXT("p.AnimDynamicsWind"), 1, TEXT("Enables/Disables anim dynamics wind forces globally."), ECVF_Scalability);
TAutoConsoleVariable<float> CVarComponentAppliedLinearAccClampOverride(TEXT("p.AnimDynamics.ComponentAppliedLinearAccClampOverride"), -1.0f, TEXT("Override the per asset setting for all axis (X,Y & Z) of ComponentAppliedLinearAccClamp for all Anim Dynamics Nodes. Negative values are ignored."));
TAutoConsoleVariable<float> CVarGravityScale(TEXT("p.AnimDynamics.GravityScale"), 1.0f, TEXT("Multiplies the defalut gravity and the gravity override on all Anim Dynamics Nodes."));

// FindChainBones
// 
// Returns an ordered list of the names of all the bones in a chain between BeginBoneName and EndBoneName.
//
void FindChainBones(const FName BeginBoneName, const FName EndBoneName, TFunctionRef< FName (const FName) > GetParentBoneName, TArray<FName>& OutChainBoneNames)

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_AnimDynamics.cpp:360

Scope (from outer to inner):

file
function     void FAnimNode_AnimDynamics::EvaluateSkeletalControl_AnyThread

Source code excerpt:

			// Update gravity.
			{
				const float ExternalGravityScale = CVarGravityScale.GetValueOnAnyThread();

				const FVector AppliedGravityOverride = SimSpaceGravityOverride * ExternalGravityScale;
				const float AppliedGravityScale = GravityScale * ExternalGravityScale;

				for (FAnimPhysRigidBody* ChainBody : SimBodies)
				{

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_AnimDynamics.cpp:709

Scope (from outer to inner):

file
function     void FAnimNode_AnimDynamics::InitPhysics

Source code excerpt:

		// Transform GravityOverride to simulation space if necessary.
		const FVector GravityOverrideSimSpace = (bUseGravityOverride && !bGravityOverrideInSimSpace) ? TransformWorldVectorToSimSpace(Output, GravityOverride) : GravityOverride;
		const float ExternalGravityScale = CVarGravityScale.GetValueOnAnyThread();

		check(PhysicsBodyDefinitions.Num() > 0);
		if (PhysicsBodyDefinitions.Num() > 0)
		{
			Bodies.Reserve(PhysicsBodyDefinitions.Num());
			PhysicsBodyDefinitions[0].BoundBone = BoundBone;