In addition to Behavior Trees which can be used to make decisions on which logic to execute, and the Environmental Query System (EQS) used to retrieve information about the environment; another tool you can use within the AI framework which provides sensory data for an AI is the AI Perception System. This provides a way for Pawns to receive data from the environment, such as where noises are coming from, if the AI was damaged by something, or if the AI sees something. This is accomplished with the AI Perception Component which acts as a stimuli listener and gathers registered Stimuli Sources.
When a stimuli source is registered, the event On Perception Updated (or On Target Perception Updated for target selection) is called which you can use to fire off a new Blueprint Script and (or) update variables that are used to validate branches in a Behavior Tree.
AI Perception Component
The AI Perception Component is a type of Component that can be added to a Pawn's AIController Blueprint from the Components window and is used to define what senses to listen for, the parameters for those senses, and how to respond when a sense has been detected. You can also use several different functions to get information about what was sensed, what Actors were sensed, or even disable or enable a particular type of sense.
To add the AI Perception Component, click the +Addbutton in your Blueprint and select AIPerception.
Once the AI Perception Component has been added, you can access its properties inside the Details panel.
AI Perception Properties
In addition to the common properties available in the Details panel for the AI Perception Component, you can add the type of Senses to perceive under the AI Perception and Senses Config section. Depending on the type of Sense, different properties are available to adjust how the Sense is perceived.
The Dominant Sense property can be used to assign a Sense that should take precedence over other senses when determining a sensed Actor's location. This should be set to one of the senses configured in your Senses Config section or set to None.
AI Damage
If you want your AI to react to damage events such as Event Any Damage, Event Point Damage, or Event Radial Damage, you can use the AI Damage Sense Config. The Implementation property (which defaults to the engine class AISense_Damage) can be used to determine how damage events are handled, however, you can create your damage classes through C++ code.
| Property | Description |
|---|---|
Implementation | The AI Sense Class to use for these entry (defaults to AISense_Damage). |
Debug Color | When using the AI Debugging tools, what color to draw the debug lines. |
Max Age | Determines the duration in which the stimuli generated by this sense becomes forgotten (0 means never forgotten). |
Starts Enabled | Determines whether the given sense starts in an enabled state or must be manually enabled/disabled. |
AI Hearing
The AI Hearing sense can be used to detect sounds generated by a Report Noise Event, for example, a projectile hits something and generates a sound that can be registered with the AI Hearing sense.
| Property | Description |
|---|---|
Implementation | The AI Sense Class to use for this entry (defaults to AISense_Hearing). |
Hearing Range | The distance in which this sense can be perceived by the AI Perception system. |
Lo SHearing Range | This is used to display a different radius in the debugger for Hearing Range. |
Detection by Affiliation | Determines if Enemies, Neutrals, or Friendlies can trigger this sense. |
Debug Color | When using the AI Debugging tools, what color to draw the debug lines. |
Max Age | Determines the duration in which the stimuli generated by this sense becomes forgotten (0 means never forgotten). |
Starts Enabled | Determines whether the given sense starts in an enabled state or must be manually enabled/disabled. |
AI Prediction
This asks the Perception System to supply the Requestor with PredictedActor's predicted location in PredictionTime seconds.
| Property | Description |
|---|---|
Debug Color | When using the AI Debugging tools, what color to draw the debug lines. |
Max Age | Determines the duration in which the stimuli generated by this sense becomes forgotten (0 means never forgotten). |
Starts Enabled | Determines whether the given sense starts in an enabled state or must be manually enabled/disabled. |
AI Sight
The AI Sight config enables you to define parameters that allow an AI character to "see" things on your Level. When an Actor enters the Sight Radius, the AI Perception System signals an update and passes through the Actor that was seen (for example a Player enters the radius and is perceived by the AI who has Sight Perception).
| Property | Description |
|---|---|
Implementation | The AI Sense Class to use for this entry (defaults to AISense_Sight). |
Sight Radius | The max distance over which this sense can start perceiving. |
Lose Sight Radius | The max distance in which a seen target is no longer perceived by the sight sense. |
Peripheral Vision Half Angle Degrees | How far to the side the AI can see in degrees. The value represents the angle measured to the forward vector, not the whole range. You can use SetPeripheralVisionAngle in Blueprint to change the value at runtime. |
Detection by Affiliation | Determines if Enemies, Neutrals, or Friendlies can trigger this sense. This property can be used to set up Sight perception for teams. Currently, Affiliation can only be defined in C++. For Blueprints, you can use the Detect Neutrals option to detect all Actors, then use Tags to filter out Actor types. |
Auto Success Range from Last Seen Location | When greater than zero, the AI will always be able to see the target that has already been seen as long as they are within the range specified here. |
Point of View Backward Offset | Point of view move back distance for cone calculation. In conjunction with near clipping distance, this will act as a close by awareness and peripheral vision. |
Near Clipping Radius | Near clipping distance, to be used with point of view backward offset. Will act as a close by awarness and peripheral vision. |
Debug Color | When using the AI Debugging tools, what color to draw the debug lines. |
Max Age | Determines the duration in which the stimuli generated by this sense become forgotten (0 means never forgotten). |
Starts Enabled | Determines whether the given sense starts in an enabled state or must be manually enabled/disabled. |
AI Team
This notifies the Perception component owner that someone on the same team is close by (radius is sent by the gameplay code which sends the event).
| Property | Description |
|---|---|
Debug Color | When using the AI Debugging tools, what color to draw the debug lines. |
Max Age | Determines the duration in which the stimuli generated by this sense becomes forgotten (0 means never forgotten). |
Starts Enabled | Determines whether the given sense starts in an enabled state or must be manually enabled/disabled. |
AI Touch
The AI Touch config setting gives you the ability to detect when the AI bumps into something or something bumps into it. For example, in a stealth-based game, you may want a Player to sneak by an enemy AI without touching them. Using this Sense you can determine when the Player touches the AI and can respond with different logic.
| Property | Description |
|---|---|
Debug Color | When using the AI Debugging tools, what color to draw the debug lines. |
Max Age | Determines the duration in which the stimuli generated by this sense becomes forgotten (0 means never forgotten). |
Starts Enabled | Determines whether the given sense starts in an enabled state or must be manually enabled/disabled. |
Perception Events
The Events section enables you to define what happens when the AI Perception System receives an update or when the AI Perception Component is activated or deactivated.
| Property | Description |
|---|---|
On Perception Updated |  This Event will fire when the Perception System receives an update and will return an array of Actors that signaled the update. |
On Target Perception Info Updated |  Notifies all bound objects that perception info has been updated for a given target. The notification is broadcasted for any received stimulus or on change of state according to the stimulus configuration. |
On Target Perception Updated |  This Event will fire when the Perception System receives an update and will return the Actor that signaled the update. It also returns an AI Stimulus struct that can be broken down to retrieve additional information.  Properties:
|
On Component Activated | An Event that is fired when the AI Perception Component is activated. |
On Component Deactivated | An Event that is fired when the AI Perception Component is deactivated. |
Perception Function Calls
The following functions can be called through Blueprint to get information from or affect the Perception System.
| Function | Description |
|---|---|
Get Actors Perception | Retrieves whatever has been sensed about a given Actor and returns a Sensed Actor's Data structure. |
Get Currently Perceived Actors | Returns all Actors that are being perceived based on a given Sense. If no Sense is specified, all Actors currently perceived in any way will be returned. |
Get Known Perceived Actors | Returns any Actors that have been perceived (and not yet forgotten) based on a given Sense. If no Sense is specified, all Actors that have been perceived will be returned. |
Get Perceived Hostile Actors | Returns the list of Hostile Actors (any hostile Actors that had a stimulus sensed which is not expired or successfully sensed). The method can be overridden in Blueprint to return whatever Actors list the user wants. |
Request Stimuli Listener Update | Manually forces the AI Perception System to update properties for the specified target stimuli listener. |
Set Sense Enabled | Enable or Disable the specified Sense Class. This only works if the given Sense has already been configured for the target component instance. |
Forget All | Cleans up all previous perception data. |
Forget Perception Event
You can configure the AI Perception system to forget and subsequently clean up perception data. To use this, you must set Project Settings > Engine > AI System > Forget Stale Actors to true. After that, you can use the Max Age property in the AI Sense Config to set how long it takes for perception to time out. It will forget any Actor that is not perceived for that duration.
Stimuli Source
The AI Perception Stimuli Source Component gives the owning Actor a way to automatically register itself as a stimuli source for the designated Sense(s) within the Perception System. An example use case would be to have an AI character with an AI Perception Component set up to perceive stimuli based on Sight. You could then use the Stimuli Source Component in an Actor (such as an item pickup Actor) and register it as a stimuli for Sight (which would enable the AI to "see" the Actor in the Level).
To add the AI Perception Stimuli Source Component, click the +Addbutton in your Blueprint and select AIPerception Stimuli Source.
Once the AI Perception Stimuli Source Component has been added, you can access properties for it inside the Details panel.
Stimuli Properties
In the Details panel for the AI Perception Stimuli Source Component, the following two options are available for AI Perception:
| Property | Description |
|---|---|
Auto Register as Source | Whether to automatically register the stimuli for the specified sense with respect to the owning Actor. |
Register as Source for Senses | An array of Senses to register as a source for. Click the + sign to add a Source, then click the drop-down and assign the desired Sense.  |
You can also assign any custom Senses that have been based on the AISense Class.
Stimuli Function Calls
The following functions can be called through Blueprint for the AI Perception Stimuli Source Component:
| Function | Description |
|---|---|
Register for Sense | Registers owning Actor as a stimuli source for the specified Sense class. |
Register with Perception System | Registers owning Actor as a stimuli source for Senses specified in the Register as Source for Senses property and through the Register for Sense function call. You do not need to call this function if the Auto Register as Source property is enabled. |
Unregister from Perception System | Unregisters the owning Actor from being a source of Sense stimuli. |
Unregister from Sense | Unregisters the stimuli for the specified sense with respect to the owning Actor. |
AI Perception Debugging
You can debug AI Perception using the AI Debugging tools by pressing the '(apostrophe) key while your game is running, then pressing Numpad key 4 to bring up the Perception information.
Please see the AI Debugging tools page and the Perception section for more information.