Filtering Perceived Actors Using Perception Stimuli

In this lesson, you will learn how to categorize perceived actors in real-time by inspecting the metadata embedded within their AI perception stimuli.

Distinguishing Threats from Allies

When your AI detects an actor, the AIPerceptionComponent triggers an event that provides an AActor* and an FAIStimulus struct. To decide how to react—whether to attack, ignore, or assist—you must look beyond the mere fact that an actor exists and interpret the context of the stimulus.

We use two primary techniques for this: Team Affiliation via the IGenericTeamAgentInterface and Stimulus Tags for specific gameplay categories.

Implementing Team Logic

If your actors implement the IGenericTeamAgentInterface, you can categorize them using a FGenericTeamId. When processing a stimulus, you compare the perceived actor's team ID against the AI's own ID:

// Within your Perception Event handler
ETeamAttitude::Type GetAttitude(AActor* PerceivedActor) {
    IGenericTeamAgentInterface* PercievedTeam = Cast<IGenericTeamAgentInterface>(PerceivedActor);
    if (PercievedTeam) {
        return FGenericTeamAgentInterface::GetTeamAttitudeTowards(this, *PerceivedActor);
    }
    return ETeamAttitude::Neutral; // Default for non-team actors
}

Leveraging Stimulus Tags

For objects that aren't formal "teams"—like a hostile turret or a neutral power-up—we use Tag filtering on the FAIStimulus. By assigning specific tags to your detection components or actors, you can filter results in your perception callback.

If you want to filter specifically for "Hostile" stimulus types, you check the stimulus metadata:

void AMyAIController::OnTargetPerceptionUpdated(AActor* Actor, FAIStimulus Stimulus) {
    if (Stimulus.Tag == FName("Hostile")) {
        // Logic to transition to 'Combat' state
    } else if (Stimulus.Tag == FName("Civilian")) {
        // Logic to ignore or protect
    }
}

Why this matters

By decoupling detection from reaction, you prevent your AI from behaving aggressively toward non-combatants. Instead of hardcoding relationships in your perception component, you create a modular system where the stimulus metadata acts as a filter, allowing the AI to query its internal blackboard with high-level classifications like "Target" or "Ally" rather than raw AActor references.

Key Takeaway: Use the FAIStimulus tag and IGenericTeamAgentInterface to classify perceived entities, ensuring your AI logic remains reactive to the specific nature of the stimulus rather than just the detection event itself.