p.Chaos.Solver.Collision.MaxVelocityBoundsExpansion

p.Chaos.Solver.Collision.MaxVelocityBoundsExpansion

#Overview

name: p.Chaos.Solver.Collision.MaxVelocityBoundsExpansion

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.Chaos.Solver.Collision.MaxVelocityBoundsExpansion is to control the maximum expansion of velocity bounds in the Chaos physics solver’s collision detection system. This setting is part of Unreal Engine 5’s Chaos physics system, which is responsible for simulating physical interactions between objects in the game world.

This setting variable is primarily used by the Chaos physics subsystem, specifically within the PBDRigidsSolver (Position Based Dynamics Rigid Solver) module. It’s part of the collision detection and handling mechanism in the physics simulation.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 3.0f and can be overridden at runtime using the console command system.

This variable interacts closely with ChaosSolverVelocityBoundsMultiplier. Together, these two variables control how the velocity bounds of objects are expanded during collision detection. The MaxVelocityBoundsExpansion sets an upper limit on this expansion.

Developers should be aware that this variable directly impacts the precision and performance of collision detection. A larger value may improve collision detection for fast-moving objects but at the cost of performance, while a smaller value may improve performance but potentially miss some collisions for rapidly moving objects.

Best practices when using this variable include:

  1. Tuning it in conjunction with ChaosSolverVelocityBoundsMultiplier for optimal balance between collision accuracy and performance.
  2. Testing with different values in scenarios involving fast-moving objects to ensure collisions are detected correctly.
  3. Monitoring performance impacts when adjusting this value, especially in scenes with many dynamic objects.

Regarding the associated variable ChaosSolverMaxVelocityBoundsExpansion:

This is the actual variable that stores the value set by the p.Chaos.Solver.Collision.MaxVelocityBoundsExpansion console variable. It’s used directly in the physics solver code to apply the maximum velocity bounds expansion.

The purpose of ChaosSolverMaxVelocityBoundsExpansion is the same as p.Chaos.Solver.Collision.MaxVelocityBoundsExpansion - to limit the expansion of velocity bounds during collision detection.

It’s used in the Chaos physics subsystem, specifically in the FPBDRigidsSolver::PrepareAdvanceBy function, where it’s passed to the SetVelocityBoundsExpansion method along with ChaosSolverVelocityBoundsMultiplier.

The value is set either through the default initialization (3.0f) or via the console variable system at runtime.

Developers should be aware that this variable is checked for validity (>= 0.0f) before being applied, so negative values will be ignored.

