UE5-Modular-Game-Framework/docs/blueprints/09-ai/82_BPC_AlertSystem.md

60 — BPC_AlertSystem

Blueprint Spec — UE 5.5–5.7

---

Parent Class

ActorComponent

Dependencies

• BPC_AIControllerBase — Owner controller
• BP_EnemyBase — Pawn that receives commands
• DA_AIProfile — Alert thresholds and response times
• BPC_PerceptionComponent — Stimulus input source
• BPC_AIStateMachine — State transition triggers
• I_Damageable — Damage stimulus source

Purpose

Manages AI threat levels, alert escalation, and reinforcement propagation. Receives stimuli from perception and damage systems, evaluates threat severity, escalates through alert levels (Unaware → Suspicious → Alert → Combat), and notifies nearby AI units. Acts as the central threat-response coordinator for each AI.

Enums

Enum	Values	Description
EAlertLevel	Unaware, Suspicious, Alert, Combat	Current alert tier
EAlertCause	SightStimulus, HearingStimulus, DamageTaken, AllyAlert, Environmental	What triggered the alert

Structs

Struct	Fields	Description
FAlertState	AlertLevel: EAlertLevel, AlertCause: EAlertCause, LastAlertTime: Float, SourceLocation: FVector, KnownTarget: AActor, bHasValidTarget: Bool, SuspicionValue: Float, CombatTimer: Float	Snapshot of current alert status
FAlertPropagationInfo	AlertLevel: EAlertLevel, SourceLocation: FVector, Target: AActor, PropagationRadius: Float, Timestamp: Float	Data sent to nearby AI

Variables

Name	Type	Description
CurrentAlertState	FAlertState	Live alert tracking
AlertThresholds	FVector2D	Suspicion threshold X, Combat threshold Y
SuspicionDecayRate	Float	Points per second lost when no stimulus
SuspicionGrowthRate	Float	Points per second gained on stimulus
CombatExitDelay	Float	Time without combat before dropping to Alert
ReinforcementRadius	Float	Max distance to notify allies
bCanCallReinforcements	Bool	Permission to propagate
ReinforcementCooldown	Float	Min seconds between calls
LastReinforcementTime	Float	Cooldown tracker
bIsInCombat	Bool	Fast check for combat state
InvestigationTimer	Float	Time spent investigating last known position
MaxInvestigationTime	Float	Give up after this long

Functions

Name	Inputs	Outputs	Description
EvaluateStimulus	StimulusType: EAlertCause, Intensity: Float, Location: FVector, Instigator: AActor	—	Process incoming stimulus
CalculateThreatScore	StimulusType: EAlertCause, Intensity: Float, Distance: Float	Float	Compute weighted threat value
EscalateAlert	NewLevel: EAlertLevel, Cause: EAlertCause	—	Raise alert level
DeescalateAlert	—	—	Lower alert level (decay timer)
UpdateSuspicion	DeltaTime: Float	—	Tick suspicion up/down
CheckAlertTransition	—	EAlertLevel	Determine if threshold crossed
EnterCombat	Target: AActor	—	Transition to combat state
ExitCombat	—	—	Transition out of combat
CallReinforcements	—	—	Broadcast alert to allies
ReceiveReinforcementCall	Info: FAlertPropagationInfo	—	Handle ally alert broadcast
GetCurrentAlertLevel	—	EAlertLevel	Getter for blackboard updates
GetKnownTarget	—	AActor	Current combat target
IsInCombat	—	Bool	Combat state check
SetInvestigationPoint	Location: FVector	—	Mark last known target position
ClearInvestigationPoint	—	—	Reset investigation
ShouldGiveUpSearch	—	Bool	Timeout check for investigation

Blueprint Flow

[EvaluateStimulus]
  └─► Calculate Threat Score
  └─► If Score > AlertThresholds.Y --> Escalate to Combat
  └─► Else If Score > AlertThresholds.X --> Escalate to Suspicious
  └─► Else --> Update SuspicionValue (accumulate)
  └─► If AlertLevel >= Suspicious:
         Set Investigation Point
         If AlertLevel == Combat:
             Set KnownTarget
             EnterCombat
             If bCanCallReinforcements:
                 CallReinforcements

[Event Tick]
  └─► UpdateSuspicion(DeltaTime):
         If no stimulus:
             SuspicionValue -= SuspicionDecayRate * DeltaTime
             If SuspicionValue <= 0:
                 DeescalateAlert (back to Unaware)
         If AlertLevel == Combat:
             CombatTimer += DeltaTime
             If CombatTimer > CombatExitDelay && no damage/stimulus:
                 ExitCombat -> set AlertLevel = Alert
         If AlertLevel == Suspicious:
             InvestigationTimer += DeltaTime
             If InvestigationTimer > MaxInvestigationTime:
                 ClearInvestigationPoint
                 DeescalateAlert

[CallReinforcements]
  └─► If (Time - LastReinforcementTime) < ReinforcementCooldown: return
  └─► Get all AI controllers within ReinforcementRadius
  └─► For each:
         Call ReceiveReinforcementCall with current alert info
  └─► LastReinforcementTime = CurrentTime

[ReceiveReinforcementCall]
  └─► If CurrentAlertLevel >= Info.AlertLevel: ignore (already higher)
  └─► Else: EscalateAlert(Info.AlertLevel, Environmental)
         Set InvestigationPoint = Info.SourceLocation
         If Info.AlertLevel == Combat:
             Set KnownTarget = Info.Target

Event Dispatchers

Name	Delegate Signature	Purpose
OnAlertLevelChanged	EAlertLevel, EAlertCause	UI, sound, state machine listeners
OnCombatEntered	AActor Target	Combat music, HUD, behavior tree
OnCombatExited	—	Combat cleanup
OnReinforcementCalled	FAlertPropagationInfo	Debug logging, analytics
OnInvestigationStarted	FVector Location	Sound/investigation music
OnInvestigationEnded	—	Return to patrol

Communications With

Target	Method	Why
BPC_AIStateMachine	Call	Request state change
BPC_AIControllerBase	Owner reference	Coordinate BB values
BPC_PerceptionComponent	Direct call	Get stimulus data
BP_EnemyBase	Owner reference	Trigger combat animations
WBP_HUD	Event dispatcher	Show combat indicator
BPC_CombatFeedback	Event dispatcher	Combat music/vignette

Reuse Notes

• Attached to AIControllerBase; profiles tune thresholds per enemy type
• Works with any perception system that produces EAlertCause stimuli
• Reinforcement chain prevents infinite loops by comparing alert levels
• Investigation system handles "last seen" behavior without combat
• Decay system ensures AI eventually returns to patrol state