r.DebugSafeZone.MaxDebugTextStringsPerActor

r.DebugSafeZone.MaxDebugTextStringsPerActor

#Overview

name: r.DebugSafeZone.MaxDebugTextStringsPerActor

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

• type: Var
• help: The maximum number of debug strings that can be attached to a given actor (<=0 : no limit)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.DebugSafeZone.MaxDebugTextStringsPerActor is to limit the number of debug text strings that can be attached to a single actor in Unreal Engine. This setting is part of the debugging and development tools, specifically related to the HUD (Heads-Up Display) system.

This setting variable is primarily used in the Engine module, particularly in the HUD implementation. It’s referenced in the Engine/Private/HUD.cpp file, which is part of the core engine functionality for creating and managing heads-up displays in games.

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

The variable interacts directly with its associated variable GMaxDebugTextStringsPerActorCVar, which is the actual C++ variable that stores and provides access to the value set by r.DebugSafeZone.MaxDebugTextStringsPerActor.

Developers should be aware that:

1. Setting this value to 0 or a negative number removes the limit on debug strings per actor.
2. This limit applies on a per-actor basis, not globally.
3. Changing this value can affect performance and memory usage, especially in scenes with many actors displaying debug information.

Best practices when using this variable include:

1. Keep the limit reasonably low in production builds to prevent potential performance issues.
2. Increase the limit temporarily during debugging sessions if more information is needed.
3. Consider disabling or reducing debug text in shipping builds.

Regarding the associated variable GMaxDebugTextStringsPerActorCVar:

The purpose of GMaxDebugTextStringsPerActorCVar is to provide programmatic access to the r.DebugSafeZone.MaxDebugTextStringsPerActor setting within the C++ code.

This variable is used directly in the Engine module, specifically in the HUD implementation (HUD.cpp).

Its value is set by the console variable system and can be accessed in code using the GetValueOnGameThread() method.

GMaxDebugTextStringsPerActorCVar interacts directly with the debug text system in the HUD class, controlling how many debug strings can be added to an actor.

Developers should be aware that:

1. This variable provides the actual limit used in the code.
2. It’s accessed on the game thread, which could have performance implications if called frequently.

Best practices when using this variable include:

1. Cache the value if it’s needed frequently, rather than calling GetValueOnGameThread() repeatedly.
2. Use this variable when implementing custom debug drawing systems that need to respect the global limit.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HUD.cpp:52

Scope: file

Source code excerpt:

TAutoConsoleVariable<int32> GMaxDebugTextStringsPerActorCVar(
	TEXT("r.DebugSafeZone.MaxDebugTextStringsPerActor"),
	128,
	TEXT("The maximum number of debug strings that can be attached to a given actor (<=0 : no limit)"));

#if ENABLE_DRAW_DEBUG
TAutoConsoleVariable<int32> GDrawCurrentDebugTargetBoundingBox(
	TEXT("r.Debug.DrawCurrentDebugTargetBoundingBox"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HUD.cpp:51

Scope: file

Source code excerpt:

	TEXT(" default: 0.2"));

TAutoConsoleVariable<int32> GMaxDebugTextStringsPerActorCVar(
	TEXT("r.DebugSafeZone.MaxDebugTextStringsPerActor"),
	128,
	TEXT("The maximum number of debug strings that can be attached to a given actor (<=0 : no limit)"));

#if ENABLE_DRAW_DEBUG
TAutoConsoleVariable<int32> GDrawCurrentDebugTargetBoundingBox(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/HUD.cpp:826

Scope (from outer to inner):

file
function     void AHUD::AddDebugText_Implementation

Source code excerpt:

				{
					// if there's a max number per actor, respect it : 
					int32 MaxNumStrings = GMaxDebugTextStringsPerActorCVar.GetValueOnGameThread();
					if ((MaxNumStrings <= 0) || (NumElements < MaxNumStrings))
					{
						DebugTextInfo = &DebugTextList.EmplaceAt_GetRef(LastIdx + 1);
					}
				}
			}