Creating Custom EQS Test Modules

Learners will develop custom C++ or Blueprint EQS tests to evaluate unique gameplay metrics beyond the default engine provided options.

In this lesson, you will learn how to extend the Environmental Query System (EQS) by creating custom C++ test modules to evaluate unique gameplay metrics that aren’t covered by default engine tests.

Why Create Custom EQS Tests?

While Unreal’s built-in tests (like Distance, Trace, or Dot Product) cover common AI needs, they often fall short for complex, game-specific logic—such as evaluating the "safety" of a cover spot based on an actor’s specific health percentage, team visibility, or dynamic environment properties. A custom test allows you to inject your own scoring logic directly into the query pipeline.

The Core Implementation

To create a custom test, you must inherit from UEnvQueryTest. You will primarily override the RunTest function. This function provides a FEnvQueryInstance, which holds the items generated by your EQS generator. Your job is to iterate through these items, perform your custom calculation, and assign a score to each.

Here is a simplified structure of a custom test:

void UMyCustomTest::RunTest(FEnvQueryInstance& QueryInstance) const
{
    for (FEnvQueryItemIterator It(QueryInstance); It; ++It)
    {
        // 1. Get the actor or location being tested
        AActor* ItemActor = GetItemActor(QueryInstance, It);
        
        // 2. Perform your unique gameplay logic
        float CustomScore = CalculateSafetyRating(ItemActor);
        
        // 3. Set the score for this specific item
        It.SetScore(TestPurpose, FilterType, CustomScore, ScorerFloatValueMin, ScorerFloatValueMax);
    }
}

Integrating Logic

When writing your RunTest logic, remember that EQS runs on the game thread. Keep your calculations lightweight. If your test requires data like "number of nearby enemies," you can cache this data in a Blackboard key or use a simple line trace. Once you’ve compiled your class, the test will appear in the EQS editor under your custom category, allowing you to treat your unique gameplay metric like a native engine feature.

By implementing custom modules, you move from using generic AI filters to creating an AI that understands the specific tactical value of your game world.

Key Takeaway: Custom EQS tests allow you to bake complex, game-specific decision-making directly into your AI’s perception pipeline by iterating over generated items and calculating bespoke scores via the RunTest override.