a.AnimNode.LegIK.MaxIterations

a.AnimNode.LegIK.MaxIterations

#Overview

name: a.AnimNode.LegIK.MaxIterations

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 a.AnimNode.LegIK.MaxIterations is to control the maximum number of iterations for the Leg IK (Inverse Kinematics) solver in Unreal Engine’s animation system. This setting is specifically used for fine-tuning the performance and accuracy of leg positioning in character animations.

This setting variable is primarily used by the Animation Runtime module, specifically within the Leg IK system. It’s part of the bone controllers in the AnimGraphRuntime subsystem.

The value of this variable is set through a console variable (CVar) named CVarAnimLegIKMaxIterations. It’s initialized with a default value of 0, which means it will use the node’s default value. Any value greater than 0 will override the default.

The associated variable CVarAnimLegIKMaxIterations interacts directly with a.AnimNode.LegIK.MaxIterations. They essentially represent the same setting, with the CVar providing a way to modify the value at runtime through console commands.

Developers should be aware that:

  1. Setting this value too low may result in less accurate leg positioning, while setting it too high might impact performance.
  2. A value of 0 means the system will use the default value set in the animation node.
  3. This setting affects all instances of Leg IK in the game, so changes should be made cautiously.

Best practices when using this variable include:

  1. Start with the default value and only adjust if necessary.
  2. Test thoroughly after making changes to ensure both visual quality and performance are maintained.
  3. Use in conjunction with other Leg IK settings like TargetReachStepPercent and PullDistribution for optimal results.
  4. Consider exposing this setting in a development build for easier tuning, but lock it down in release builds.

Regarding the associated variable CVarAnimLegIKMaxIterations: The purpose of CVarAnimLegIKMaxIterations is to provide a runtime-adjustable way to control the a.AnimNode.LegIK.MaxIterations setting. It’s part of the console variable system in Unreal Engine, allowing developers and potentially players to modify the setting without recompiling the game.

This CVar is used in the same AnimGraphRuntime module, specifically in the Leg IK solver code. Its value is checked and applied in the DoLegReachIK function of the FAnimNode_LegIK class.

The value of CVarAnimLegIKMaxIterations can be set through console commands or potentially through game code that interfaces with the console variable system.

Developers should be aware that changes to this CVar will immediately affect all Leg IK calculations in the game, which could have wide-ranging effects on character animations.

Best practices for using CVarAnimLegIKMaxIterations include:

  1. Use it for debugging and fine-tuning during development.
  2. Consider adding safeguards to prevent extreme values that could negatively impact performance or animation quality.
  3. Document the use and impact of this CVar for other team members.
  4. In a shipping game, you might want to disable or remove access to this CVar to prevent potential exploits or unintended 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_LegIK.cpp:16

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarAnimLegIKEnable(TEXT("a.AnimNode.LegIK.Enable"), 1, TEXT("Toggle LegIK node."));
TAutoConsoleVariable<int32> CVarAnimLegIKMaxIterations(TEXT("a.AnimNode.LegIK.MaxIterations"), 0, TEXT("Leg IK MaxIterations override. 0 = node default, > 0 override."));
TAutoConsoleVariable<float> CVarAnimLegIKTargetReachStepPercent(TEXT("a.AnimNode.LegIK.TargetReachStepPercent"), 0.7f, TEXT("Leg IK TargetReachStepPercent."));
TAutoConsoleVariable<float> CVarAnimLegIKPullDistribution(TEXT("a.AnimNode.LegIK.PullDistribution"), 0.5f, TEXT("Leg IK PullDistribution. 0 = foot, 0.5 = balanced, 1.f = hip"));

/////////////////////////////////////////////////////
// FAnimAnimNode_LegIK

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_LegIK.cpp:16

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarAnimLegIKEnable(TEXT("a.AnimNode.LegIK.Enable"), 1, TEXT("Toggle LegIK node."));
TAutoConsoleVariable<int32> CVarAnimLegIKMaxIterations(TEXT("a.AnimNode.LegIK.MaxIterations"), 0, TEXT("Leg IK MaxIterations override. 0 = node default, > 0 override."));
TAutoConsoleVariable<float> CVarAnimLegIKTargetReachStepPercent(TEXT("a.AnimNode.LegIK.TargetReachStepPercent"), 0.7f, TEXT("Leg IK TargetReachStepPercent."));
TAutoConsoleVariable<float> CVarAnimLegIKPullDistribution(TEXT("a.AnimNode.LegIK.PullDistribution"), 0.5f, TEXT("Leg IK PullDistribution. 0 = foot, 0.5 = balanced, 1.f = hip"));

/////////////////////////////////////////////////////
// FAnimAnimNode_LegIK

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_LegIK.cpp:428

Scope (from outer to inner):

file
function     bool FAnimNode_LegIK::DoLegReachIK

Source code excerpt:

	if (bNeedsSolver)
	{
		const int32 MaxIterationsOverride = CVarAnimLegIKMaxIterations.GetValueOnAnyThread() > 0 ? CVarAnimLegIKMaxIterations.GetValueOnAnyThread() : MaxIterations;
		IKChain.ReachTarget(FootIKLocation, ReachPrecision, MaxIterationsOverride, SoftPercentLength, SoftAlpha);
	}

	if (bHasTwistOffset)
	{
		IKChain.ApplyTwistOffset(InLegData.TwistOffsetDegrees);