HearingRange

HearingRange

#Overview

name: HearingRange

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of HearingRange is to define the maximum distance at which an AI agent can detect sounds in the Unreal Engine’s AI perception system. It is specifically used for the hearing sense configuration in AI-controlled characters.

This setting variable is primarily used by the AI Module in Unreal Engine, specifically within the perception system. It is a key component of the UAISenseConfig_Hearing class, which is part of the AI perception framework.

The value of this variable is typically set in the constructor of UAISenseConfig_Hearing, where it is initialized to 3000 units (centimeters in Unreal Engine’s default scale). However, it can be modified through the Unreal Editor’s property system, as indicated by the UPROPERTY macro with EditAnywhere and BlueprintReadOnly specifiers.

HearingRange interacts with other variables in the AI perception system, particularly:

  1. Loudness: Used to modify the effective hearing range.
  2. MaxRange: An optional limit on the maximum distance a sound can be heard.

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

  1. The value is in Unreal Engine units (typically centimeters).
  2. It has a minimum value of 0, enforced by the ClampMin meta specifier.
  3. It replaced the deprecated LoSHearingRange in version 5.2.

Best practices when using this variable include:

  1. Carefully consider the appropriate range for your game’s scale and AI behavior requirements.
  2. Use in conjunction with Loudness and MaxRange for more nuanced sound detection.
  3. Adjust the value in the editor to fine-tune AI perception without recompiling code.
  4. Be mindful of performance implications when setting very large hearing ranges, as it may increase the number of sound events the AI needs to process.
  5. Consider using different hearing ranges for different AI types or difficulty levels to create varied gameplay experiences.

#Setting Variables

#References In INI files

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

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

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Classes/Perception/AISenseConfig_Hearing.h:24

Scope (from outer to inner):

file
class        class UAISenseConfig_Hearing : public UAISenseConfig

Source code excerpt:


	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Sense", meta = (UIMin = 0.0, ClampMin = 0.0, Units="Centimeters"))
	float HearingRange;

	UE_DEPRECATED(5.2, "LoSHearingRange is deprecated. Use HearingRange instead.")
	UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Sense", meta = (UIMin = 0.0, ClampMin = 0.0, Units="Centimeters", EditCondition = "bUseLoSHearing"))
	float LoSHearingRange;

	UE_DEPRECATED(5.2, "bUseLoSHearing is deprecated.")

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Classes/Perception/AISense_Hearing.h:27

Scope: file

Source code excerpt:

	 * Loudness modifier of the sound.
	 * If MaxRange is non-zero, this modifies the range (by multiplication).
	 * If there is no MaxRange, then if Square(DistanceToSound) <= Square(HearingRange * Loudness), the sound is heard, false otherwise.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sense", meta = (UIMin = 0, ClampMin = 0))
	float Loudness;

	/**
	 * Max range at which the sound can be heard. Multiplied by Loudness.
	 * A value of 0 indicates that there is no range limit, though listeners are still limited by their own hearing range.
	 */
	UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Sense", meta = (UIMin = 0, ClampMin = 0))
	float MaxRange;

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/Perception/AISense.cpp:249

Scope (from outer to inner):

file
function     UAISenseConfig_Hearing::UAISenseConfig_Hearing

Source code excerpt:


UAISenseConfig_Hearing::UAISenseConfig_Hearing(const FObjectInitializer& ObjectInitializer) 
	: Super(ObjectInitializer), HearingRange(3000.f)
{
	DebugColor = FColor::Yellow;
}

TSubclassOf<UAISense> UAISenseConfig_Hearing::GetSenseImplementation() const 
{

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/Perception/AISense.cpp:283

Scope (from outer to inner):

file
function     void UAISenseConfig_Hearing::DescribeSelfToGameplayDebugger

Source code excerpt:

		FVector OwnerLocation = BodyActor->GetActorLocation();
		
		DebuggerCategory->AddShape(FGameplayDebuggerShape::MakeCylinder(OwnerLocation, HearingRange, 25.0f, HearingRangeColor));
	}
}
#endif // WITH_GAMEPLAY_DEBUGGER_MENU

//----------------------------------------------------------------------//
// UAISenseConfig_Prediction

#Loc: <Workspace>/Engine/Source/Runtime/AIModule/Private/Perception/AISense_Hearing.cpp:38

Scope (from outer to inner):

file
function     UAISense_Hearing::FDigestedHearingProperties::FDigestedHearingProperties

Source code excerpt:

UAISense_Hearing::FDigestedHearingProperties::FDigestedHearingProperties(const UAISenseConfig_Hearing& SenseConfig)
{
	HearingRangeSq = FMath::Square(SenseConfig.HearingRange);
	AffiliationFlags = SenseConfig.DetectionByAffiliation.GetAsFlags();
}

UAISense_Hearing::FDigestedHearingProperties::FDigestedHearingProperties()
	: HearingRangeSq(-1.f)
{