EnvironmentQuery

自动关联目录:EnvironmentQuery

EQS 回答的是"空间上哪里最合适":找一个埋伏点、找一个远离玩家的撤退点、找一条视野最好的巡逻路线。

用代码写这类需求会变成一堆嵌套循环与打分逻辑,EQS 把它变成声明式的"生成候选点 → 逐项打分 → 取最优"。

三段结构

阶段说明
Generator生成候选点(网格、圆环、路径上的点、当前位置周围…)
Test对每个候选点打分或过滤
Query 结果取最高分 / 随机前 N 个
Generator(候选点)
  ├── Test: 距离目标 > 500 ? 淘汰
  ├── Test: 是否可见玩家 ? 加分
  ├── Test: 是否在 NavMesh 上 ? 淘汰
  └── 输出:最高分的点

常用 Generator

Generator用途
Points: Grid在矩形网格上布点
Points: Circle / Donut环形布点(围绕自己或目标)
Points: Pathing Grid沿可达路径布点
Actors Of Class直接以某类 Actor 为候选
Composite组合多个 Generator

常用 Test

Test打分依据
Distance与某点/Actor 的距离
Dot朝向关系(正面/背面)
Pathfinding路径长度 / 是否可达
Trace射线(可见性、遮挡)
Overlap重叠检测
Gameplay Tags目标身上的标签
Project投影到 NavMesh
Test 用途说明
Score加权打分(越大越好)
Filter不满足即淘汰
Filter and Score先淘汰再打分

先用 Filter 再用 Score:候选点越少,后续测试越便宜。把最便宜、最能砍的测试放前面。

运行方式

// 通过行为树的 EQS 任务(最常用)
// 或 C++ 直接发起
FQueryFinishedSignature OnFinished;
EnvQueryInstance->RunQuery(...);
用法说明
行为树 Run EQS Query 任务结果写进黑板,最省事
UEnvQueryManager::RunQueryC++ 里手动发起,异步回调
Run EQS 调试 Pawn编辑器里实时看打分

性能

EQS 是 AI 系统里最容易拖垮性能的部分,因为它天然是多次射线/寻路查询。

手段说明
降频不要每帧跑;0.5~2 秒一次或事件驱动
限制候选点数量Generator 的密度与范围
先过滤后打分便宜的测试放前面
限制并发查询Max Simultaneous Queries
分帧开启分帧执行避免单帧尖峰
按 Significance 分级远处 AI 不跑或跑简化版

代价与权衡

设计收益代价什么时候不该用
声明式查询可读性远好于手写打分逻辑每次查询是多射线/多寻路高频需求必须节流
Filter 在前候选点迅速减少顺序错了就白付成本Trace/Pathfinding 绝不该放最前
Generator 密度高选点精细候选点数 × 测试数 = 成本远处 AI 应用低密度版本
异步查询不阻塞结果延迟到达需要即时反应的场景要缓存
EQS vs 手写可配置、可复用极特殊的选择逻辑反而更难表达简单"最近目标"不必用 EQS

常见坑

坑说明
每帧跑 EQS帧率杀手
候选点太密 + Trace 测试射线数量爆炸
忘记投影到 NavMesh选到不可达的点,AI 卡住
打分权重只调 Test 不改 Generator应该先保证候选点覆盖了合理位置
查询结果没写回黑板行为树后续节点拿不到
把 Trace 测试放在 Filter 之前成本最高的一项先跑了
并发查询过多单帧尖峰
只在编辑器测试打包后性能不同

排查顺序

1. 选点不对?→ 用 Run EQS 调试 Pawn 实时看打分
2. 候选点没覆盖合理位置?→ 先改 Generator(范围/密度/类型)
3. 结果可达吗?→ 是否 Project 到 NavMesh
4. 慢?→ 降频 + 减少候选点 + Filter 前置 + 限制并发
5. 拿不到结果?→ 是否写回黑板
6. 调试 → Gameplay Debugger 的 EQS 页签(见 [AI 调试与性能](/4d3761e5.html))