Environment Query System User Guide

Describes the common methods of creating and working with EQS assets.

Windows
MacOS
Linux

This page covers the typical workflows for enabling, creating and editing Environmental Query System (EQS) assets. 

Enabling EQS

Before you can start working with EQS, you will need to enable it from the Editor Preferences menu.

  • Under Editor Preferences > Experimental > AI section, enable the Environmental Query System option.

    EQSUG_EnableEQS.png

Creating an EQS Query

To create an EQS Asset: 

  1. Click the Add New button in the Content Browser, then under Artificial Intelligence, select Environment Query

    EQSUG_CreateEQSAsset.png

  1. Enter in a name for your new EQS asset. 

    EQSUG_EnterEQSName.png

In addition to Environment Query, you can create custom Generator and Context Blueprint assets in the Content Browser.

Editing an EQS Query

Inside the EQS asset, you can use a Generator to produce the locations or Actors that will be tested and weighted, provide a Context or frame of reference, and Tests to determine which item from the Generator is the best option. The following section will illustrate how to create each of these within the EQS asset.

To add a Generator:

  • Right-click in the EQS Graph and select your desired Generator type.

    EQSUG_AddGenerator.png

    After adding a Generator, drag off the Root node and connect it to your Generator. 

    EQSUG_ConnectGenerator.png

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

To add a Test:

  • Right-click on a Generator and select a Test to add. 

    EQSUG_AddTest.png

    After adding a Test, if will appear attached to the Generator. Select the Test to adjust properties in the Details panel. 

    EQSUG_AddTestDetails.png

To define a Context:

  • In the Details panel for a Test, change the EnvQueryContext to your desired Context. 

    EQSUG_Context.png

    The property name may vary based on the type of Test. Please see Tests for more information.

Previewing an EQS Query

You can preview the results of an EQS Query inside the Editor, where weighted/filtered results will be represented by debug spheres. 

EQSUG_Preview.png

In the image above, we debug an EQS Query that returns a location which provides line of sight to the Player Character in the Level. 

Please see AI Debugging or EQS Testing Pawn for more information.

Using EQS with Behavior Trees

After creating EQS Query, you can run the query inside a Behavior Tree as part of a Task.

  1. Inside a Behavior Tree, right-click and add the Run EQS Query Task node.

    EQSUG_RunEQS.png

  2. For Run EQS Query, assign the Query Template (desired EQS asset) to execute and the Blackboard Key it should return.

    EQSUG_EditEQSBT.png

    The Blackboard Key that is returned will be the highest weight result (Object or Vector). In the example above, we have an EQS Query that is used to locate the Player and provide that location back to a Blackboard Key called  MoveToLocation. 

    You can optionally add parameters to pass to the EQS asset through the Query Config option.

Using EQS with Native Code

While EQS Queries generally run within Behavior Trees, you can also use them directly from native code. The following example shows a hypothetical query that finds a safe place for a character or item to spawn within a specific zone:

// These names must match the variable names used in the query
static const FName SafeZoneIndexName = FName(TEXT("SafeZoneIndex"));
static const FName SafeZoneRadiusName = FName(TEXT("SafeZoneRadius"));

// Run a query to find a safe spawn point based on the zone's index and a safety radius
bool AMyActor::RunPlacementQuery(const UEnvQuery* PlacementQuery)
{
    if (PlacementQuery)
    {
        // Set up a query request
        FEnvQueryRequest QueryRequest(PlacementQuery, this);

        // Set query parameters
        QueryRequest.SetIntParam(SafeZoneIndexName, SafeZoneIndexValue);
        QueryRequest.SetFloatParam(SafeZoneRadiusName, SafeZoneRadius);

        // Execute the query
        QueryRequest.Execute(EEnvQueryRunMode::RandomBest25Pct, this, &AFortAthenaMutator_SpawningPolicyBase::OnEQSSpawnLocationFinished);

        // Return true to indicate that we started the query
        return true;
    }

    // Return false to indicate that we failed to start a query
    return false;
}
Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback