Combat Awareness Guide

Track multiple targets without locking to any of them. Perfect for threat indicators, camera framing, and AI systems.

What is Awareness?

Awareness is a secondary targeting mode that runs alongside your lock-on system. While Lock() gives you a single focused target, awareness tracks ALL nearby threats and returns them as a list.

Aspect	Lock-On	Awareness
Targets	Single target	Multiple targets
Lock type	Hard or soft lock	No lock at all
Control	Player-controlled	System-managed
API	`GetCurrentTarget()`	`GetAwarenessTargets()`
Used for	Combat focus	Peripheral vision

Key Point: Awareness is independent of lock-on. You can use them together or separately.

Use Cases

1. Threat Indicators (UI)

Show danger icons for enemies outside your view.

void AMyHUD::UpdateThreatIndicators()
{
    TArray<FAgenticTargetData> Threats = TargetingComponent->GetAwarenessTargets();

    for (const FAgenticTargetData& Threat : Threats)
    {
        // Skip the locked target (already showing lock reticle)
        if (Threat.bIsLocked) continue;

        // Show indicator based on angle
        if (FMath::Abs(Threat.Angle) > 90.f)
        {
            ShowOffscreenIndicator(Threat.Target, Threat.Angle, Threat.ThreatLevel);
        }
    }
}

2. Camera Framing

Keep multiple threats in view during combat.

// Camera system queries awareness to frame threats
TArray<FAgenticTargetData> Threats = TargetingComponent->GetAwarenessTargets();
FVector AveragePosition = CalculateCentroid(Threats);
FocusCameraOn(AveragePosition);

3. AI Decision Making

Let AI know about nearby threats for tactical decisions.

// AI checks what player is aware of
TArray<FAgenticTargetData> PlayerAwareness = PlayerTargeting->GetAwarenessTargets();
if (PlayerAwareness.Num() > 3)
{
    // Player is surrounded - flank them!
    ExecuteFlankingManeuver();
}

4. Combat Music/Audio

Dynamically adjust intensity based on threat count.

int32 ThreatCount = TargetingComponent->GetAwarenessTargets().Num();
float Intensity = FMath::Clamp(ThreatCount / 5.f, 0.f, 1.f);
AudioManager->SetCombatIntensity(Intensity);

Basic Usage

Starting Awareness

// Start tracking nearby threats
TargetingComponent->StartAwareness(
    FGameplayTag::RequestGameplayTag("Agentic.Targeting.Preset.Awareness.Melee")
);

Getting Targets

// Returns all targets found by the awareness preset
TArray<FAgenticTargetData> Threats = TargetingComponent->GetAwarenessTargets();

for (const FAgenticTargetData& Threat : Threats)
{
    AActor* Enemy = Threat.Target;      // The actor
    float Distance = Threat.Distance;    // Distance from player
    float Angle = Threat.Angle;          // Angle from forward vector
    float ThreatLevel = Threat.ThreatLevel;  // 0-1 threat score
    bool bIsLocked = Threat.bIsLocked;   // Is this the locked target?
}

Stopping Awareness

// Stop tracking (saves performance when not in combat)
TargetingComponent->StopAwareness();

Listening for Updates

// Bind to awareness updates
TargetingComponent->OnAwarenessUpdated.AddDynamic(this, &AMyCharacter::OnAwarenessChanged);

void AMyCharacter::OnAwarenessChanged(const TArray<FAgenticTargetData>& Targets)
{
    // Called whenever awareness pool changes
    UpdateThreatUI(Targets);
}

Awareness Preset

Preset	Range	Filters	Best For
`Agentic.Targeting.Preset.Awareness`	15m	Targetable only	Combat awareness, threat tracking

Awareness presets skip LOS checks by default - you want to know about threats even behind walls!

Custom Awareness Presets

Create your own by duplicating and modifying DT_TargetingPresets:

