p.LevelSetFailureOnHighError

p.LevelSetFailureOnHighError

#Overview

name: p.LevelSetFailureOnHighError

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.LevelSetFailureOnHighError is to control the behavior of the level set system when it encounters high error levels during generation or processing. This setting is part of the Chaos physics simulation system in Unreal Engine 5, specifically related to the level set functionality.

This variable is used in the Experimental Chaos module of Unreal Engine 5. The Chaos physics system relies on this setting to determine how to handle cases where the generated level set has a high error compared to the original geometry.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an integer (int32) named FailureOnHighError, which is then exposed as a console variable named “p.LevelSetFailureOnHighError”.

The associated variable FailureOnHighError directly interacts with p.LevelSetFailureOnHighError. They share the same value, as FailureOnHighError is the actual variable used in the code, while p.LevelSetFailureOnHighError is the console variable name used to set its value.

Developers must be aware that when this variable is set to a non-zero value, it will cause the system to set level sets with high error to null in the solver. This can have significant impacts on the physics simulation, as it effectively removes problematic level sets from consideration.

Best practices when using this variable include:

  1. Use it for debugging and quality control in development builds.
  2. Be cautious when enabling it in production, as it may cause unexpected behavior in the physics simulation.
  3. When enabled, monitor the performance and stability of the physics system closely.
  4. Use in conjunction with other level set error tolerance settings (p.LevelSetAvgDistErrorTolerance and p.LevelSetMaxDistErrorTolerance) for fine-tuned control.

Regarding the associated variable FailureOnHighError:

The purpose of FailureOnHighError is to serve as the actual boolean flag checked in the code to determine if high-error level sets should be nullified.

It’s used directly in the Chaos physics system, specifically in the level set generation and validation process.

Its value is set through the p.LevelSetFailureOnHighError console variable.

It interacts closely with other error tolerance variables like AvgDistErrorTolerance and MaxDistErrorTolerance.

Developers should be aware that this variable directly controls the behavior of the level set system when errors are encountered. When set to true (non-zero), it will cause high-error level sets to be nullified, potentially affecting physics simulations.

Best practices for FailureOnHighError include:

  1. Use it in conjunction with proper error reporting and logging to track when and why level sets are being nullified.
  2. Consider exposing this setting to technical artists or gameplay programmers who may need to fine-tune physics behavior.
  3. Be prepared to adjust related error tolerance settings if this flag is causing too many level sets to be nullified.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Levelset.cpp:20

Scope: file

Source code excerpt:


int32 FailureOnHighError = 0;
FAutoConsoleVariableRef CVarFailureOnHighError(TEXT("p.LevelSetFailureOnHighError"), FailureOnHighError, TEXT("Set level sets with high error to null in the solver"));

Chaos::FRealSingle AvgDistErrorTolerance = 1.f;
FAutoConsoleVariableRef CVarAvgDistErrorTolerance(TEXT("p.LevelSetAvgDistErrorTolerance"), AvgDistErrorTolerance, TEXT("Error tolerance for average distance between the triangles and generated levelset.  Note this is a fraction of the average bounding box dimensions."));

Chaos::FRealSingle MaxDistErrorTolerance = 1.f;
FAutoConsoleVariableRef CVarMaxDistErrorTolerance(TEXT("p.LevelSetMaxDistErrorTolerance"), MaxDistErrorTolerance, TEXT("Max error for the highest error triangle generated from a levelset.  Note this is a fraction of the average bounding box dimensions."));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Levelset.cpp:19

Scope: file

Source code excerpt:

FAutoConsoleVariableRef CVarOutputFailedLevelSetDebugData(TEXT("p.LevelSetOutputFailedDebugData"), OutputFailedLevelSetDebugData, TEXT("Output debug obj files for level set and mesh when error tolerances are too high"));

int32 FailureOnHighError = 0;
FAutoConsoleVariableRef CVarFailureOnHighError(TEXT("p.LevelSetFailureOnHighError"), FailureOnHighError, TEXT("Set level sets with high error to null in the solver"));

Chaos::FRealSingle AvgDistErrorTolerance = 1.f;
FAutoConsoleVariableRef CVarAvgDistErrorTolerance(TEXT("p.LevelSetAvgDistErrorTolerance"), AvgDistErrorTolerance, TEXT("Error tolerance for average distance between the triangles and generated levelset.  Note this is a fraction of the average bounding box dimensions."));

Chaos::FRealSingle MaxDistErrorTolerance = 1.f;
FAutoConsoleVariableRef CVarMaxDistErrorTolerance(TEXT("p.LevelSetMaxDistErrorTolerance"), MaxDistErrorTolerance, TEXT("Max error for the highest error triangle generated from a levelset.  Note this is a fraction of the average bounding box dimensions."));

#Loc: <Workspace>/Engine/Source/Runtime/Experimental/Chaos/Private/Chaos/Levelset.cpp:590

Scope (from outer to inner):

file
namespace    Chaos
function     bool FLevelSet::CheckData

Source code excerpt:

		}

		if (FailureOnHighError)
		{
			FString ErrorStr = FString::Printf(TEXT("High error for level set: AvgDistError: %f (Max: %f*%f), MaxDistError: %f (Max: %f*%f), AvgAngleError: %f (Max: %f)"), 
				AvgDistError, AvgDistErrorTolerance, MGrid.Dx().Size(),
				MaxDistError, MaxDistErrorTolerance, MGrid.Dx().Size(),
				AvgAngleError, AvgAngleErrorTolerance);
			ErrorReporter.ReportError(*ErrorStr);