csv.RecordActorCountThreshold

csv.RecordActorCountThreshold

#Overview

name: csv.RecordActorCountThreshold

This variable is created as a Console Variable (cvar).

• type: Var
• help: Number of instances of a native Actor class required before recording to a CSV stat

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of csv.RecordActorCountThreshold is to set a threshold for recording Actor class instance counts in CSV stats. This setting is used in the World Metrics system of Unreal Engine 5, specifically for CSV metrics collection.

This setting variable is primarily used in the CsvMetrics module, which is part of the WorldMetrics plugin. The subsystem that relies on this variable is the CSV profiling system, which is used for performance monitoring and analysis.

The value of this variable is set through a console variable (CVar) system. It is initialized with a default value of 5, but can be changed at runtime through console commands or configuration files.

The associated variable CVarCsvRecordActorCountThreshold directly interacts with csv.RecordActorCountThreshold. They share the same value and purpose.

Developers must be aware that this threshold affects the granularity of actor count reporting in CSV stats. Only actor classes with instance counts exceeding this threshold will be recorded. This can help reduce noise in the collected data by focusing on more significant actor populations.

Best practices when using this variable include:

1. Adjusting the threshold based on the scale of your game world and the level of detail required in profiling.
2. Considering the performance impact of setting a very low threshold in large worlds with many actor types.
3. Using this in conjunction with other CSV profiling tools for a comprehensive performance analysis.

Regarding the associated variable CVarCsvRecordActorCountThreshold:

The purpose of CVarCsvRecordActorCountThreshold is to provide programmatic access to the csv.RecordActorCountThreshold setting within the C++ code.

This variable is used in the CsvActorCountMetric class to determine which actor counts should be recorded during CSV profiling sessions. It’s accessed in the Update function of the UCsvActorCountMetric class.

The value of this variable is set through the TAutoConsoleVariable template, which links it to the console variable system.

Developers should be aware that changes to this variable will immediately affect the behavior of the actor count metric collection. It’s thread-safe, as evidenced by the use of GetValueOnAnyThread() when accessing its value.

Best practices for using CVarCsvRecordActorCountThreshold include:

1. Accessing its value at the point of use rather than caching it, to ensure the most up-to-date setting is always used.
2. Considering the impact on performance and data collection when modifying this value during runtime.
3. Documenting any project-specific modifications to this threshold to ensure consistent profiling across the development team.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/WorldMetrics/Source/CsvMetrics/Private/CsvActorCountMetric.cpp:14

Scope (from outer to inner):

file
namespace    UE::WorldMetrics::Private

Source code excerpt:

{
static TAutoConsoleVariable<int32> CVarCsvRecordActorCountThreshold(
	TEXT("csv.RecordActorCountThreshold"),
	5,
	TEXT("Number of instances of a native Actor class required before recording to a CSV stat"));

}  // namespace UE::WorldMetrics::Private

//---------------------------------------------------------------------------------------------------------------------

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/WorldMetrics/Source/CsvMetrics/Private/CsvActorCountMetric.cpp:13

Scope (from outer to inner):

file
namespace    UE::WorldMetrics::Private

Source code excerpt:

namespace UE::WorldMetrics::Private
{
static TAutoConsoleVariable<int32> CVarCsvRecordActorCountThreshold(
	TEXT("csv.RecordActorCountThreshold"),
	5,
	TEXT("Number of instances of a native Actor class required before recording to a CSV stat"));

}  // namespace UE::WorldMetrics::Private

#Loc: <Workspace>/Engine/Plugins/WorldMetrics/Source/CsvMetrics/Private/CsvActorCountMetric.cpp:56

Scope (from outer to inner):

file
function     void UCsvActorCountMetric::Update

Source code excerpt:

	if (FCsvProfiler::Get()->IsCapturing())
	{
		const int32 Threshold = UE::WorldMetrics::Private::CVarCsvRecordActorCountThreshold.GetValueOnAnyThread();
		for (const TPair<FName, int32>& ActorClassNameCount : ActorClassNameCounter)
		{
			if (ActorClassNameCount.Value > Threshold)
			{
				FCsvProfiler::Get()->RecordCustomStat(
					ActorClassNameCount.Key, CSV_CATEGORY_INDEX(ActorCount), ActorClassNameCount.Value,