Awareness System

Documentation Unreal Engine AI Awareness Perception

Per-AI perception memory: notice, investigate, chase, and forget targets through sight, hearing, and damage.

USECAwarenessComponent wraps Unreal perception and keeps per-target memory. Pair it with an awareness filtered selector and combat engages only sensed targets.

Viewport

LVL_SEC_Showcase>Awareness

Seen = Detected. Lose sight = Lost (grace), then Suspicious if still heard, then Unknown.

When to Use This

Stealth or patrol enemies that aggro on sight, not through walls.
Investigate-by-sound before full combat.
A search tail after line-of-sight breaks, then give up.
Pack alerting when one enemy spots the player.
An HUD bar from GetAwarenessProgress.

Leave UEnemyAIConfig::AwarenessConfig null and nothing changes. AEnemyControllerBase already owns the component; assign a config asset to opt in.

Mount USECAwarenessComponent on the AIController. It listens to UAIPerceptionComponent, tracks Awareness01 (0..1) per target, and maps that meter to states on EvaluationInterval (default 0.1s). The component header documents server-only use; run perception and awareness on the authority side in multiplayer.

States

Selector comparisons use: Unknown < Forgotten < Suspicious < Lost < Detected.

State	Meaning
Unknown	No map entry. Never sensed, or pruned after Forgotten.
Suspicious	Partial info: sound, sub-threshold sight meter, peripheral fill.
Lost	Was Detected; sight broke. Last-known location frozen; grace timer runs from `TimeEnteredLost`.
Detected	High confidence: live sight at full meter, damage, proximity floor, or `ForceAwareOf`.
Forgotten	Exit state: `OnTargetForgotten` fires once, then the entry is removed. `GetAwarenessState` returns Unknown afterward.

Meter and senses

With bGradualEscalation enabled (default), sight ramps the meter each evaluation tick:

Fill rate = EscalationRate × distance curve × angle curve × GetAwarenessRateMultiplier (sight).
Meter ≥ SuspicionThreshold (default 0.2): Suspicious.
Meter ≥ 1.0: Detected; the role subsystem gets RequestTargetReassignment.
Hearing applies a meter bump: max(HearingBump, SuspicionThreshold) × hearing multiplier, capped below 1.0. Reaches Suspicious, not Detected.
Damage sets the meter to 1.0 and promotes to Detected immediately.

Disable bGradualEscalation for a flat fill rate of 1.0 units per second (no distance/angle scaling). Proximity still fills immediately.

Losing a target

ConfirmLostDelay (0.5s): Detected holds through brief sight loss before dropping to Lost.
ProximityRadius (220 cm): targets inside stay in the rising branch without line of sight.
Lost grace: GraceLossDuration (5s) from TimeEnteredLost. Re-sight while Lost snaps back to Detected. Timeout prunes to Forgotten.
Suspicious drain: meter drains over SuspiciousDecayDuration (8s). At 0 it becomes Forgotten (Suspicious skips Lost).

State demotion and Forgotten also call RequestTargetReassignment, not only first Detected.

Setup

You need both a config asset and an awareness filtered selector for gated combat.

1. Config asset and EnemyAIConfig

Create SECAwarenessConfig (Right-click → Miscellaneous → Data Asset). Assign it on UEnemyAIConfig:

Details

Enemy AI Config (EnemyAIConfig)

Awareness

Manage Awareness Automatically

Awareness Config

DA_EnemyAwareness

Awareness category on the config asset assigned to the pawn via IEnemyAIConfigProvider.

With Manage Awareness Automatically on (default), SECCombatControllerComponent calls ApplyConfig on possession. Turn it off and the component receives ApplyConfig(nullptr) and sits idle.

Auto Create Perception Component (default on) builds sight, hearing, and damage senses from the asset:

Details

SEC Awareness Config (SECAwarenessConfig)

Perception

Auto Create Perception Component

Sight

Enable Sight

Sight Radius

1500

Lose Sight Radius

1800

Peripheral Vision Half Angle

Hearing

Enable Hearing

Hearing Range

1200

Damage

Enable Damage Sense

Perception tuning on the awareness config asset referenced by EnemyAIConfig.

2. Gate target selection

Set UEnemyAIConfig → Target Selector to Awareness Filtered Target Selector. Without it, awareness still records stimuli but target selection behaves as if awareness were not in the chain.

Details

Awareness Filtered Target Selector (AwarenessFilteredTargetSelector)

Awareness Filter

Min Required State

Lost

Inner Selector

None

Instanced selector on EnemyAIConfig. Requires USECAwarenessComponent on the AI controller.

`MinRequiredState`	Feel
Detected	Combat drops when sight breaks; you drive investigate/search in Blueprint. Fits stealth patrols.
Lost (default)	Combat continues through the grace window; drops at Forgotten.
Suspicious	Combat can start on investigate-by-sound targets.

On possession, SECCombatControllerComponent warns when AwarenessConfig is set but Target Selector is not UAwarenessFilteredTargetSelector. Memory records either way; the selector enforces the gate.

