Language:
Page Info
Skill Level:
Engine Version:

Environment Query System User Guide

Choose your OS:

Enabling the Environment Query System

  1. Edit Menu -> Editor Preferences

  2. Experimental

  3. Scroll down to AI

  4. Enable Environment Query System

Parts of a Environment Query

An Environment Query is actually made up a number of different pieces. You must call an Environment Query from a Behavior Tree, and then the actual Environment Query will use its Generator, reference its Contexts, and use its Tests to give the Behavior Tree the highest weighted result.

Behavior Tree

To use an Environment Query in a Behavior Tree, you need a Run EQS Query Task node.

runEQS.png

Selecting it in the Behavior Tree will enable you to set the Query Template property (the Environment Query asset), set its Query Params properties (which are the named values that are passed into the Environment Query asset), and which Blackboard Key it should return the highest weighted result to (object or vector).

runEQS_details.png

See the Behavior Tree documentation for more information on their usage.

Environment Query

The Environment Query asset is what you call in the Behavior Tree using the Run EQS Query node, to test a number of Actors or locations to find the "best" one. What is really defined as "best" is really up to the way the Tests are structured in the Environment Query.

Environment Queries can be created in Blueprint and C++.

Generator

A Generator produces the locations or Actors, referred to as Items, that will actually be tested and weighted, with the highest weighted location or Actor being returned to the Behavior Tree.

Generators can be created in Blueprint and C++.

Contexts

Contexts are a frame of reference for various tests and Generators. They can be as simple as The Querier or more complex such as All Actors of a Type.

Of note is the fact a Generator, such as the Simple Grid Generator can use a Context that returns multiple locations or Actors. This will create a Simple Grid, of the defined size and density, at the location of each Context.

Contexts can be created in Blueprint and C++.

Tests

Tests are how the Environment Query decides which item from the Generator is the "best". The default tests cover a good percentage of use cases, such as can an item trace to another location or is the distance between an item and context is within a specified range.

Currently, Tests must be created in C++; there is no Blueprint implementable version of them.

Creating a Query

newQuery.png

  1. In the Content Browser, left-click the Create button

  2. Select Miscellaneous -> Environment Query

Creating a Blueprint Context

  1. In the Content Browser, left-click the Create button

  2. Select Blueprint

  3. Expand All Classes

  4. Search for EnvQueryContext

  5. Select EnvQueryContext_BlueprintBase

Creating a Blueprint Generator

  1. In the Content Browser, left-click the Create button

  2. Select Blueprint

  3. Expand All Classes

  4. Search for EnvQueryGenerator

  5. Select EnvQueryGenerator_BlueprintBase

Connecting the Root to the Generator

connectRootToGen.png

Just Left-click and drag from the dark bar at the bottom of the Root node to the dark bar at the top of the Generator node to make a connection.

Alternatively, if you Left-click and drag into the graph area, you'll get an option to create a new Generator node.

While you can have more than one Generator connected to the Root, only the left most, valid Generator is used in the Query.

Adding a Query to a Behavior Tree

To use an Environment Query in a Behavior Tree, you need a Run EQS Query Task node.

runEQS.png

  1. Right-click in the Behavior Tree graph area.

  2. Create a Task -> Run EQSQuery node.

  3. Select the newly created Run EQSQuery node, and change the Query Template property to your Environment Query asset (or you can create a new one from within the pull down).

  4. Optionally, set any Query Params the Environment Query may be looking for.

  5. Finally, set the Blackboard Key to be set by the Environment Query, only Object and Vector Blackboard Keys are usable here.

Editing a Query

Adding a Generator

  1. Right-click in the graph area of the Query, and select a Generator.

addGenToQuery.png

Adding Tests

  1. Right-click a Generator and select a Test to add.

addTest.png

Modifying Tests

  1. Select a Test on a Generator and modify it in the Details panel

editTest.png

See the Environmental Query System Node Reference for usage information on individual tests.

Previewing the Query Results

See the Environmental Query System Test Pawn documentation for information on how to preview the results of a Query

testingPawnBanner.png

Editing a Context

A newly created EnvQueryContext Blueprint will have 4 implementable functions:

implementableFunctions.png

  • Provide Single Location

  • Provide Single Actor

  • Provide Locations Set

  • Provide Actors Set

Implementing one (or more) of these will enable you to create your own custom Contexts for use within Tests in a Query. Right-click the function or functions you want to implement and select Implement Function.

Provide Single Location

Returns a single location (vector). How you generate that location is up to you. For example, this function will return the trace hit location of a random Actor (that is one of the types found in the DesiredObjectType array, such as Pawn, Vehicle, etc...) found within 1500 cm of the Querier:

Provide Single Actor

Returns a single Actor. How you find that Actor is up to you. In this example, the function will return Player 0's controlled (possessed) Actor:

Provide Locations Set

Returns an array of locations (vectors). How you generate these locations is up to you. This example graph will trace from 16 evenly spaced locations on a circle with a radius of 1500 units, returning successful hits on the environment:

Provide Actors Set

Returns an array of Actors. How you find these Actors is up to you. For example, this function will return an array of MyCharacter Actors that have the variable Team Number set to 1:

Editing a Generator

Event Do Item Generation

implementDoItem.png

This is the primary function for the Generator. When you implement this function, you'll get an array of locations that are the Context locations passed in from the Environment Query. Depending on the Context, this just may be an array of one entry with the location of the Querier, or it could be the locations of every health pack in the level.

Add Generated Actor

AddGenActor.png

Since functions can only return one value, the "Do Item Generation" function actually has two arrays it can fancily pass back to the Environment Query. This node will add an Actor to the Actor return array, and can also be used with the Add Generated Vector node to also return location values.

How the Generator decides what it's actually passing back to the Behavior tree is based on what Blackboard key you are setting from the EnvQuery node.

Add Generated Vector

AddGenVec.png

Since functions can only return one value, the "Do Item Generation" function actually has two arrays it can fancily pass back to the Environment Query. This node will add a Vector to the vector return array, and can also be used with the Add Generated Actor node to also return Actor values.

How the Generator decides what it's actually passing back to the Behavior tree is based on what Blackboard key you are setting from the EnvQuery node.

Example Generator

This will trace from the edge of a circle that has a radius of Rad towards the Querier. It will space the traces a number of degrees apart based on the Number of Spokes value (so 360/Number of Spokes). The locations of the traces will only be stored if they hit the environment, essentially looking for a surface that can't see who's calling it.

It ends up looking like this:

customGenOutput.png

The one thing this example should do is use the Context Locations passed in from the Do Item Generation to modify where the circle is generated. This wasn't done just do to image size constraints.