p.ReplaySQs

p.ReplaySQs

#Overview

name: p.ReplaySQs

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.ReplaySQs is to enable or disable the rerunning of scene queries (SQs) against the Chaos physics engine. This setting variable is primarily used for debugging and comparison purposes in the collision system of Unreal Engine 5.

The Unreal Engine subsystem that relies on this setting variable is the collision system, specifically the scene query functionality. It is used in the Engine module, as evident from the file path Engine/Source/Runtime/Engine/Private/Collision/SceneQueryLowLevel.cpp.

The value of this variable is set through a console variable (CVar) named “p.ReplaySQs”. It is initialized to 0 (disabled) by default, but can be changed at runtime through the console or configuration files.

This variable interacts with several other variables related to scene query serialization and debugging:

Developers must be aware that enabling this variable (setting it to 1) will cause the engine to rerun scene queries against the Chaos physics engine. This can be computationally expensive and may impact performance, especially in complex scenes or when used frequently.

Best practices when using this variable include:

  1. Only enable it when necessary for debugging or comparison purposes.
  2. Be mindful of the performance impact, especially in production builds.
  3. Use it in conjunction with other related variables (like SerializeBadSQs) for comprehensive debugging.
  4. Disable it when not actively debugging to avoid unnecessary performance overhead.

Regarding the associated variable ReplaySQs:

The purpose of ReplaySQs is the same as p.ReplaySQs. It’s an internal variable that directly corresponds to the console variable p.ReplaySQs.

This variable is used within the collision system of the Engine module. Its value is set by the console variable p.ReplaySQs through the FAutoConsoleVariableRef mechanism.

ReplaySQs interacts with other debugging variables in the scene query system, particularly SerializeBadSQs. For example, if ReplaySQs is enabled and a mismatch is detected between Chaos and PhysX results, it can trigger additional serialization if SerializeBadSQs is also enabled.

Developers should be aware that this variable is used in conditional statements to determine whether to replay scene queries and potentially trigger additional debugging actions.

Best practices for ReplaySQs are the same as for p.ReplaySQs, as they are essentially the same variable exposed through different mechanisms (console variable vs. internal C++ variable).

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

Scope: file

Source code excerpt:

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;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

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;
constexpr int32 SerializeSQSamples = 0;
constexpr int32 EnableRaycastSQCapture = 0;
constexpr int32 EnableOverlapSQCapture = 0;
constexpr int32 EnableSweepSQCapture = 0;
#endif

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

Scope (from outer to inner):

file
namespace    anonymous
function     void FinalizeCapture

Source code excerpt:

		}
#if 0
		if (ReplaySQs)
		{
			const bool bReplaySuccess = SQComparisonHelper(Serializer);
			if (!bReplaySuccess)
			{
				UE_LOG(LogPhysicsCore, Warning, TEXT("Chaos SQ does not match physx"));
				if (SerializeBadSQs && !SerializeSQs)