Download the Source Code from My Github Repo

Creating EQS Contexts in C++

In this post we’re going to explore the basics of the Environment Query System (EQS) that resides in UE4. To fully understand this post you need prior knowledge of Behavior Trees and Blackboards since these concepts won’t be explained here. In case you don’t quite remember how these work, check outEpic’s official documentationas well as my previous post onhow to create a basic patrol AI.

In this post, we’re going to create a clone ofEpic’s Advanced AI stream tutorialbut instead of using Blueprints, we’re going to code our logic inc++. Basically, we’re going to create an AI that is scared ofour player and flees when it sees him.

Before we go any further, take a look at the final result in the video below.

Download The Source Code From My Github Repo

Moreover, please note that this tutorial was written in 4.13.1 version so you may need to adjust your code based on the version of the engine you’re using.

I’m going to explain in detail what EQS actually is, the moment we use it in our Behavior Tree. But first, let’s write some code.

Creating the AI Controller

Create a Third Person C++ Template Project and create a C++ class that inherits the AIController, named MyAIController. Before you continue,create a NavMesh that covers the whole map.

Open up the header file of your class and make sure to add the following includes before the .generated.h file:

#include “Perception/AIPerceptionComponent.h”
#include “Perception/AISenseConfig_Sight.h”

Then, type in the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36 / private:
/** BlackboardComponent - used to initialize blackboard values and set/get values from a blackboard asset */
UBlackboardComponent* BlackboardComp;
/** BehaviorTreeComponent - used to start a behavior tree */
UBehaviorTreeComponent* BehaviorTreeComp;
/** Blackboard Key Value Name */
const FName BlackboardEnemyKey = FName("Enemy");
/** The function that fires when the perception of our AI gets updated */
UFUNCTION()
void OnPerceptionUpdated(TArray<AActor*> UpdatedActors);
/** A Sight Sense config for our AI */
UAISenseConfig_Sight* Sight;
protected:
/** The Behavior Tree that contains the logic of our AI */
UPROPERTY(EditAnywhere)
UBehaviorTree* BehaviorTree;
/** The Perception Component of our AI */
UPROPERTY(VisibleAnywhere)
UAIPerceptionComponent* AIPerceptionComponent;
public:
AMyAIController();
virtual void Possess(APawn* InPawn) override;
/** Returns the seeing pawn. Returns null, if our AI has no target */
AActor* GetSeeingPawn();

Then, open up the source file of your class and add the following includes:

#include “BehaviorTree/BlackboardComponent.h”
#include “BehaviorTree/BehaviorTreeComponent.h”
#include “BehaviorTree/BehaviorTree.h”
#include “EqsTutCharacter.h”

Depending on how you named your project, you may have to edit the last include.

