au.MaxRandomBranches

au.MaxRandomBranches

#Overview

name: au.MaxRandomBranches

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of au.MaxRandomBranches is to control the maximum number of branches that can be played from a random sound node in Unreal Engine’s audio system. It is used to optimize memory usage by limiting the number of sound branches loaded and ready for playback.

This setting variable is primarily used in the Unreal Engine’s audio subsystem, specifically within the random sound node functionality. It is referenced in the Engine module, particularly in the SoundNodeRandom class.

The value of this variable is set through a console variable (CVar) system. It can be adjusted at runtime or set in configuration files.

The au.MaxRandomBranches variable interacts directly with a static integer variable named MaxRandomBranchesCVar. They share the same value, with MaxRandomBranchesCVar serving as the actual storage for the setting.

Developers must be aware that:

  1. Setting this variable to 0 means no culling will occur, and all branches will be loaded.
  2. Any value greater than 0 will limit the number of branches loaded for each random sound node.
  3. This setting can significantly impact memory usage and load times for audio assets.

Best practices when using this variable include:

  1. Carefully consider the trade-off between variety in sound playback and memory usage.
  2. Monitor performance and memory usage when adjusting this value.
  3. Use in conjunction with the MaxNumRandomBranches project setting for platform-specific optimizations.

Regarding the associated variable MaxRandomBranchesCVar:

The purpose of MaxRandomBranchesCVar is to store the actual value of the au.MaxRandomBranches setting within the engine’s code.

This variable is used directly in the Engine module, specifically in the USoundNodeRandom class to determine the number of branches to preselect.

The value of MaxRandomBranchesCVar is set through the FAutoConsoleVariableRef system, which links it to the au.MaxRandomBranches console variable.

MaxRandomBranchesCVar interacts directly with the au.MaxRandomBranches setting and is used in the DetermineAmountOfBranchesToPreselect function of the USoundNodeRandom class.

Developers should be aware that modifying MaxRandomBranchesCVar directly is not recommended. Instead, they should use the au.MaxRandomBranches console variable to change its value.

Best practices for MaxRandomBranchesCVar include:

  1. Treat it as a read-only variable within the code.
  2. Use it for conditional logic related to branch preselection in sound nodes.
  3. Always refer to it when implementing features that depend on the maximum number of random branches.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundNodeRandom.cpp:13

Scope: file

Source code excerpt:

static int32 MaxRandomBranchesCVar = 0;
FAutoConsoleVariableRef CVarMaxRandomBranches(
	TEXT("au.MaxRandomBranches"),
	MaxRandomBranchesCVar,
	TEXT("Sets the max amount of branches to play from for any random node. The rest of the branches will be released from memory.\n")
	TEXT("0: No culling, Any other value: The amount of branches we should use as a maximum for any random node."),
	ECVF_Default);

static int32 PrimeRandomSoundNodesCVar = 0;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Classes/Sound/SoundNodeRandom.h:110

Scope (from outer to inner):

file
class        class USoundNodeRandom : public USoundNode

Source code excerpt:

	/*
	 * Determines the amount of branches to use on this random node, so that we can cull the rest.
	 * Based on the au.MaxRandomBranches CVar, the MaxNumRandomBranches project setting
	 * available for some platforms, and this node's PreselectAtLevelLoad FProperty.
	 * @return 0 if we do not want cull any branches.
	 */
	int32 DetermineAmountOfBranchesToPreselect();

};

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundNodeRandom.cpp:11

Scope: file

Source code excerpt:

#endif

static int32 MaxRandomBranchesCVar = 0;
FAutoConsoleVariableRef CVarMaxRandomBranches(
	TEXT("au.MaxRandomBranches"),
	MaxRandomBranchesCVar,
	TEXT("Sets the max amount of branches to play from for any random node. The rest of the branches will be released from memory.\n")
	TEXT("0: No culling, Any other value: The amount of branches we should use as a maximum for any random node."),
	ECVF_Default);

static int32 PrimeRandomSoundNodesCVar = 0;
FAutoConsoleVariableRef CVarPrimeRandomSoundNodes(

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SoundNodeRandom.cpp:160

Scope (from outer to inner):

file
function     int32 USoundNodeRandom::DetermineAmountOfBranchesToPreselect

Source code excerpt:



	if (MaxRandomBranchesCVar > 0)
	{
		// If the CVar has been set, allow it to override our .ini setting:
		OverrideForAmountOfBranchesToPreselect = MaxRandomBranchesCVar;
	}
	else
	{
		// Otherwise, we use the value from the ini setting, if we have one:
		OverrideForAmountOfBranchesToPreselect = FPlatformCompressionUtilities::GetMaxPreloadedBranchesForCurrentPlatform();
	}