p.Chaos.Solver.Sleep.Defaults.SleepCounterThreshold

p.Chaos.Solver.Sleep.Defaults.SleepCounterThreshold

#Overview

name: p.Chaos.Solver.Sleep.Defaults.SleepCounterThreshold

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.Chaos.Solver.Sleep.Defaults.SleepCounterThreshold is to control the sleep behavior of particles in the Chaos physics system within Unreal Engine 5. Specifically, it sets the default counter threshold for determining when a particle should enter a sleep state.

This setting variable is primarily used by the Chaos physics system, which is part of Unreal Engine’s experimental physics simulation module. Based on the callsites, it’s clear that this variable is utilized in the Island Manager component of the Chaos system, which handles grouping of interacting physics objects.

The value of this variable is set through a console variable (CVar) system, allowing it to be adjusted at runtime. It’s initialized with a default value of 20 in the source code.

The associated variable ChaosSolverCollisionDefaultSleepCounterThreshold directly interacts with this setting. They share the same value, with the CVar acting as an interface to modify the internal variable.

Developers should be aware that this threshold affects how quickly physics objects in the simulation will enter a sleep state. A higher value will make objects take longer to sleep, potentially increasing simulation accuracy but at the cost of performance. Conversely, a lower value will allow objects to sleep more quickly, improving performance but potentially at the cost of simulation fidelity.

Best practices when using this variable include:

  1. Balancing performance and simulation accuracy based on the specific needs of the project.
  2. Testing different values to find the optimal setting for the particular use case.
  3. Considering the interaction with other sleep-related variables, such as linear and angular sleep thresholds.
  4. Being cautious about setting the value too low, which could cause objects to sleep prematurely and behave unrealistically.

Regarding the associated variable ChaosSolverCollisionDefaultSleepCounterThreshold:

This variable is the internal representation of the sleep counter threshold in the Chaos physics system. It’s used directly in the physics simulation code to determine when a particle should enter a sleep state.

The variable is primarily used in the Chaos::CVars namespace and is referenced in test code, indicating its importance in both the core simulation and in verifying the correct behavior of the physics system.

The value of this variable is set directly in the code (with a default of 20) but can be modified through the associated CVar (p.Chaos.Solver.Sleep.Defaults.SleepCounterThreshold).

Developers should be aware that modifying this variable directly in code will be overridden by any CVar settings. It’s generally better to use the CVar system to adjust this value for consistency and to allow for runtime modifications.

Best practices for this variable align with those of the CVar, focusing on finding the right balance between performance and simulation accuracy for the specific project requirements.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Island/IslandManager.cpp:51

Scope (from outer to inner):

file
namespace    Chaos::CVars

Source code excerpt:

	/** Cvar to override the sleep counter threshold if necessary */
	int32 ChaosSolverCollisionDefaultSleepCounterThreshold = 20;
	FAutoConsoleVariableRef CVarChaosSolverCollisionDefaultSleepCounterThreshold(TEXT("p.Chaos.Solver.Sleep.Defaults.SleepCounterThreshold"), ChaosSolverCollisionDefaultSleepCounterThreshold, TEXT("Default counter threshold for sleeping.[def:20]"));

	/** Cvar to override the sleep linear threshold if necessary */
	FRealSingle ChaosSolverCollisionDefaultLinearSleepThreshold = 0.001f; // .001 unit mass cm
	FAutoConsoleVariableRef CVarChaosSolverCollisionDefaultLinearSleepThreshold(TEXT("p.Chaos.Solver.Sleep.Defaults.LinearSleepThreshold"), ChaosSolverCollisionDefaultLinearSleepThreshold, TEXT("Default linear threshold for sleeping.[def:0.001]"));

	/** Cvar to override the sleep angular threshold if necessary */

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Programs/HeadlessChaos/Private/HeadlessChaosTestGraphEvolution.cpp:319

Scope (from outer to inner):

file
namespace    ChaosTest
function     GTEST_TEST

Source code excerpt:

		Test.AdvanceUntilSleeping();

		// Particle should be asleep and it should have taken 21 ticks (ChaosSolverCollisionDefaultSleepCounterThreshold)
		EXPECT_TRUE(Test.ParticleHandles[0]->IsSleeping());
		EXPECT_EQ(Test.TickCount, 21);
	}

	// Wait for all particles to go to sleep naturally (i.e., as part of the tick and not by explicitly setting the state)
	// then check that the islands are preserved.

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Island/IslandManager.cpp:50

Scope (from outer to inner):

file
namespace    Chaos::CVars

Source code excerpt:


	/** Cvar to override the sleep counter threshold if necessary */
	int32 ChaosSolverCollisionDefaultSleepCounterThreshold = 20;
	FAutoConsoleVariableRef CVarChaosSolverCollisionDefaultSleepCounterThreshold(TEXT("p.Chaos.Solver.Sleep.Defaults.SleepCounterThreshold"), ChaosSolverCollisionDefaultSleepCounterThreshold, TEXT("Default counter threshold for sleeping.[def:20]"));

	/** Cvar to override the sleep linear threshold if necessary */
	FRealSingle ChaosSolverCollisionDefaultLinearSleepThreshold = 0.001f; // .001 unit mass cm
	FAutoConsoleVariableRef CVarChaosSolverCollisionDefaultLinearSleepThreshold(TEXT("p.Chaos.Solver.Sleep.Defaults.LinearSleepThreshold"), ChaosSolverCollisionDefaultLinearSleepThreshold, TEXT("Default linear threshold for sleeping.[def:0.001]"));

	/** Cvar to override the sleep angular threshold if necessary */

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Island/IslandManager.cpp:174

Scope (from outer to inner):

file
namespace    Chaos::Private
function     bool GetIslandParticleSleepThresholds

Source code excerpt:

				OutSleepLinearThreshold = ParticleSleepThresholdMultiplier * CVars::ChaosSolverCollisionDefaultLinearSleepThreshold;
				OutSleepAngularThreshold = ParticleSleepThresholdMultiplier * CVars::ChaosSolverCollisionDefaultAngularSleepThreshold;
				OutSleepCounterThreshold = CVars::ChaosSolverCollisionDefaultSleepCounterThreshold;
			}

			// Adjust angular threshold for size. It is equivalent to converting the angular threshold into a linear
			// movement threshold at the extreme points on the particle.
			const FRealSingle AngularSleepThresholdSize = CVars::ChaosSolverCollisionAngularSleepThresholdSize;
			if ((AngularSleepThresholdSize > 0) && Rigid->HasBounds())