When you’re done with the included files, type in the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66 / void AMyAIController::OnPerceptionUpdated(TArray<AActor*> UpdatedActors)
{
//If our character exists inside the UpdatedActors array, register him
//to our blackboard component
for (AActor* Actor : UpdatedActors)
{
if (Actor->IsA<AEqsTutCharacter>() & !GetSeeingPawn())
{
BlackboardComp->SetValueAsObject(BlackboardEnemyKey, Actor);
return;
}
}
//The character doesn't exist in our updated actors - so make sure
//to delete any previous reference of him from the blackboard
BlackboardComp->SetValueAsObject(BlackboardEnemyKey, nullptr);
}
AMyAIController::AMyAIController()
{
//Components Init.
BehaviorTreeComp = CreateDefaultSubobject<UBehaviorTreeComponent>(FName("BehaviorComp"));
BlackboardComp = CreateDefaultSubobject<UBlackboardComponent>(FName("BlackboardComp"));
AIPerceptionComponent = CreateDefaultSubobject<UAIPerceptionComponent>(FName("PerceptionComp"));
//Create a Sight Sense
Sight = CreateDefaultSubobject<UAISenseConfig_Sight>(FName("Sight Config"));
Sight->SightRadius = 1000.f;
Sight->LoseSightRadius = 1500.f;
Sight->PeripheralVisionAngleDegrees = 130.f;
//Tell the sight sense to detect everything
Sight->DetectionByAffiliation.bDetectEnemies = true;
Sight->DetectionByAffiliation.bDetectFriendlies = true;
Sight->DetectionByAffiliation.bDetectNeutrals = true;
//Register the sight sense to our Perception Component
AIPerceptionComponent->ConfigureSense(*Sight);
}
void AMyAIController::Possess(APawn* InPawn)
{
Super::Possess(InPawn);
if (BehaviorTree)
{
//Initialize the Blackboard and start the attached behavior tree
BlackboardComp->InitializeBlackboard(*BehaviorTree->BlackboardAsset);
BehaviorTreeComp->StartTree(*BehaviorTree);
}
//Register the OnPerceptionUpdated function to fire whenever the AIPerception get's updated
AIPerceptionComponent->OnPerceptionUpdated.AddDynamic(this, &AMyAIController::OnPerceptionUpdated);
}
AActor* AMyAIController::GetSeeingPawn()
{
//Return the seeing pawn
UObject* object = BlackboardComp->GetValueAsObject(BlackboardEnemyKey);
return object ?Cast<AActor>(object) : nullptr;
}

Save and compile your code.

Creating theBlackboard of our AI

Createthe following Blackboard:

Click on image to enlarge in a new tab

Make sure that your Enemy key has the Actor class as its Base Class as seen in the screenshot above.

Activating the Environment Query System

The EQS is still an experimental system and we explicitly need to enable it by changing some options inside the editor in order to use it on our Behavior Tree. Toactivate the EQS in 4.13 version of the engine, perform the following steps:

1. Click on the Edit menu
2. Open up the Editor Preferences
3. Select the Experimental tab
4. Check the Environment Query System

The following picture sums up the above steps:

Click on image to enlarge in a new tab

Creating an Environment Query

If you activated EQS by following the steps above, right click somewhere on the content browser and create an Environment Query (it’s located inside the Artificial Intelligence tab only after when you enable the system) named FindHidingSpot. Save it and close it. We won’tadd any logic to itjust yet because we haven’t explained what a Query actually is. Please bare with me for a few moments and everything will become clear!

Creating the Behavior Tree for our AI

Create the following Behavior Tree for our AI:

Click on image to enlarge in a new tab

The Run EQS Query node is located inside the available tasks of the behavior tree. You will notice that of the node’s properties in the details panel are marked as red. I will explain what these are in the following section.

What is the Environment Query System (EQS)?

TheEQS is a system that allows our AI to “ask” thegame’s environment specific questions and based on the received answers it will be able toact accordingly. An Environment Query consists of:

1. Generators and
2. Tests

Most Generators are used to generate an area around a specified actor in our game. This area consists of pointsand theirdensity is configurable through the corresponding editor. Moreover, the developer is able to configure the size of the area as well. Each time our AI runs an Environment Query, the system iterates through all the generated pointsin order to find a result. We’re going to specify what this result is going to be, for example, it can be another Actor, or a world space location, etc.. This is where Tests come in play.

Think of Tests asfunctionsthat filter and/or (depending on your needs) score every generated point. Tests areattachedto generators.

Based on the attached Tests, each point has a score. The point that has the higher score is considered the best match for our result.

To sum up the theory written above, here is a screenshot of how the EQS works:

If you take a second look at our Behavior Tree in the previous section you will notice that I have selected the HidingSpot as a Blackboard Key for our EQS. This means that in this case, the result of the FindHidingSpot Query is going to get stored on the HidingSpot key of our Blackboard.

Moreover, I’ve assigned the FindHidingSpot as a Query template. The Query template in this case is the query that it’s going to execute when the Run EQS Query node fires.

Last but not least, you will notice that in the RunMode in the details panel, I have selected the Single Best Item. This means that I want to store the point with the highest score only.

