p.Chaos.Solver.UseMACD

p.Chaos.Solver.UseMACD

#Overview

name: p.Chaos.Solver.UseMACD

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Solver.UseMACD is to control the usage of Movement-Aware Collision Detection (MACD) in Unreal Engine’s Chaos physics system. This setting variable is primarily used for the collision detection subsystem within the physics simulation.

This setting variable is relied upon by the Chaos physics module, which is part of Unreal Engine’s experimental physics system. Specifically, it’s used in the PBDRigidsSolver and PBDRigidsEvolutionGBF components of the Chaos system.

The value of this variable is set using an FAutoConsoleVariableRef, which allows it to be modified at runtime through console commands. It’s initialized to true by default, enabling MACD.

This variable interacts closely with another variable named bChaosForceMACD. While p.Chaos.Solver.UseMACD enables or disables MACD globally, bChaosForceMACD can force all collisions to use MACD for testing purposes (but only if p.Chaos.Solver.UseMACD is also enabled).

Developers must be aware that this variable acts as a global flag for MACD. Even if individual particle settings are configured to use MACD, setting this variable to false will disable MACD system-wide.

Best practices when using this variable include:

  1. Keep it enabled (true) for most use cases, as it’s the default and likely optimized setting.
  2. Only disable it if you’re experiencing specific issues related to MACD or if you’re comparing performance with and without MACD.
  3. Use in conjunction with bChaosForceMACD for comprehensive testing of the MACD system.

Regarding the associated variable bChaosUseMACD:

The purpose of bChaosUseMACD is to serve as the actual boolean flag that controls MACD usage within the Chaos physics code. It’s the internal representation of the p.Chaos.Solver.UseMACD console variable.

This variable is used directly in the Chaos physics simulation code, specifically in the Integrate function of FPBDRigidsEvolutionGBF and in the PrepareAdvanceBy function of FPBDRigidsSolver.

The value of bChaosUseMACD is set by the p.Chaos.Solver.UseMACD console variable.

It interacts closely with bChaosForceMACD, as mentioned earlier. Both variables are often checked together to determine the MACD behavior in the physics simulation.

Developers should be aware that modifying bChaosUseMACD directly in code might not have the intended effect, as it can be overwritten by the console variable. It’s best to modify the behavior through the p.Chaos.Solver.UseMACD console variable instead.

Best practices for bChaosUseMACD include:

  1. Treat it as a read-only variable in most code contexts.
  2. Use it for conditional logic in physics simulation code where MACD behavior needs to be checked.
  3. Remember that its value is controlled by the p.Chaos.Solver.UseMACD console variable, so any runtime changes should be made through that interface.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PBDRigidsSolver.cpp:378

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// Enable/Disable MACD (Motion-Aware Collision Detection). Set to false to disable the system, regardless of particle settings
		bool bChaosUseMACD = true;
		FAutoConsoleVariableRef CVarChaos_Collision_UseMACD(TEXT("p.Chaos.Solver.UseMACD"), bChaosUseMACD, TEXT("Global flag to turn Movement-Aware Collision Detection (MACD) on or off. Default is true (on)"), OnCollisionConfigCVarChanged);

		// Use to force all collisions to use MACD for testing (must also have bChaosUseMACD enabled)
		bool bChaosForceMACD = false;
		FAutoConsoleVariableRef CVarChaos_Collision_ForceMACD(TEXT("p.Chaos.Solver.bChaosForceMACD"), bChaosForceMACD, TEXT("Force all collisions to use MACD for testing"), OnCollisionConfigCVarChanged);

		// Joint cvars

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

	{
		// Debug/testing MACD
		extern bool bChaosUseMACD;
		extern bool bChaosForceMACD;

		FRealSingle HackMaxAngularVelocity = 1000.f;
		FAutoConsoleVariableRef CVarHackMaxAngularVelocity(TEXT("p.HackMaxAngularVelocity"), HackMaxAngularVelocity, TEXT("Max cap on angular velocity: rad/s. This is only a temp solution and should not be relied on as a feature. -1.f to disable"));

		FRealSingle HackMaxVelocity = -1.f;

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsEvolutionGBF::Integrate

Source code excerpt:

	const FReal HackMaxAngularSpeedSq = CVars::HackMaxAngularVelocity * CVars::HackMaxAngularVelocity;
	const FReal HackMaxLinearSpeedSq = CVars::HackMaxVelocity * CVars::HackMaxVelocity;
	const bool bAllowMACD = CVars::bChaosUseMACD;
	const bool bForceMACD = CVars::bChaosForceMACD;

	ParticlesView.ParallelFor([&](auto& GeomParticle, int32 Index)
		{
			//question: can we enforce this at the API layer? Right now islands contain non dynamic which makes this hard
			auto PBDParticle = GeomParticle.CastToRigidParticle();

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PBDRigidsSolver.cpp:377

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:


		// Enable/Disable MACD (Motion-Aware Collision Detection). Set to false to disable the system, regardless of particle settings
		bool bChaosUseMACD = true;
		FAutoConsoleVariableRef CVarChaos_Collision_UseMACD(TEXT("p.Chaos.Solver.UseMACD"), bChaosUseMACD, TEXT("Global flag to turn Movement-Aware Collision Detection (MACD) on or off. Default is true (on)"), OnCollisionConfigCVarChanged);

		// Use to force all collisions to use MACD for testing (must also have bChaosUseMACD enabled)
		bool bChaosForceMACD = false;
		FAutoConsoleVariableRef CVarChaos_Collision_ForceMACD(TEXT("p.Chaos.Solver.bChaosForceMACD"), bChaosForceMACD, TEXT("Force all collisions to use MACD for testing"), OnCollisionConfigCVarChanged);

		// Joint cvars
		float ChaosSolverJointMinSolverStiffness = 1.0f;
		float ChaosSolverJointMaxSolverStiffness = 1.0f;

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/PBDRigidsSolver.cpp:1288

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsSolver::PrepareAdvanceBy

Source code excerpt:

		CollisionDetectorSettings.bAllowManifolds = (ChaosSolverCollisionUseManifolds != 0);
		CollisionDetectorSettings.bAllowCCD = bChaosUseCCD;
		CollisionDetectorSettings.bAllowMACD = bChaosUseMACD;
		MEvolution->GetCollisionConstraints().SetDetectorSettings(CollisionDetectorSettings);
		
		FPBDJointSolverSettings JointsSettings = MEvolution->GetJointConstraints().GetSettings();
		JointsSettings.MinSolverStiffness = ChaosSolverJointMinSolverStiffness;
		JointsSettings.MaxSolverStiffness = ChaosSolverJointMaxSolverStiffness;
		JointsSettings.NumIterationsAtMaxSolverStiffness = ChaosSolverJointNumIterationsAtMaxSolverStiffness;