p.SerializeBadSQs

p.SerializeBadSQs

#Overview

name: p.SerializeBadSQs

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.SerializeBadSQs is to enable the creation of scene query captures when there’s a divergence between Chaos and PhysX physics systems in Unreal Engine 5. This setting is primarily used for debugging and performance analysis in the collision system.

This setting variable is part of the Engine module, specifically within the collision subsystem. It’s used in the SceneQueryLowLevel.cpp file, which handles low-level scene queries for collision detection.

The value of this variable is set through a console variable (CVar) system in Unreal Engine. It’s defined as an integer and initialized to 0, but can be changed at runtime through console commands or configuration files.

p.SerializeBadSQs interacts with several other variables, notably:

  1. SerializeSQs: Controls general scene query serialization.
  2. ReplaySQs: Enables rerunning scene queries against Chaos.
  3. EnableRaycastSQCapture, EnableOverlapSQCapture, EnableSweepSQCapture: Control which types of scene queries are considered for serialization.

Developers should be aware that enabling this variable can have performance implications. When enabled, it creates a scene query capture whenever Chaos and PhysX physics results diverge, which can be computationally expensive as it involves saving out the entire scene.

Best practices for using this variable include:

  1. Use it primarily for debugging purposes, not in production builds.
  2. Be cautious of performance impacts when enabled.
  3. Use in conjunction with other scene query serialization settings for comprehensive debugging.
  4. Disable in performance-critical scenarios.

Regarding the associated variable SerializeBadSQs:

The purpose of SerializeBadSQs is the same as p.SerializeBadSQs. It’s the actual integer variable that stores the value set by the console variable p.SerializeBadSQs.

This variable is used directly in the code to check if bad scene query serialization should occur. It’s checked in the FinalizeCapture function when a mismatch between Chaos and PhysX is detected.

The value of SerializeBadSQs is set through the console variable system, specifically by p.SerializeBadSQs.

SerializeBadSQs interacts with SerializeSQs in a conditional statement. If SerializeBadSQs is true and SerializeSQs is false, a “BadSQCapture” will be serialized.

Developers should be aware that this variable directly controls the behavior of scene query serialization when mismatches occur. Its value should be managed carefully to balance debugging needs with performance considerations.

Best practices for SerializeBadSQs align with those of p.SerializeBadSQs, as they are essentially two representations of the same setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp:26

Scope: file

Source code excerpt:

FAutoConsoleVariableRef CVarSerializeSQSamples(TEXT("p.SerializeSQSampleCount"), SerializeSQSamples, TEXT("If Query exceeds duration threshold, we will re-measure SQ this many times before serializing. Larger values cause hitching."));
FAutoConsoleVariableRef CVarReplaySweeps(TEXT("p.ReplaySQs"), ReplaySQs, TEXT("If enabled, we rerun the sq against chaos"));
FAutoConsoleVariableRef CVarSerializeBadSweeps(TEXT("p.SerializeBadSQs"), SerializeBadSQs, TEXT("If enabled, we create a sq capture whenever chaos and physx diverge"));
FAutoConsoleVariableRef CVarSerializeSQsRaycastEnabled(TEXT("p.SerializeSQsRaycastEnabled"), EnableRaycastSQCapture, TEXT("If disabled, p.SerializeSQs will not consider raycasts"));
FAutoConsoleVariableRef CVarSerializeSQsOverlapEnabled(TEXT("p.SerializeSQsOverlapEnabled"), EnableOverlapSQCapture, TEXT("If disabled, p.SerializeSQs will not consider overlaps"));
FAutoConsoleVariableRef CVarSerializeSQsSweepEnabled(TEXT("p.SerializeSQsSweepEnabled"), EnableSweepSQCapture, TEXT("If disabled, p.SerializeSQs will not consider sweeps"));
#else
constexpr int32 SerializeSQs = 0;
constexpr int32 ReplaySQs = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp:17

Scope: file

Source code excerpt:

int32 SerializeSQs = 0;
int32 SerializeSQSamples = 100;
int32 SerializeBadSQs = 0;
int32 ReplaySQs = 0;
int32 EnableRaycastSQCapture = 1;
int32 EnableOverlapSQCapture = 1;
int32 EnableSweepSQCapture = 1;

FAutoConsoleVariableRef CVarSerializeSQs(TEXT("p.SerializeSQs"), SerializeSQs, TEXT("If enabled, we create a sq capture per sq that takes more than provided value in microseconds. This can be very expensive as the entire scene is saved out"));
FAutoConsoleVariableRef CVarSerializeSQSamples(TEXT("p.SerializeSQSampleCount"), SerializeSQSamples, TEXT("If Query exceeds duration threshold, we will re-measure SQ this many times before serializing. Larger values cause hitching."));
FAutoConsoleVariableRef CVarReplaySweeps(TEXT("p.ReplaySQs"), ReplaySQs, TEXT("If enabled, we rerun the sq against chaos"));
FAutoConsoleVariableRef CVarSerializeBadSweeps(TEXT("p.SerializeBadSQs"), SerializeBadSQs, TEXT("If enabled, we create a sq capture whenever chaos and physx diverge"));
FAutoConsoleVariableRef CVarSerializeSQsRaycastEnabled(TEXT("p.SerializeSQsRaycastEnabled"), EnableRaycastSQCapture, TEXT("If disabled, p.SerializeSQs will not consider raycasts"));
FAutoConsoleVariableRef CVarSerializeSQsOverlapEnabled(TEXT("p.SerializeSQsOverlapEnabled"), EnableOverlapSQCapture, TEXT("If disabled, p.SerializeSQs will not consider overlaps"));
FAutoConsoleVariableRef CVarSerializeSQsSweepEnabled(TEXT("p.SerializeSQsSweepEnabled"), EnableSweepSQCapture, TEXT("If disabled, p.SerializeSQs will not consider sweeps"));
#else
constexpr int32 SerializeSQs = 0;
constexpr int32 ReplaySQs = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp:55

Scope (from outer to inner):

file
namespace    anonymous
function     void FinalizeCapture

Source code excerpt:

			{
				UE_LOG(LogPhysicsCore, Warning, TEXT("Chaos SQ does not match physx"));
				if (SerializeBadSQs && !SerializeSQs)
				{
					Serializer.Serialize(TEXT("BadSQCapture"));
				}
			}
		}
#endif