API Reference

Complete API reference for the Agentic Targeting System.

UAgenticTargetingComponent

The main component that handles all targeting functionality.

Setup Methods

// Set the targeting style (how lock behaves)
void SetStyleByTag(FGameplayTag StyleTag);

// Set the targeting preset (who to target)
void SetPresetByTag(FGameplayTag PresetTag);

Lock-On Methods

// Primary lock function - behavior determined by style
// Hard lock styles: toggles lock on/off
// Soft lock styles: updates target based on input
void Lock();

// Explicitly lock to a specific actor
void LockOnTo(AActor* Target);

// Release current lock
void Unlock();

// Release current lock (alias)
void ReleaseLock();

// Check if currently locked
bool IsLockedOn() const;

// Get current locked target
AActor* GetCurrentTarget() const;

// Get target location (uses IAgenticTargetable if available)
FVector GetCurrentTargetLocation() const;

Target Cycling

// Cycle to next valid target
void CycleTargetNext();

// Cycle to previous valid target
void CycleTargetPrevious();

// Get all valid targets in pool
TArray<AActor*> GetTargetPool() const;

// Get target count
int32 GetTargetCount() const;

Soft Lock Methods

// Trigger soft lock update (for Freeflow styles)
void TriggerSoftLockUpdate();

// Get current soft lock target
AActor* GetSoftLockTarget() const;

Awareness Methods

// Start awareness tracking with preset
void StartAwareness(FGameplayTag PresetTag);

// Stop awareness tracking
void StopAwareness();

// Manually update awareness
void UpdateAwareness();

// Get awareness targets
TArray<FAgenticTargetData> GetAwarenessTargets() const;

Events (Delegates)

// Fired when a new target is acquired
UPROPERTY(BlueprintAssignable)
FOnTargetAcquired OnTargetAcquired;

// Fired when target is lost
UPROPERTY(BlueprintAssignable)
FOnTargetLost OnTargetLost;

// Fired when target changes to a different actor
UPROPERTY(BlueprintAssignable)
FOnTargetChanged OnTargetChanged;

// Fired when target pool is updated
UPROPERTY(BlueprintAssignable)
FOnTargetsUpdated OnTargetsUpdated;

// Fired when awareness targets update
UPROPERTY(BlueprintAssignable)
FOnAwarenessUpdated OnAwarenessUpdated;

// Fired when lock state changes (locked/unlocked)
UPROPERTY(BlueprintAssignable)
FOnLockStateChanged OnLockStateChanged;

Binding Events (C++)

// In your character's BeginPlay
TargetingComponent->OnTargetAcquired.AddDynamic(this, &AMyCharacter::OnTargetAcquired);
TargetingComponent->OnTargetLost.AddDynamic(this, &AMyCharacter::OnTargetLost);

void AMyCharacter::OnTargetAcquired(AActor* Target)
{
    // Show target indicator widget
    // Switch to combat camera
}

void AMyCharacter::OnTargetLost(AActor* PreviousTarget)
{
    // Hide target indicator
    // Return to exploration camera
}

Debug Properties

// Enable debug visualization
UPROPERTY(EditAnywhere, Category = "Debug")
bool bDebugDraw = false;

// Enable debug logging
UPROPERTY(EditAnywhere, Category = "Debug")
bool bDebugLog = false;

IAgenticTargetable Interface

Optional interface for targetable actors to customize behavior.

Methods to Implement

// Can this actor be targeted by the given targeter?
UFUNCTION(BlueprintNativeEvent)
bool CanBeTargeted(AActor* Targeter) const;

// Get the world location to target (default: actor location)
UFUNCTION(BlueprintNativeEvent)
FVector GetTargetLocation() const;

// Get threat level for sorting (0.0 to 1.0)
UFUNCTION(BlueprintNativeEvent)
float GetThreatLevel() const;

// Called when this actor becomes a target
UFUNCTION(BlueprintNativeEvent)
void OnBecameTarget(AActor* Targeter, bool bIsLocked);

// Called when this actor is no longer targeted
UFUNCTION(BlueprintNativeEvent)
void OnLostTarget(AActor* Targeter);

// Is this target still alive? (for validation)
UFUNCTION(BlueprintNativeEvent)
bool IsTargetAlive() const;

Example Implementation

