Environment Queries

Search 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.

cfa search_eqs_nodes --kind generator
cfa search_eqs_nodes --queries "distance,trace,pathfinding" --max-results 3

Read 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.

cfa get_eqs_node_type_info --node-class EnvQueryGenerator_SimpleGrid
cfa get_eqs_node_type_info --node-class EnvQueryTest_Distance --filter score

Create 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.

cfa create_env_query --name EQ_Cover --path /Game/AI/Queries
cfa create_env_query --name EQ_Cover --generator EnvQueryGenerator_SimpleGrid

Read 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.

cfa get_env_query --env-query /Game/AI/Queries/EQ_Cover --verbosity full

Add 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.

cfa add_eqs_option --env-query /Game/AI/Queries/EQ_Cover --generator EnvQueryGenerator_SimpleGrid --properties '{"GridSize":{"DefaultValue":1000}}'

Remove an option from a query

Removes an option and every test on it.

cfa remove_eqs_option --env-query /Game/AI/Queries/EQ_Cover --option 1

Add 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.

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 Match

Remove a test from an option

Removes a test and renumbers the rest so their order matches their position.

cfa remove_eqs_test --env-query /Game/AI/Queries/EQ_Cover --test EnvQueryTest_Distance

Set 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.

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.0

Check 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.

cfa validate_env_query --env-query /Game/AI/Queries/EQ_Cover

Run 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.

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}'

During 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'.

cfa play_in_editor
cfa get_eqs_runtime --actor Guard_1
cfa get_eqs_runtime --max-queries 3 --max-results 3