Auto-created sight detects enemies and neutrals, not friendlies. Put the player on a different team from the AI (AEnemyControllerBase defaults enemies to team 1). Same-team pawns never produce sight stimuli.

If the filtered selector runs without a USECAwarenessComponent on the controller, it warns once and passes candidates through unfiltered.

See Targeting System for the full selector chain.

Tune

Details

SEC Awareness Config (SECAwarenessConfig)

Escalation

Gradual Escalation

Escalation Rate

0.9

Suspicion Threshold

0.2

Hearing Bump

0.5

Distance Rate Curve

None

Angle Rate Curve

None

Escalation category on the awareness config asset.

Details

SEC Awareness Config (SECAwarenessConfig)

Memory

Grace Loss Duration

Suspicious Decay Duration

Evaluation Interval

0.1

Track Last Known Location

Proximity

Proximity Radius

220

Hysteresis

Confirm Lost Delay

0.5

Memory category on the awareness config asset.

Rate multipliers live on USECAwarenessComponent: AwarenessRateMultipliers or SetAwarenessRateMultiplier. Sight scales meter fill; hearing scales the bump. Damage and the proximity floor ignore multipliers. Override GetAwarenessRateMultiplier for per-target rules.

Facing: bFaceLastKnownWhenNotDetected (default on) on AEnemyControllerBase tracks the live actor only while Detected; Suspicious and Lost face last-known location. Override GetDesiredFacingLocation to replace that logic.

Integration

System	Link
Targeting System	Filtered selector gates candidates; `MinRequiredState` sets disengage feel.
StateTree Integration	Awareness State At Least condition; Poll Last Known Location task.
Combat Roles	Filtered targets feed role assignment. Detected, demotion, and Forgotten can trigger reassignment.
Threat Detection	Awareness: what this AI sensed. Threat: whether the focus target is looking at this AI.

AdvancedEvents and queries

Event	When
`OnTargetSuspicious`	First promotion to Suspicious (includes stimulus location).
`OnTargetSpotted`	First promotion to Detected.
`OnTargetLost`	Detected → Lost.
`OnTargetForgotten`	Entry pruned after grace or Suspicious drain.
`OnAwarenessProgress`	Meter crosses 0.25 / 0.5 / 0.75 / 1.0.
`OnAlertLevelChanged`	Highest state across targets changes.
`OnTargetStateChanged`	Any transition (catch-all).

ESECAwarenessState GetAwarenessState(AActor* Target) const;
float              GetAwarenessProgress(AActor* Target) const;
AActor*            GetMostAwareTarget(ESECAwarenessState& OutState) const;
bool               GetLastKnownLocation(AActor* Target, FVector& OutLocation, float& OutAgeSeconds) const;
void               GetTargetsInState(ESECAwarenessState MinState, TArray<AActor*>& OutTargets) const;
void               ForceAwareOf(AActor* Target, ESECAwarenessState State);  // Unknown/Forgotten → Forget()
void               BroadcastAwarenessToAllies(float Radius);

GetAwarenessProgress: live meter while Suspicious, 1.0 while Detected, grace fraction while Lost.

GetMostAwareTarget ranks by state magnitude, then meter within the same state.

AdvancedBehavior recipes

Return home: OnTargetForgotten → AI Move To home (capture at BeginPlay).

Investigate noise: OnTargetSuspicious → AI Move To stimulus location. Visible player fills meter to Detected; otherwise Suspicious drains to Forgotten.

StateTree loop: Patrol below Suspicious; Investigate at Suspicious; Combat at Detected; Search at Lost via Poll Last Known Location; Return on Forgotten. Keep movement evaluator in Combat only.

Meter UI: bind OnAwarenessProgress or poll GetAwarenessProgress.

Pack alert: OnTargetSpotted → BroadcastAwarenessToAllies. Allies need their own awareness component; matching team id required.

AdvancedExtension hooks

Hook	Use
`ShouldIgnoreActor`	Block all senses for an actor (default: `IgnoredActorClasses`).
`ResolveStimulusState`	Remap non-sight senses (hearing/damage defaults in C++).
`GetAwarenessRateMultiplier`	Per-target fill scale.
`GetDesiredFacingLocation`	Custom facing while not Detected.
`InnerSelector`	Pick among filtered targets (default: nearest by squared distance).

Add fly-cam classes to IgnoredActorClasses when debug pawns keep getting spotted.

AlternativeBring your own UAIPerceptionComponent

Add UAIPerceptionComponent on the controller, configure senses in Blueprint, set Auto Create Perception Component to false. USECAwarenessComponent binds to the existing component; sense fields on the config asset are not applied. If none exists and auto-create is off, awareness logs a warning and stops updating.

AdvancedDebug

Bind OnTargetStateChanged or poll GetAwarenessState / GetHighestAwarenessState.
Walk into sight: OnTargetSpotted once. Behind the AI: quiet.
GetAwarenessProgress shows meter fill, Detected at 1.0, Lost grace drain.