bTestQueriesUsingBreadth

bTestQueriesUsingBreadth

#Overview

name: bTestQueriesUsingBreadth

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of bTestQueriesUsingBreadth is to control the testing strategy for Environment Queries in Unreal Engine 5’s AI Module. It determines whether queries should be tested using a breadth-first approach or a depth-first approach.

This setting variable is primarily used by the AI Module, specifically within the Environment Query System (EQS). The main subsystem that relies on this variable is the EnvQueryManager, which is responsible for managing and executing environment queries.

The value of this variable is set in the UEnvQueryManager constructor and can be configured through the FEnvQueryManagerConfig structure. It can be modified at runtime using the Configure() function of the UEnvQueryManager class.

The bTestQueriesUsingBreadth variable interacts with other variables in the EnvQueryManager, such as MaxAllowedTestingTime and QueryCountWarningThreshold. It directly affects the query execution logic in the Tick() function of the EnvQueryManager.

Developers must be aware that:

  1. Setting this to true will cause the manager to test one step of each query before moving to the next query.
  2. Setting it to false will cause the manager to test an entire query before moving to the next one.

Best practices when using this variable include:

  1. Consider the nature of your queries and the desired responsiveness of your AI system when choosing between breadth-first and depth-first testing.
  2. Monitor performance impacts, as the choice between breadth and depth can affect how quickly queries complete and how evenly system resources are distributed among multiple queries.
  3. Use in conjunction with other EQS settings like MaxAllowedTestingTime to fine-tune query execution behavior.
  4. Be consistent in your approach across related systems to maintain predictable behavior.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseGame.ini:213, section: [/Script/AIModule.EnvQueryManager]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Classes/EnvironmentQuery/EnvQueryManager.h:39

Scope: file

Source code excerpt:

	or test an entire query before moving to the next one (depth). */
	UPROPERTY(config)
	bool bTestQueriesUsingBreadth = false;

	/** if greater than zero, we will warn once when the number of queries is greater than or equal to this number, and log the queries out */
	UPROPERTY(config)
	int32 QueryCountWarningThreshold = 200;

	/** how often (in seconds) we will warn about the number of queries (allows us to catch multiple occurrences in a session) */

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Classes/EnvironmentQuery/EnvQueryManager.h:343

Scope (from outer to inner):

file
class        class UEnvQueryManager : public UAISubsystem, public FSelfRegisteringExec

Source code excerpt:

	    or test an entire query before moving to the next one (depth). */
	UPROPERTY(config)
	bool bTestQueriesUsingBreadth;

	/** if greater than zero, we will warn once when the number of queries is greater than or equal to this number, and log the queries out */
	UPROPERTY(config)
	int32 QueryCountWarningThreshold;

	/** how often (in seconds) we will warn about the number of queries (allows us to catch multiple occurrences in a session) */

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/EnvironmentQuery/EnvQueryManager.cpp:179

Scope (from outer to inner):

file
function     UEnvQueryManager::UEnvQueryManager

Source code excerpt:

	NextQueryID = 0;
	MaxAllowedTestingTime = 0.01f;
	bTestQueriesUsingBreadth = true;
	NumRunningQueriesAbortedSinceLastUpdate = 0;

	QueryCountWarningThreshold = 0;
	QueryCountWarningInterval = 30.0;
#if !(UE_BUILD_SHIPPING)
	LastQueryCountWarningThresholdTime = -FLT_MAX;

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/EnvironmentQuery/EnvQueryManager.cpp:536

Scope (from outer to inner):

file
function     void UEnvQueryManager::Tick

Source code excerpt:

				// If we're testing queries using breadth, move on to the next query.
				// If we're testing queries using depth, we only move on to the next query when we finish the current one.
				else if (bTestQueriesUsingBreadth)
				{
					++Index;
				}

				if (QueryInstancePtr->TotalExecutionTime > ExecutionTimeWarningSeconds && !QueryInstancePtr->bHasLoggedTimeLimitWarning)
				{

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/EnvironmentQuery/EnvQueryManager.cpp:553

Scope (from outer to inner):

file
function     void UEnvQueryManager::Tick

Source code excerpt:


			// Start over at the beginning if we are testing using breadth and we've reached the end of the list
			if (bTestQueriesUsingBreadth && (Index == NumRunningQueries))
			{
				Index = 0;
			}

#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)
			if (bAllowEQSTimeSlicing) // if Time slicing is enabled...

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/EnvironmentQuery/EnvQueryManager.cpp:589

Scope (from outer to inner):

file
function     void UEnvQueryManager::Tick

Source code excerpt:

			// When doing depth without any queries aborted since the last update we know how many to remove.
			// Or if we have finished all the queries.  In that case we don't need to check if the queries are finished)
			if ((NumQueriesFinished != RunningQueries.Num()) && (bTestQueriesUsingBreadth || (NumRunningQueriesAbortedSinceLastUpdate > 0)))
			{
				for (int32 Index = RunningQueries.Num() - 1, FinishedQueriesCounter = NumQueriesFinished; Index >= 0 && FinishedQueriesCounter > 0; --Index)
				{
					TSharedPtr<FEnvQueryInstance>& QueryInstance = RunningQueries[Index];
					if (!QueryInstance.IsValid())
					{

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/EnvironmentQuery/EnvQueryManager.cpp:1139

Scope (from outer to inner):

file
function     void UEnvQueryManager::Configure

Source code excerpt:


	MaxAllowedTestingTime = NewConfig.MaxAllowedTestingTime;
	bTestQueriesUsingBreadth = NewConfig.bTestQueriesUsingBreadth;
	QueryCountWarningThreshold = NewConfig.QueryCountWarningThreshold;
	QueryCountWarningInterval = NewConfig.QueryCountWarningInterval;
	ExecutionTimeWarningSeconds = NewConfig.ExecutionTimeWarningSeconds;
	HandlingResultTimeWarningSeconds = NewConfig.HandlingResultTimeWarningSeconds;
	GenerationTimeWarningSeconds = NewConfig.GenerationTimeWarningSeconds;	
}

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/EnvironmentQuery/EnvQueryManager.cpp:1321

Scope (from outer to inner):

file
function     FString FEnvQueryManagerConfig::ToString

Source code excerpt:

FString FEnvQueryManagerConfig::ToString() const
{
	return FString::Printf(TEXT("MaxAllowedTestingTime=%f bTestQueriesUsingBreadth=%d QueryCountWarningThreshold=%d QueryCountWarningInterval=%f ExecutionTimeWarningSeconds=%f HandlingResultTimeWarningSeconds=%f GenerationTimeWarningSeconds=%f"), MaxAllowedTestingTime, bTestQueriesUsingBreadth, QueryCountWarningThreshold, QueryCountWarningInterval, ExecutionTimeWarningSeconds, HandlingResultTimeWarningSeconds, GenerationTimeWarningSeconds);
}