With that said, let’s create type some logic inside our Query.

Creating the FindHidingSpot Query

The logic that we want to create, is summed up with the following senteces:

Find a location where the enemy (in this case the player) can’t see you. This location needs to be as close as possible to the AI and at the same time, as far as possible from the enemy (in this case, the player).

To create the mentioned logic, open up the FindHidingSpot Query. Then, select thePoints: Pathing Gridgenerator. Remeber that I mentioned that you can adjust the density of the points as well as the size of the generated area. Here are the options that enable you to do so:

You will notice that the Editor mentions that the PathingGrid will be generated around Querier. In our case, this means that a of size 2000 units is going to get generated around our AI.

Right Click on your Pathing Grid andadd a Trace Test.

This is a test that performs a trace among two actors. The starting Actor is the Querier and the other end of the trace is by default our Querier again. With that said, we need to change that in order to match our needs. Specifically, we need to trace from our AI to our Player. To do that, we need to create a newContextfor that test. A Context in this case is a class that contains a function, responsible for providing results in our test.

To add a context, add a new C++ class, named FindEnemyQueryContext that inherits the EnvQueryContext class. Then, inside its header file, declare the following function:

virtualvoidProvideContext(FEnvQueryInstance&QueryInstance,FEnvQueryContextData&ContextData)constoverride;

You don’t need to specify an access modifier in this case. In the source file, add the following includes:

#include “EnvironmentQuery/EnvQueryTypes.h”
#include “EnvironmentQuery/Items/EnvQueryItemType_Actor.h”
#include “EqsTutCharacter.h”
#include “MyAIController.h”

Then, type in the following implementation of the ProvideContext function:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 / void UFindEnemyQueryContext::ProvideContext(FEnvQueryInstance& QueryInstance, FEnvQueryContextData& ContextData) const
{
Super::ProvideContext(QueryInstance, ContextData);
//Get the Owner of this Query and cast it to an actor
//Then, get the actor's controller and cast to it our AIController
//This code works for our case but avoid that many casts and one-liners in cpp.
AMyAIController* AICon = Cast<AMyAIController>((Cast<AActor>((QueryInstance.Owner).Get())->GetInstigatorController()));
if (AICon & AICon->GetSeeingPawn())
{
//Set the context SeeingPawn to the provided context data
UEnvQueryItemType_Actor::SetContextHelper(ContextData, AICon->GetSeeingPawn());
}
}

This will return the seeing pawn (if any) to our context. Comple and save your code.

Then, select the Trace test and in the context drop-down menu, select the FindenemyQueryContext class. Moreover, adjust the item height offset, to match the character’s height:

When the Trace test is done, it will generate points that the player can’t see from his current position. The next step, is to select thepoint that is close enough to our AI and far enough from our player.

To do that, add aDistance Testto our PathingGrid and select the following options:

By selecting Inverse Linear, the distance test will prefer the points that are close to our AI. Note that the Test Purpose is to Score the points only and not to filter them.

Then,add another Distance Testto our Pathing Grid. this time however, we want to get the points that are far from theplayer. To do that, in the Distance To dropdown menu, select our FindEnemyQueryContext and set the Scoring Equation to Linear as the following screenshot suggests:

We’re done with our Query. To test your AI:

• Create a Blueprint Controller based on MyAIController (BP_AICon)
• Create a Blueprint Character based on the Character class and attach the:
• SK_Mannequin to it’s static mesh
• ThirdPerson_AnimBP to it’s anim class
• BP_AICon to it’s AIController menu

• Assign our Behavior Tree to the BP_AICon
• Place the Blueprint character in the map

Then, click the play button and test your functionality!

Debugging your AI

To debug your AI during play, open up the project settings and inside the Gameplay Debugger tab, activate the following options:

Click on image to enlarge in a new tab

Moreover,activate the following option from the viewport:

Then, when playing, press the ” ‘ ” (apostrophe key) on your keyboard. You don’t to write it in the console like the previous versions.