// MyEnemy.h
UCLASS()
class AMyEnemy : public ACharacter, public IAgenticTargetable
{
    GENERATED_BODY()

public:
    // IAgenticTargetable
    virtual bool CanBeTargeted_Implementation(AActor* Targeter) const override;
    virtual FVector GetTargetLocation_Implementation() const override;
    virtual float GetThreatLevel_Implementation() const override;
    virtual void OnBecameTarget_Implementation(AActor* Targeter, bool bIsLocked) override;
    virtual void OnLostTarget_Implementation(AActor* Targeter) override;

protected:
    UPROPERTY()
    bool bIsDead = false;

    UPROPERTY()
    float ThreatLevel = 0.5f;
};

// MyEnemy.cpp
bool AMyEnemy::CanBeTargeted_Implementation(AActor* Targeter) const
{
    return !bIsDead && !IsPendingKill();
}

FVector AMyEnemy::GetTargetLocation_Implementation() const
{
    // Return chest/spine location for better visual targeting
    if (USkeletalMeshComponent* Mesh = GetMesh())
    {
        return Mesh->GetSocketLocation("Spine");
    }
    return GetActorLocation() + FVector(0, 0, 50);
}

float AMyEnemy::GetThreatLevel_Implementation() const
{
    return ThreatLevel;
}

void AMyEnemy::OnBecameTarget_Implementation(AActor* Targeter, bool bIsLocked)
{
    // Show "targeted" indicator on enemy
    // Play target acquired sound
}

void AMyEnemy::OnLostTarget_Implementation(AActor* Targeter)
{
    // Hide target indicator
}

FAgenticTargetData

Data structure returned by awareness and target pool queries.

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

    // Distance from targeter
    UPROPERTY(BlueprintReadOnly)
    float Distance;

    // Angle from targeter's forward vector
    UPROPERTY(BlueprintReadOnly)
    float Angle;

    // Threat level (from IAgenticTargetable)
    UPROPERTY(BlueprintReadOnly)
    float ThreatLevel;

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

Blueprint Usage

All methods are exposed to Blueprint with the BlueprintCallable specifier.

Common Blueprint Nodes

Lock - Primary targeting function (behavior determined by style)
Unlock - Release current lock
Set Style By Tag - Change targeting style
Set Preset By Tag - Change targeting preset
Get Current Target - Get locked actor
Is Locked On - Check lock state
Cycle Target Next/Previous - Switch targets

Event Dispatchers

Bind to these in your Character Blueprint's Event Graph:

On Target Acquired
On Target Lost
On Target Changed
On Lock State Changed

GAS Abilities (Multiplayer)

The plugin includes pre-built Gameplay Ability System abilities for multiplayer-ready targeting with full prediction support.

Why Use GAS Abilities?

Feature	Direct Component Calls	GAS Abilities
Prediction	None	Full client prediction
Validation	None	Server validates targets
Rollback	None	Automatic on misprediction
Effects	Manual	GameplayEffects integration
Cues	Manual	GameplayCues integration
Multiplayer	Basic replication	Production-ready

Available Abilities

Ability	Purpose	Lock Type
GA_HardLock	Toggle hard lock on/off	Hard
GA_SoftLockMode	Timer-based continuous soft lock	Soft
GA_CycleTarget	Switch between targets while locked	N/A

GA_HardLock

Toggle hard lock with GAS prediction. Client predicts target selection, server validates.

Configuration

UPROPERTY(EditDefaultsOnly, Category = "Targeting")
FGameplayTag TargetingPresetTag;  // Which preset to use

UPROPERTY(EditDefaultsOnly, Category = "Targeting")
float MaxLockRange = 2000.0f;     // Server validation range

UPROPERTY(EditDefaultsOnly, Category = "Targeting")
float LatencyTolerance = 1.1f;    // 10% tolerance for lag

Effects & Cues

UPROPERTY(EditDefaultsOnly, Category = "Effects")
TSubclassOf<UGameplayEffect> HardLockEffect;  // Applied while locked

UPROPERTY(EditDefaultsOnly, Category = "Cues")
FGameplayTag LockAcquiredCue;    // Played on successful lock
FGameplayTag LockFailedCue;      // Played when lock fails
FGameplayTag LockReleasedCue;    // Played when lock releases

Flow

1. Player presses Lock button
2. Client: Query targets, select best, show UI immediately (prediction)
3. Server: Validate target (range, alive, targetable)
4. Server confirms → Done
   Server rejects → Client rolls back, server provides alternative

Extending

Override these methods in Blueprint or C++:

// Custom validation logic
UFUNCTION(BlueprintNativeEvent)
bool ServerValidateTarget(AActor* Target) const;

// Find alternative if primary rejected
UFUNCTION(BlueprintNativeEvent)
AActor* FindAlternativeTarget(AActor* RejectedTarget) const;

