p.Chaos.Solver.Collision.CullDistance

p.Chaos.Solver.Collision.CullDistance

#Overview

name: p.Chaos.Solver.Collision.CullDistance

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

• type: Var
• help: Override cull distance (if >= 0)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of p.Chaos.Solver.Collision.CullDistance is to override the cull distance for collision detection in the Chaos physics solver. This setting is part of Unreal Engine’s Chaos physics system, which is an experimental physics engine introduced in Unreal Engine 5.

This setting variable is primarily used in the Chaos physics subsystem, specifically within the PBDRigidsSolver (Position Based Dynamics Rigid Solver) module. It’s part of the collision detection and culling process 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 -1.0f and can be changed at runtime through console commands or programmatically.

The associated variable ChaosSolverCullDistance interacts directly with p.Chaos.Solver.Collision.CullDistance. They share the same value, with ChaosSolverCullDistance being the actual variable used in the code, while p.Chaos.Solver.Collision.CullDistance is the console variable name used to set its value.

Developers must be aware that:

1. This variable only takes effect if its value is greater than or equal to 0.
2. It overrides the engine configuration if set to a valid value (>= 0).
3. Changes to this variable trigger the OnCollisionConfigCVarChanged callback, which likely updates the physics simulation settings.

Best practices when using this variable include:

1. Only set it when you need to override the default cull distance behavior.
2. Be cautious when changing this value, as it can significantly impact performance and simulation accuracy.
3. Test thoroughly after changing this value to ensure it doesn’t negatively impact your game’s physics behavior.

Regarding the associated variable ChaosSolverCullDistance:

• Its purpose is to store the actual cull distance value used in the Chaos solver.
• It’s used directly in the FPBDRigidsSolver::PrepareAdvanceBy function to set the collision cull distance if its value is valid (>= 0).
• It’s initialized with a default value of -1.0f, which means it won’t override the engine configuration unless explicitly set.
• Developers should be aware that this variable is the actual one used in the physics calculations, while p.Chaos.Solver.Collision.CullDistance is just the means to set it via console commands.

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// These override the engine config if >= 0
		FRealSingle ChaosSolverCullDistance = -1.0f;
		FAutoConsoleVariableRef CVarChaosSolverCullDistance(TEXT("p.Chaos.Solver.Collision.CullDistance"), ChaosSolverCullDistance, TEXT("Override cull distance (if >= 0)"), OnCollisionConfigCVarChanged);

		// @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

#Associated Variable and Callsites

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

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

Scope (from outer to inner):

file
namespace    Chaos
namespace    CVars

Source code excerpt:

		// These override the engine config if >= 0
		FRealSingle ChaosSolverCullDistance = -1.0f;
		FAutoConsoleVariableRef CVarChaosSolverCullDistance(TEXT("p.Chaos.Solver.Collision.CullDistance"), ChaosSolverCullDistance, TEXT("Override cull distance (if >= 0)"), OnCollisionConfigCVarChanged);

		// @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

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

Scope (from outer to inner):

file
namespace    Chaos
function     void FPBDRigidsSolver::PrepareAdvanceBy

Source code excerpt:

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