Best practices include ensuring that any code modifying this variable directly (rather than through the console variable system) also updates related systems and maintains the validity check (>= 0.0f).

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		FRealSingle ChaosSolverMaxVelocityBoundsExpansionMACD = 1000.0f;	// For use when Movement-Aware Collision Detection (MACD) is enabled
		FAutoConsoleVariableRef CVarChaosSolverVelocityBoundsMultiplier(TEXT("p.Chaos.Solver.Collision.VelocityBoundsMultiplier"), ChaosSolverVelocityBoundsMultiplier, TEXT("Override velocity bounds multiplier (if >= 0)"), OnCollisionConfigCVarChanged);
		FAutoConsoleVariableRef CVarChaosSolverMaxVelocityBoundsExpansion(TEXT("p.Chaos.Solver.Collision.MaxVelocityBoundsExpansion"), ChaosSolverMaxVelocityBoundsExpansion, TEXT("Override max velocity bounds expansion (if >= 0)"), OnCollisionConfigCVarChanged);
		FAutoConsoleVariableRef CVarChaosSolverVelocityBoundsMultiplierMACD(TEXT("p.Chaos.Solver.Collision.VelocityBoundsMultiplierMACD"), ChaosSolverVelocityBoundsMultiplierMACD, TEXT("Override velocity bounds multiplier for MACD (if >= 0)"), OnCollisionConfigCVarChanged);
		FAutoConsoleVariableRef CVarChaosSolverMaxVelocityBoundsExpansionMACD(TEXT("p.Chaos.Solver.Collision.MaxVelocityBoundsExpansionMACD"), ChaosSolverMaxVelocityBoundsExpansionMACD, TEXT("Override max velocity bounds expansion for MACD (if >= 0)"), OnCollisionConfigCVarChanged);

		FRealSingle ChaosSolverMaxPushOutVelocity = -1.0f;
		FAutoConsoleVariableRef CVarChaosSolverMaxPushOutVelocity(TEXT("p.Chaos.Solver.Collision.MaxPushOutVelocity"), ChaosSolverMaxPushOutVelocity, TEXT("Override max pushout velocity (if >= 0)"), OnCollisionConfigCVarChanged);

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// @todo(chaos): move to physics project settings and set these to -1 when we are settled on values...
		FRealSingle ChaosSolverVelocityBoundsMultiplier = 1.0f;
		FRealSingle ChaosSolverMaxVelocityBoundsExpansion = 3.0f;			// This should probably be a fraction of object size (see FParticlePairMidPhase::GenerateCollisions)
		FRealSingle ChaosSolverVelocityBoundsMultiplierMACD = 1.0f;
		FRealSingle ChaosSolverMaxVelocityBoundsExpansionMACD = 1000.0f;	// For use when Movement-Aware Collision Detection (MACD) is enabled
		FAutoConsoleVariableRef CVarChaosSolverVelocityBoundsMultiplier(TEXT("p.Chaos.Solver.Collision.VelocityBoundsMultiplier"), ChaosSolverVelocityBoundsMultiplier, TEXT("Override velocity bounds multiplier (if >= 0)"), OnCollisionConfigCVarChanged);
		FAutoConsoleVariableRef CVarChaosSolverMaxVelocityBoundsExpansion(TEXT("p.Chaos.Solver.Collision.MaxVelocityBoundsExpansion"), ChaosSolverMaxVelocityBoundsExpansion, TEXT("Override max velocity bounds expansion (if >= 0)"), OnCollisionConfigCVarChanged);
		FAutoConsoleVariableRef CVarChaosSolverVelocityBoundsMultiplierMACD(TEXT("p.Chaos.Solver.Collision.VelocityBoundsMultiplierMACD"), ChaosSolverVelocityBoundsMultiplierMACD, TEXT("Override velocity bounds multiplier for MACD (if >= 0)"), OnCollisionConfigCVarChanged);
		FAutoConsoleVariableRef CVarChaosSolverMaxVelocityBoundsExpansionMACD(TEXT("p.Chaos.Solver.Collision.MaxVelocityBoundsExpansionMACD"), ChaosSolverMaxVelocityBoundsExpansionMACD, TEXT("Override max velocity bounds expansion for MACD (if >= 0)"), OnCollisionConfigCVarChanged);

		FRealSingle ChaosSolverMaxPushOutVelocity = -1.0f;
		FAutoConsoleVariableRef CVarChaosSolverMaxPushOutVelocity(TEXT("p.Chaos.Solver.Collision.MaxPushOutVelocity"), ChaosSolverMaxPushOutVelocity, TEXT("Override max pushout velocity (if >= 0)"), OnCollisionConfigCVarChanged);

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsSolver::PrepareAdvanceBy

Source code excerpt:

				SetCollisionCullDistance(ChaosSolverCullDistance);
			}
			if ((ChaosSolverVelocityBoundsMultiplier >= 0.0f) && (ChaosSolverMaxVelocityBoundsExpansion >= 0.0f))
			{
				SetVelocityBoundsExpansion(ChaosSolverVelocityBoundsMultiplier, ChaosSolverMaxVelocityBoundsExpansion);
			}
			if ((ChaosSolverVelocityBoundsMultiplierMACD >= 0.0f) && (ChaosSolverMaxVelocityBoundsExpansionMACD >= 0.0f))
			{
				SetVelocityBoundsExpansionMACD(ChaosSolverVelocityBoundsMultiplierMACD, ChaosSolverMaxVelocityBoundsExpansionMACD);
			}
			if (ChaosSolverMaxPushOutVelocity >= 0.0f)