p.AnimDynamicsAdaptiveSubstep

p.AnimDynamicsAdaptiveSubstep

#Overview

name: p.AnimDynamicsAdaptiveSubstep

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.AnimDynamicsAdaptiveSubstep is to enable or disable adaptive substepping in the animation dynamics system of Unreal Engine 5. Adaptive substepping allows the simulation to adjust its time step dynamically to maintain stability and accuracy, particularly in scenarios with fast-moving objects or complex interactions.

This setting variable is primarily used in the animation system, specifically within the AnimGraphRuntime module. It directly affects the behavior of the AnimDynamics node, which is responsible for physics-based secondary animation.

The value of this variable is set through a console variable (CVar) named CVarEnableAdaptiveSubstep. It is initialized with a default value of 0, meaning adaptive substepping is disabled by default. Developers can change this value at runtime using console commands or through project settings.

The main variable that interacts with p.AnimDynamicsAdaptiveSubstep is CVarAdaptiveSubstepNumDebtFrames, which determines the number of frames to maintain as time debt when using adaptive substepping.

Developers should be aware that enabling adaptive substepping can improve the quality and stability of animations, especially in scenarios with rapid movements or complex physics interactions. However, it may also increase computational overhead.

Best practices when using this variable include:

  1. Enable it when dealing with fast-moving characters or objects that require more precise physics simulation.
  2. Adjust the CVarAdaptiveSubstepNumDebtFrames value to fine-tune the balance between simulation accuracy and performance.
  3. Test the impact on performance, as adaptive substepping may increase CPU usage.

Regarding the associated variable CVarEnableAdaptiveSubstep:

The purpose of CVarEnableAdaptiveSubstep is to provide a runtime-configurable way to enable or disable the adaptive substepping feature. It is directly linked to the p.AnimDynamicsAdaptiveSubstep setting.

This variable is used in the AnimGraphRuntime module, specifically within the AnimNode_AnimDynamics class, which handles physics-based animations.

The value of CVarEnableAdaptiveSubstep is set when the engine initializes the console variables. It can be changed at runtime using console commands.

CVarEnableAdaptiveSubstep interacts closely with CVarAdaptiveSubstepNumDebtFrames, as they both control aspects of the adaptive substepping feature.

Developers should be aware that this variable directly impacts the behavior of the AnimDynamics node. Changing its value at runtime will immediately affect all active AnimDynamics simulations.

Best practices for using CVarEnableAdaptiveSubstep include:

  1. Use it in conjunction with performance profiling to determine if adaptive substepping benefits your specific use case.
  2. Consider exposing this setting to end-users as a graphics option if the visual difference is significant and the performance impact is manageable.
  3. Be cautious when changing this value during gameplay, as it may cause noticeable changes in animation behavior.

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarLODThreshold(TEXT("p.AnimDynamicsLODThreshold"), -1, TEXT("Max LOD that anim dynamics is allowed to run on. Provides a global threshold that overrides per-node the LODThreshold property. -1 means no override."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableDynamics(TEXT("p.AnimDynamics"), 1, TEXT("Enables/Disables anim dynamics node updates."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableAdaptiveSubstep(TEXT("p.AnimDynamicsAdaptiveSubstep"), 0, TEXT("Enables/disables adaptive substepping. Adaptive substepping will substep the simulation when it is necessary and maintain a debt buffer for time, always trying to utilise as much time as possible."));
TAutoConsoleVariable<int32> CVarAdaptiveSubstepNumDebtFrames(TEXT("p.AnimDynamicsNumDebtFrames"), 5, TEXT("Number of frames to maintain as time debt when using adaptive substepping, this should be at least 1 or the time debt will never be cleared."));
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

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> CVarLODThreshold(TEXT("p.AnimDynamicsLODThreshold"), -1, TEXT("Max LOD that anim dynamics is allowed to run on. Provides a global threshold that overrides per-node the LODThreshold property. -1 means no override."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableDynamics(TEXT("p.AnimDynamics"), 1, TEXT("Enables/Disables anim dynamics node updates."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableAdaptiveSubstep(TEXT("p.AnimDynamicsAdaptiveSubstep"), 0, TEXT("Enables/disables adaptive substepping. Adaptive substepping will substep the simulation when it is necessary and maintain a debt buffer for time, always trying to utilise as much time as possible."));
TAutoConsoleVariable<int32> CVarAdaptiveSubstepNumDebtFrames(TEXT("p.AnimDynamicsNumDebtFrames"), 5, TEXT("Number of frames to maintain as time debt when using adaptive substepping, this should be at least 1 or the time debt will never be cleared."));
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

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

Scope (from outer to inner):

file
function     void FAnimNode_AnimDynamics::EvaluateSkeletalControl_AnyThread

Source code excerpt:

			}

			if (CVarEnableAdaptiveSubstep.GetValueOnAnyThread() == 1)
			{
				float CurrentTimeDilation = Output.AnimInstanceProxy->GetTimeDilation();
				float FixedTimeStep = MaxSubstepDeltaTime * CurrentTimeDilation;

				// Clamp the fixed timestep down to max physics tick time.
				// at high speeds the simulation will not converge as the delta time is too high, this will