GA_SoftLockMode

Timer-based soft lock that continuously updates target selection. Useful for bow aiming or combat stances.

Configuration

UPROPERTY(EditDefaultsOnly, Category = "Targeting")
FGameplayTag TargetingPresetTag;  // Query preset

UPROPERTY(EditDefaultsOnly, Category = "Targeting")
float UpdateInterval = 0.1f;       // Update every 100ms

UPROPERTY(EditDefaultsOnly, Category = "Targeting|Network")
float MinSyncInterval = 0.1f;      // Rate limit server syncs

Effects

UPROPERTY(EditDefaultsOnly, Category = "Effects")
TSubclassOf<UGameplayEffect> SoftLockModeEffect;  // Applied while active

Flow

1. Ability activates (e.g., hold aim button)
2. Spawns AbilityTask_SoftLockTick
3. Task runs targeting queries at UpdateInterval
4. Target changes sync to server (rate-limited)
5. Ability ends when cancelled (release aim button)

Usage Example

// Bind to aim input
void AMyCharacter::OnAimStart()
{
    AbilitySystemComponent->TryActivateAbilityByClass(UGA_SoftLockMode::StaticClass());
}

void AMyCharacter::OnAimEnd()
{
    AbilitySystemComponent->CancelAbilityHandle(SoftLockHandle);
}

GA_CycleTarget

Switch between targets while locked. Supports sequential (next/prev) and directional (left/right/up/down) cycling.

Configuration

UPROPERTY(EditDefaultsOnly, Category = "Targeting")
ECycleDirection CycleDirection = ECycleDirection::Next;

UPROPERTY(EditDefaultsOnly, Category = "Targeting")
FGameplayTag CyclePresetTag;  // Uses ViewAngle filter

Cycle Directions

enum class ECycleDirection : uint8
{
    Next,      // Cycle clockwise on screen
    Previous,  // Cycle counter-clockwise
    Left,      // Target to the left
    Right,     // Target to the right
    Up,        // Target above
    Down       // Target below
};

Cues

UPROPERTY(EditDefaultsOnly, Category = "Cues")
FGameplayTag CycleSuccessCue;  // Target switched
FGameplayTag CycleFailedCue;   // No target in direction

Usage Example

Create ability instances for each direction:

// GA_CycleTarget_Next (default: Next)
// GA_CycleTarget_Left (CycleDirection: Left)
// GA_CycleTarget_Right (CycleDirection: Right)

// Bind to right stick flick
void AMyCharacter::OnRightStickFlick(FVector2D Direction)
{
    if (Direction.X > 0.5f)
        ASC->TryActivateAbilityByClass(UGA_CycleTarget_Right::StaticClass());
    else if (Direction.X < -0.5f)
        ASC->TryActivateAbilityByClass(UGA_CycleTarget_Left::StaticClass());
}

Setting Up GAS Abilities

1. Grant Abilities

void AMyCharacter::GrantTargetingAbilities()
{
    if (!AbilitySystemComponent) return;

    // Grant hard lock ability
    FGameplayAbilitySpec HardLockSpec(UGA_HardLock::StaticClass(), 1);
    AbilitySystemComponent->GiveAbility(HardLockSpec);

    // Grant cycle abilities
    FGameplayAbilitySpec CycleNextSpec(UGA_CycleTarget::StaticClass(), 1);
    AbilitySystemComponent->GiveAbility(CycleNextSpec);
}

2. Bind to Input

Using Enhanced Input:

void AMyCharacter::SetupInputBindings()
{
    // Lock-on button
    EnhancedInput->BindAction(IA_LockOn, ETriggerEvent::Triggered, this, &AMyCharacter::OnLockOnPressed);
}

void AMyCharacter::OnLockOnPressed()
{
    AbilitySystemComponent->TryActivateAbilityByClass(UGA_HardLock::StaticClass());
}

3. Configure Ability Defaults

In your ability Blueprint or C++ subclass:

UMyHardLockAbility::UMyHardLockAbility()
{
    TargetingPresetTag = FGameplayTag::RequestGameplayTag("Agentic.Targeting.Preset.Melee");
    MaxLockRange = 1500.0f;
    LatencyTolerance = 1.15f;  // 15% tolerance for high-latency games
}

Network Architecture

All GAS abilities use:

ServerSetReplicatedTargetData for prediction
COND_SkipOwner on component (owner predicts, others replicate)
Rate-limited syncs to prevent bandwidth issues

API Reference

On this page