Tag: Agentic.Targeting.Preset.Awareness.Custom
Tasks:
  - AOE_Selection (30m radius, 360°)
  - Filter_Targetable
  - Sort_ThreatLevel (highest first)

Using with Lock-On

Awareness works independently from lock-on. Common pattern:

void AMyCharacter::EnterCombat()
{
    // Set up lock-on style
    TargetingComponent->SetStyleByTag("Agentic.Targeting.Style.Souls");
    TargetingComponent->SetPresetByTag("Agentic.Targeting.Preset.Melee");

    // Also start awareness for peripheral threats
    TargetingComponent->StartAwareness("Agentic.Targeting.Preset.Awareness.Melee");
}

void AMyCharacter::ExitCombat()
{
    TargetingComponent->Unlock();
    TargetingComponent->StopAwareness();
}

Now you have:

Lock-on for focused combat (GetCurrentTarget())
Awareness for peripheral threats (GetAwarenessTargets())

FAgenticTargetData Structure

Each awareness target returns this data:

USTRUCT(BlueprintType)
struct FAgenticTargetData
{
    UPROPERTY(BlueprintReadOnly)
    AActor* Target;         // The target actor

    UPROPERTY(BlueprintReadOnly)
    float Distance;         // Distance from player (cm)

    UPROPERTY(BlueprintReadOnly)
    float Angle;            // Angle from forward vector (-180 to 180)

    UPROPERTY(BlueprintReadOnly)
    float ThreatLevel;      // 0.0 to 1.0 (from IAgenticTargetable)

    UPROPERTY(BlueprintReadOnly)
    bool bIsLocked;         // Is this the current locked target?
};

Blueprint Usage

Start/Stop Awareness

Get your Agentic Targeting Component reference
Call Start Awareness with a preset tag
Call Stop Awareness when leaving combat

Get Awareness Targets

Call Get Awareness Targets on the component
Returns array of Agentic Target Data structs
Loop through and use Target, Distance, Angle, ThreatLevel

Bind to Updates

In Event Graph, find On Awareness Updated event dispatcher
Bind to it in BeginPlay
Event fires whenever the awareness pool changes

Performance Tips

Stop when not needed - Call StopAwareness() outside combat
Use appropriate range - Smaller radius = fewer queries
Adjust update rate - Awareness updates on validation tick (default 0.25s)
Filter by class - Add actor class filter to reduce candidates

AgenticGameplayCamera Integration

The Agentic Gameplay Camera plugin has built-in awareness integration via the Awareness Modifier:

Modifier: Agentic.Camera.Modifier.Awareness

When enabled, the camera automatically:

Queries GetAwarenessTargets() from your targeting component
Frames multiple threats in view
Adjusts FOV and position to keep awareness targets visible
Works alongside lock-on (shows both locked target and peripheral threats)

Setup:

Install AgenticGameplayCamera plugin
Add Agentic.Camera.Modifier.Awareness to your camera mode
Camera will automatically use your targeting component's awareness data

Common Patterns

Threat Count Check

bool AMyCharacter::IsSurrounded() const
{
    return TargetingComponent->GetAwarenessTargets().Num() >= 4;
}

Highest Threat

AActor* AMyCharacter::GetHighestThreat() const
{
    TArray<FAgenticTargetData> Threats = TargetingComponent->GetAwarenessTargets();
    if (Threats.Num() == 0) return nullptr;

    // Sorted by threat level (highest first) via preset
    return Threats[0].Target;
}

Threats Behind Player

TArray<AActor*> AMyCharacter::GetThreatsFromBehind() const
{
    TArray<AActor*> Behind;
    for (const FAgenticTargetData& Threat : TargetingComponent->GetAwarenessTargets())
    {
        if (FMath::Abs(Threat.Angle) > 90.f)
        {
            Behind.Add(Threat.Target);
        }
    }
    return Behind;
}

Combat Awareness Guide

On this page