Environment Queries
Environment Queries: Build the queries AI uses to make spatial decisions. Unreal Engine 5 command reference with parameters and examples.
Loading…
Environment Queries: Build the queries AI uses to make spatial decisions. Unreal Engine 5 command reference with parameters and examples.
12 commands. Each shows its parameters and an example, and has a copyable deep link, so you (or an AI agent) can jump straight to one.
search_eqs_nodesSearch EQS generators, tests and contexts, ranked
Searches every generator, test and context class in the project, engine and Blueprint alike, ranked the same way the Behavior Tree search ranks: exact beats prefix, prefix beats a word-boundary hit, that beats a loose substring. Pass --queries for several keywords in one call. The class prefix is optional, so 'Distance' finds EnvQueryTest_Distance.
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | No | Keyword to rank against. Omit to list everything of the chosen kind |
| queries | stringlist | No | Several keywords at once; each gets its own ranked list |
| kind | string | No | generator | test | context | all |
| max_results | int | No | Maximum results per query |
cfa search_eqs_nodes --kind generator
cfa search_eqs_nodes --queries "distance,trace,pathfinding" --max-results 3get_eqs_node_type_infoRead an EQS generator, test or context class
Returns a class in full: its chain and every editable property with type, default and tooltip. Properties that take a context class are flagged, because a context is never added to a query, it is chosen on a generator or a test.
| Parameter | Type | Required | Description |
|---|---|---|---|
| node_class | string | Yes | Generator, test or context class name |
| kind | string | No | Narrow the lookup: generator | test | context |
| filter | string | No | Case-insensitive substring filter on property names |
cfa get_eqs_node_type_info --node-class EnvQueryGenerator_SimpleGrid
cfa get_eqs_node_type_info --node-class EnvQueryTest_Distance --filter scorecreate_env_queryCreate an Environment Query
Creates an Environment Query asset. Pass --generator to give it a first option so it is runnable immediately. The asset is built directly rather than through the EQS editor factory, which lives in a plugin that exports nothing; the visual graph appears when a human first opens it.
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Asset name |
| path | string | No | Content folder |
| generator | string | No | Generator class for a first option |
cfa create_env_query --name EQ_Cover --path /Game/AI/Queries
cfa create_env_query --name EQ_Cover --generator EnvQueryGenerator_SimpleGridget_env_queryRead a query's options and tests
Returns every option with its generator, its item type and its ordered tests, each with the editor's own description text; a test flagged supported:false is one the engine will drop at run time. 'params' lists the named parameters the query reads through AIDataProvider_QueryParams bindings, which is what run_env_query --params and a Behavior Tree task's QueryConfig feed. Use --verbosity full to include all generator and test properties. 'has_editor_graph' reports whether the visual graph has been built yet; false is normal for a query authored here and is not damage.
| Parameter | Type | Required | Description |
|---|---|---|---|
| env_query | string | Yes | Environment Query path |
| verbosity | string | No | summary | standard | full |
cfa get_env_query --env-query /Game/AI/Queries/EQ_Cover --verbosity fulladd_eqs_optionAdd a generator option to a query
Adds an option and its generator. A query runs its options in order and uses the first that produces items, so several options are a fallback chain. Generator properties are set in the same call.
| Parameter | Type | Required | Description |
|---|---|---|---|
| env_query | string | Yes | Environment Query path |
| generator | string | Yes | Generator class |
| properties | string | No | Generator properties, as a JSON object |
cfa add_eqs_option --env-query /Game/AI/Queries/EQ_Cover --generator EnvQueryGenerator_SimpleGrid --properties '{"GridSize":{"DefaultValue":1000}}'remove_eqs_optionRemove an option from a query
Removes an option and every test on it.
| Parameter | Type | Required | Description |
|---|---|---|---|
| env_query | string | Yes | Environment Query path |
| option | string | Yes | Option index, or the generator's class name |
cfa remove_eqs_option --env-query /Game/AI/Queries/EQ_Cover --option 1add_eqs_testAdd a test to an option
Adds a test and sets the things that decide what it does: --purpose (Filter, Score or FilterAndScore), --filter-type (Minimum, Maximum, Range or Match) when it filters, --scoring-equation (Linear, Square, InverseLinear, SquareRoot or Constant) and --scoring-factor as its weight. Tests run in order and are renumbered automatically. An invalid enum value comes back with the valid ones listed.
| Parameter | Type | Required | Description |
|---|---|---|---|
| env_query | string | Yes | Environment Query path |
| option | string | No | Option index, or the generator's class name |
| test_class | string | Yes | Test class, e.g. EnvQueryTest_Distance |
| purpose | string | No | Filter | Score | FilterAndScore |
| filter_type | string | No | Minimum | Maximum | Range | Match |
| scoring_equation | string | No | Linear | Square | InverseLinear | SquareRoot | Constant |
| scoring_factor | string | No | Weight applied to this test's score |
| index | int | No | Position among the option's tests; default appended |
| properties | string | No | Any other test properties, as a JSON object |
cfa add_eqs_test --env-query /Game/AI/Queries/EQ_Cover --test-class EnvQueryTest_Distance --purpose Score --scoring-equation InverseLinear --scoring-factor 2.0
cfa add_eqs_test --env-query /Game/AI/Queries/EQ_Cover --test-class EnvQueryTest_Trace --purpose Filter --filter-type Matchremove_eqs_testRemove a test from an option
Removes a test and renumbers the rest so their order matches their position.
| Parameter | Type | Required | Description |
|---|---|---|---|
| env_query | string | Yes | Environment Query path |
| option | string | No | Option holding the test |
| test | string | Yes | Test index, or its class name |
cfa remove_eqs_test --env-query /Game/AI/Queries/EQ_Cover --test EnvQueryTest_Distanceset_eqs_node_propertySet a property on a generator or a test
Writes any reflected property on an option's generator, or on one of its tests when --test is given. Every property type works, including the FAIDataProvider values EQS uses for numbers: address the literal as e.g. ScoringFactor.DefaultValue. To bind one to a named query parameter set its DataBinding to AIDataProvider_QueryParams (a bare class name creates the instance) and set DataBinding.ParamName; DataField then defaults to the matching value field and get_env_query lists the parameter. --option asset targets the query's own settings instead. --index reorders: with --test it moves that test within its option, otherwise it moves the option within the query. Both orders are execution order, so this is authoring and not layout. bWorkOnFloatValues is routed through the engine's own mutator, which also repairs FilterType; writing it raw would leave a float test filtering by match. An unknown name comes back with the close matches.
| Parameter | Type | Required | Description |
|---|---|---|---|
| env_query | string | Yes | Environment Query path |
| option | string | No | Option index, the generator's class name, or 'asset' for the query itself |
| test | string | No | Test to target; omit to target the option's generator |
| property | string | No | Property name or path; [N] index, [-] append and [Key] map rows work (see set_object_property) |
| value | string | No | Value to write |
| properties | string | No | Several properties at once, as a JSON object |
| index | int | No | Move the test, or the option when no test is named, to this position |
cfa set_eqs_node_property --env-query /Game/AI/Queries/EQ_Cover --property GenerateAround --value EnvQueryContext_Querier
cfa set_eqs_node_property --env-query /Game/AI/Queries/EQ_Cover --test EnvQueryTest_Distance --property ScoringFactor.DefaultValue --value 3.0validate_env_queryCheck a query and return a verdict
Returns pass, pass_with_warnings or fail with the reasons. Errors cover a query with no options, an option with no generator, a test whose item type the generator does not produce (the engine silently removes it at run time), and any node not outered to the query, which is what makes the editor report an asset as corrupt. Warnings cover test ordering the editor would renumber, and an option that never scores so every surviving item ties.
| Parameter | Type | Required | Description |
|---|---|---|---|
| env_query | string | Yes | Environment Query path |
cfa validate_env_query --env-query /Game/AI/Queries/EQ_Coverrun_env_queryRun a query in the editor and return the engine's debug view
Runs the query synchronously in the editor world and returns what the Gameplay Debugger would show: the option that produced items, every test that ran in order, each passed item with its raw value and weighted score per test, the items that failed with the test that rejected them, and per-step timing. 'dropped_tests' lists tests the engine removed because their item type does not match the generator. Runs in the PLAY world whenever Play In Editor is active and reports which world it used: a query whose context reads the player resolves to nothing in the editor world, so every test passes and a green result means nothing. Picks a pawn as the querier by default, or name one with --querier. --params supplies the named parameters listed by get_env_query; without them a parameterised query runs on its defaults.
| Parameter | Type | Required | Description |
|---|---|---|---|
| env_query | string | Yes | Environment Query path |
| querier | string | No | Actor to run the query as; defaults to any pawn |
| run_mode | string | No | SingleResult | RandomBest5Pct | RandomBest25Pct | AllMatching |
| max_results | int | No | Maximum passed items to report |
| max_failed | int | No | Maximum failed items to report, each with the test that rejected it |
| params | string | No | Named query parameters, as a JSON object of name to number or bool |
cfa run_env_query --env-query /Game/AI/Queries/EQ_Cover
cfa run_env_query --env-query /Game/AI/Queries/EQ_Cover --querier BP_Enemy_1 --run-mode SingleResult --max-failed 10
cfa run_env_query --env-query /Game/AI/Queries/EQ_Cover --params '{"Distance.FloatValueMax":900}'get_eqs_runtimeDuring play, the EQS queries each actor last ran
Reads the EQS debugger while Play In Editor runs: for each actor (or one named with --actor) the latest query instance per query name, with the same breakdown run_env_query gives, option used, tests run, per-item values and scores, failed items and why. A pawn's list includes queries its controller ran, which is where a Behavior Tree's Run EQS Query task runs them. This is the answer to 'why did the AI pick that spot'.
| Parameter | Type | Required | Description |
|---|---|---|---|
| actor | string | No | Actor name or label in the play world; omit for every actor |
| max_results | int | No | Maximum passed items per query |
| max_failed | int | No | Maximum failed items per query |
| max_queries | int | No | Maximum queries to report |
cfa play_in_editor
cfa get_eqs_runtime --actor Guard_1
cfa get_eqs_runtime --max-queries 3 --max-results 3