p.ChaosCloth.Solver.DebugHitchInterval

p.ChaosCloth.Solver.DebugHitchInterval

#Overview

name: p.ChaosCloth.Solver.DebugHitchInterval

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.ChaosCloth.Solver.DebugHitchInterval is to create artificial hitches in the Chaos Cloth simulation for debugging simulation jitter. It is used in conjunction with p.ChaosCloth.Solver.DebugHitchLength to control the frequency and duration of these artificial hitches.

This setting variable is primarily used in the Chaos Cloth plugin, which is part of Unreal Engine’s physics simulation system. Specifically, it is utilized in the ChaosClothingSimulationSolver module.

The value of this variable is set through the Unreal Engine console variable system, as evident from the FAutoConsoleVariableRef declaration in the source code.

This variable interacts closely with ClothSolverDebugHitchLength. Together, they control the debugging hitch mechanism. ClothSolverDebugHitchInterval determines the number of frames between hitches, while ClothSolverDebugHitchLength sets the duration of each hitch in milliseconds.

Developers must be aware that this variable is only active in non-shipping builds (#if !UE_BUILD_SHIPPING). It should be used cautiously as it intentionally introduces performance hitches, which can significantly impact the game’s framerate and overall performance.

Best practices when using this variable include:

  1. Only enable it when specifically debugging simulation jitter issues.
  2. Use it in controlled test environments, not in production or near-production scenarios.
  3. Always disable it after debugging to ensure optimal performance.
  4. Use in conjunction with ClothSolverDebugHitchLength for effective debugging.

Regarding the associated variable ClothSolverDebugHitchInterval:

The purpose of ClothSolverDebugHitchInterval is to store the actual value of the debug hitch interval. It is the internal representation of the console variable p.ChaosCloth.Solver.DebugHitchInterval.

This variable is used directly in the Update function of the FClothingSimulationSolver class to control the frequency of artificial hitches. It determines how many frames should pass before the next artificial hitch is introduced.

The value of ClothSolverDebugHitchInterval is set by the console variable system when p.ChaosCloth.Solver.DebugHitchInterval is modified.

Developers should be aware that this variable is only used in non-shipping builds and directly affects the simulation’s performance when active. It should be used judiciously and only for debugging purposes.

Best practices for using ClothSolverDebugHitchInterval include:

  1. Monitoring its value when debugging to ensure it’s set as intended.
  2. Resetting it to 0 when not actively debugging to disable the artificial hitches.
  3. Using it in conjunction with ClothSolverDebugHitchLength for a comprehensive debugging approach.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/ChaosCloth/Source/ChaosCloth/Private/ChaosCloth/ChaosClothingSimulationSolver.cpp:67

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

FAutoConsoleVariableRef CVarClothSolverParallelClothPostUpdate(TEXT("p.ChaosCloth.Solver.ParallelClothPostUpdate"), bClothSolverParallelClothPostUpdate, TEXT("Pre-transform the cloth particles for each cloth in parallel."));
FAutoConsoleVariableRef CVarClothSolverDebugHitchLength(TEXT("p.ChaosCloth.Solver.DebugHitchLength"), ClothSolverDebugHitchLength, TEXT("Hitch length in ms. Create artificial hitches to debug simulation jitter. 0 to disable"));
FAutoConsoleVariableRef CVarClothSolverDebugHitchInterval(TEXT("p.ChaosCloth.Solver.DebugHitchInterval"), ClothSolverDebugHitchInterval, TEXT("Hitch interval in frames. Create artificial hitches to debug simulation jitter. 0 to disable"));
FAutoConsoleVariableRef CVarClothSolverDisableCollision(TEXT("p.ChaosCloth.Solver.DisableCollision"), bClothSolverDisableCollision, TEXT("Disable all collision particles. Needs reset of the simulation (p.ChaosCloth.Reset)."));
#endif

FAutoConsoleVariableRef CVarClothSolverDisableTimeDependentNumIterations(TEXT("p.ChaosCloth.Solver.DisableTimeDependentNumIterations"), bClothSolverDisableTimeDependentNumIterations, TEXT("Make the number of iterations independent from the time step."));
FAutoConsoleVariableRef CVarClothSolverUseVelocityScale(TEXT("p.ChaosCloth.Solver.UseVelocityScale"), bClothSolverUseVelocityScale, TEXT("Use the velocity scale to compensate for clamping to MaxPhysicsDelta, in order to avoid miscalculating velocities during hitches."));
FAutoConsoleVariableRef CVarClothSolverMaxVelocity(TEXT("p.ChaosCloth.Solver.MaxVelocity"), ClothSolverMaxVelocity, TEXT("Maximum relative velocity of the cloth particles relatively to their animated positions equivalent. 0 to disable."));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/ChaosCloth/Source/ChaosCloth/Private/ChaosCloth/ChaosClothingSimulationSolver.cpp:59

Scope (from outer to inner):

file
namespace    Chaos

Source code excerpt:

#if !UE_BUILD_SHIPPING
static int32 ClothSolverDebugHitchLength = 0;
static int32 ClothSolverDebugHitchInterval = 0;
static bool bClothSolverDisableCollision = false;

FAutoConsoleVariableRef CVarClothSolverMinParallelBatchSize(TEXT("p.ChaosCloth.Solver.MinParallelBatchSize"), ClothSolverMinParallelBatchSize, TEXT("The minimum number of particle to process in parallel batch by the solver."));
FAutoConsoleVariableRef CVarClothSolverParallelClothPreUpdate(TEXT("p.ChaosCloth.Solver.ParallelClothPreUpdate"), bClothSolverParallelClothPreUpdate, TEXT("Pre-transform the cloth particles for each cloth in parallel."));
FAutoConsoleVariableRef CVarClothSolverParallelClothUpdate(TEXT("p.ChaosCloth.Solver.ParallelClothUpdate"), bClothSolverParallelClothUpdate, TEXT("Skin the physics mesh and do the other cloth update for each cloth in parallel."));
FAutoConsoleVariableRef CVarClothSolverParallelClothPostUpdate(TEXT("p.ChaosCloth.Solver.ParallelClothPostUpdate"), bClothSolverParallelClothPostUpdate, TEXT("Pre-transform the cloth particles for each cloth in parallel."));
FAutoConsoleVariableRef CVarClothSolverDebugHitchLength(TEXT("p.ChaosCloth.Solver.DebugHitchLength"), ClothSolverDebugHitchLength, TEXT("Hitch length in ms. Create artificial hitches to debug simulation jitter. 0 to disable"));
FAutoConsoleVariableRef CVarClothSolverDebugHitchInterval(TEXT("p.ChaosCloth.Solver.DebugHitchInterval"), ClothSolverDebugHitchInterval, TEXT("Hitch interval in frames. Create artificial hitches to debug simulation jitter. 0 to disable"));
FAutoConsoleVariableRef CVarClothSolverDisableCollision(TEXT("p.ChaosCloth.Solver.DisableCollision"), bClothSolverDisableCollision, TEXT("Disable all collision particles. Needs reset of the simulation (p.ChaosCloth.Reset)."));
#endif

FAutoConsoleVariableRef CVarClothSolverDisableTimeDependentNumIterations(TEXT("p.ChaosCloth.Solver.DisableTimeDependentNumIterations"), bClothSolverDisableTimeDependentNumIterations, TEXT("Make the number of iterations independent from the time step."));
FAutoConsoleVariableRef CVarClothSolverUseVelocityScale(TEXT("p.ChaosCloth.Solver.UseVelocityScale"), bClothSolverUseVelocityScale, TEXT("Use the velocity scale to compensate for clamping to MaxPhysicsDelta, in order to avoid miscalculating velocities during hitches."));
FAutoConsoleVariableRef CVarClothSolverMaxVelocity(TEXT("p.ChaosCloth.Solver.MaxVelocity"), ClothSolverMaxVelocity, TEXT("Maximum relative velocity of the cloth particles relatively to their animated positions equivalent. 0 to disable."));

#Loc: <Workspace>/Engine/Plugins/ChaosCloth/Source/ChaosCloth/Private/ChaosCloth/ChaosClothingSimulationSolver.cpp:1880

Scope (from outer to inner):

file
namespace    Chaos
function     void FClothingSimulationSolver::Update

Source code excerpt:

#if !UE_BUILD_SHIPPING
	// Introduce artificial hitches for debugging any simulation jitter
	if (ClothSolverDebugHitchLength && ClothSolverDebugHitchInterval)
	{
		static int32 HitchCounter = 0;
		if (--HitchCounter < 0)
		{
			UE_LOG(LogChaosCloth, Warning, TEXT("Hitching for %dms"), ClothSolverDebugHitchLength);
			FPlatformProcess::Sleep((float)ClothSolverDebugHitchLength * 0.001f);
			HitchCounter = ClothSolverDebugHitchInterval;
		}
	}
#endif  // #if !UE_BUILD_SHIPPING

	// Update time step
	DeltaTime = InDeltaTime;