CriticalPathStall.TickStartFrame

CriticalPathStall.TickStartFrame

#Overview

name: CriticalPathStall.TickStartFrame

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 CriticalPathStall.TickStartFrame is to introduce an intentional delay at the start of each frame for debugging and critical path analysis in Unreal Engine 5. This setting variable is primarily used in the engine’s tick system, which is responsible for managing and executing periodic tasks in the game loop.

This setting variable is part of the Engine module, specifically within the tick management system. It is implemented in the TickTaskManager.cpp file, which is part of the core engine functionality.

The value of this variable is set through a console variable (CVarStallStartFrame) using the TAutoConsoleVariable template. It is initialized with a default value of 0.0f, meaning no delay by default.

The associated variable CVarStallStartFrame directly interacts with CriticalPathStall.TickStartFrame. They share the same value and purpose.

Developers must be aware of the following when using this variable:

  1. It is intended for debugging and critical path analysis only.
  2. The value is in milliseconds, so even small values can have a noticeable impact on performance.
  3. It is only active in non-shipping builds (conditional compilation with #if !UE_BUILD_SHIPPING).

Best practices when using this variable include:

  1. Use it sparingly and only when necessary for debugging or analysis.
  2. Remember to reset it to 0.0f after debugging to avoid unintended performance impacts.
  3. Be cautious when using large values, as it can significantly slow down the game’s frame rate.

Regarding the associated variable CVarStallStartFrame:

The purpose of CVarStallStartFrame is to provide a programmable interface to the CriticalPathStall.TickStartFrame setting. It allows developers to modify the stall time at runtime through console commands or code.

CVarStallStartFrame is used in the FTickTaskManager class, specifically in the StartFrame function. This function is called at the beginning of each frame, where the intentional stall is applied if the value is greater than 0.

The value of CVarStallStartFrame can be set and retrieved using console commands or through C++ code using the GetValueOnGameThread() method.

Developers should be aware that changes to CVarStallStartFrame will directly affect the game’s performance, and it should only be used for debugging and analysis purposes.

Best practices for using CVarStallStartFrame include:

  1. Use it in conjunction with profiling tools to analyze the impact of frame start delays on the game’s critical path.
  2. Reset the value to 0.0f when not actively debugging to ensure normal performance.
  3. Consider using this variable in automated testing scenarios to simulate different performance conditions.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TickTaskManager.cpp:30

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarStallStartFrame(
	TEXT("CriticalPathStall.TickStartFrame"),
	0.0f,
	TEXT("Sleep for the given time in start frame. Time is given in ms. This is a debug option used for critical path analysis and forcing a change in the critical path."));

static TAutoConsoleVariable<int32> CVarLogTicks(
	TEXT("tick.LogTicks"),
	0,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TickTaskManager.cpp:29

Scope: file

Source code excerpt:

CSV_DECLARE_CATEGORY_MODULE_EXTERN(CORE_API, Basic);

static TAutoConsoleVariable<float> CVarStallStartFrame(
	TEXT("CriticalPathStall.TickStartFrame"),
	0.0f,
	TEXT("Sleep for the given time in start frame. Time is given in ms. This is a debug option used for critical path analysis and forcing a change in the critical path."));

static TAutoConsoleVariable<int32> CVarLogTicks(
	TEXT("tick.LogTicks"),

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TickTaskManager.cpp:1474

Scope (from outer to inner):

file
class        class FTickTaskManager : public FTickTaskManagerInterface
function     virtual void StartFrame

Source code excerpt:


#if !UE_BUILD_SHIPPING
		if (CVarStallStartFrame.GetValueOnGameThread() > 0.0f)
		{
			QUICK_SCOPE_CYCLE_COUNTER(STAT_Tick_Intentional_Stall);
			FPlatformProcess::Sleep(CVarStallStartFrame.GetValueOnGameThread() / 1000.0f);
		}
#endif
		Context.TickGroup = ETickingGroup(0); // reset this to the start tick group
		Context.DeltaSeconds = InDeltaSeconds;
		Context.TickType = InTickType;
		Context.Thread = ENamedThreads::GameThread;