p.RigidBodyNode.EnableSimulation

p.RigidBodyNode.EnableSimulation

#Overview

name: p.RigidBodyNode.EnableSimulation

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.RigidBodyNode.EnableSimulation is to enable or disable the simulation of rigid body nodes at runtime for debugging and testing purposes. This setting variable is part of the animation system in Unreal Engine 5, specifically for the rigid body node simulation.

The Unreal Engine subsystem that relies on this setting variable is the AnimGraphRuntime module, particularly the bone controllers system. This can be seen from the file path where the variable is defined and used: “Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_RigidBody.cpp”.

The value of this variable is set as a console variable using TAutoConsoleVariable. It is initialized with a default value of 1, which means the simulation is enabled by default.

This variable interacts closely with another variable named bEnableRigidBodyNode, which controls the entire rigid body node system. While bEnableRigidBodyNode can completely disable the system to avoid allocations and runtime costs, p.RigidBodyNode.EnableSimulation allows for more granular control. Even when simulation is disabled, the node is still initialized, and bodies and constraints are created.

Developers must be aware that this variable is primarily intended for debugging and testing purposes. It allows for runtime toggling of the simulation without completely disabling the rigid body node system. This can be useful for isolating issues or performance testing.

Best practices when using this variable include:

  1. Use it judiciously during development and debugging phases.
  2. Remember that disabling simulation doesn’t free up all resources associated with rigid body nodes.
  3. Consider the interaction with the broader bEnableRigidBodyNode setting.
  4. Be cautious about changing this setting in a shipping game, as it may lead to unexpected behavior.

Regarding the associated variable CVarEnableRigidBodyNodeSimulation:

The purpose of CVarEnableRigidBodyNodeSimulation is to provide a programmatic way to access and modify the p.RigidBodyNode.EnableSimulation setting. It’s an instance of TAutoConsoleVariable, which allows for runtime modification of the setting.

This variable is used in the AnimGraphRuntime module, specifically in the FAnimNode_RigidBody::EvaluateSkeletalControl_AnyThread function. The function checks the value of this variable to determine whether to proceed with the rigid body simulation.

The value of this variable can be set through console commands or programmatically at runtime.

Developers should be aware that changes to this variable take effect immediately in the EvaluateSkeletalControl_AnyThread function. This allows for real-time toggling of the simulation for debugging purposes.

Best practices for using CVarEnableRigidBodyNodeSimulation include:

  1. Use it for debugging and performance testing scenarios.
  2. Be cautious about modifying it in shipping builds, as it may affect gameplay.
  3. Consider wrapping access to this variable in debug-only code to prevent accidental usage in release builds.
  4. When toggling this variable, be prepared to handle any visual or gameplay inconsistencies that may arise from enabling or disabling the simulation mid-game.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_RigidBody.cpp:51

Scope: file

Source code excerpt:

bool bEnableRigidBodyNode = true;
FAutoConsoleVariableRef CVarEnableRigidBodyNode(TEXT("p.RigidBodyNode"), bEnableRigidBodyNode, TEXT("Enables/disables the whole rigid body node system. When disabled, avoids all allocations and runtime costs. Can be used to disable RB Nodes on low-end platforms."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableRigidBodyNodeSimulation(TEXT("p.RigidBodyNode.EnableSimulation"), 1, TEXT("Runtime Enable/Disable RB Node Simulation for debugging and testing (node is initialized and bodies and constraints are created, even when disabled.)"), ECVF_Default);
TAutoConsoleVariable<int32> CVarRigidBodyLODThreshold(TEXT("p.RigidBodyLODThreshold"), -1, TEXT("Max LOD that rigid body node is allowed to run on. Provides a global threshold that overrides per-node the LODThreshold property. -1 means no override."), ECVF_Scalability);

int32 RBAN_MaxSubSteps = 4;
bool bRBAN_EnableTimeBasedReset = true;
bool bRBAN_EnableComponentAcceleration = true;
int32 RBAN_WorldObjectExpiry = 4;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_RigidBody.cpp:51

Scope: file

Source code excerpt:

bool bEnableRigidBodyNode = true;
FAutoConsoleVariableRef CVarEnableRigidBodyNode(TEXT("p.RigidBodyNode"), bEnableRigidBodyNode, TEXT("Enables/disables the whole rigid body node system. When disabled, avoids all allocations and runtime costs. Can be used to disable RB Nodes on low-end platforms."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableRigidBodyNodeSimulation(TEXT("p.RigidBodyNode.EnableSimulation"), 1, TEXT("Runtime Enable/Disable RB Node Simulation for debugging and testing (node is initialized and bodies and constraints are created, even when disabled.)"), ECVF_Default);
TAutoConsoleVariable<int32> CVarRigidBodyLODThreshold(TEXT("p.RigidBodyLODThreshold"), -1, TEXT("Max LOD that rigid body node is allowed to run on. Provides a global threshold that overrides per-node the LODThreshold property. -1 means no override."), ECVF_Scalability);

int32 RBAN_MaxSubSteps = 4;
bool bRBAN_EnableTimeBasedReset = true;
bool bRBAN_EnableComponentAcceleration = true;
int32 RBAN_WorldObjectExpiry = 4;

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_RigidBody.cpp:524

Scope (from outer to inner):

file
function     void FAnimNode_RigidBody::EvaluateSkeletalControl_AnyThread

Source code excerpt:

	//SCOPED_NAMED_EVENT_TEXT("FAnimNode_RigidBody::EvaluateSkeletalControl_AnyThread", FColor::Magenta);

	if (CVarEnableRigidBodyNodeSimulation.GetValueOnAnyThread() == 0)
	{
		return;
	}

	const float DeltaSeconds = AccumulatedDeltaTime;
	AccumulatedDeltaTime = 0.f;

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Public/BoneControllers/AnimNode_RigidBody.h:16

Scope: file

Source code excerpt:

extern ANIMGRAPHRUNTIME_API bool bEnableRigidBodyNode;
extern ANIMGRAPHRUNTIME_API FAutoConsoleVariableRef CVarEnableRigidBodyNode;
extern ANIMGRAPHRUNTIME_API TAutoConsoleVariable<int32> CVarEnableRigidBodyNodeSimulation;
extern ANIMGRAPHRUNTIME_API TAutoConsoleVariable<int32> CVarRigidBodyLODThreshold;

/** Determines in what space the simulation should run */
UENUM()
enum class ESimulationSpace : uint8
{