SuperAPI AI 工具集

navigation

智能体与模型

查看项目

更新于 11-08 11:40

技能介绍

用途

本技能用于将 AI/智能体的寻路任务交给 navcat。navcat 根据原始几何体构建导航网格(navmesh,即关卡中互联的可行走多边形),并在其上回答寻路查询。当有对象需要在世界中智能移动时使用它,例如敌人绕过障碍物、NPC 巡逻、单位被命令前往某点、智能体必须避开墙壁和缺口。navcat 与渲染无关;navcat/three 可将其适配到 Three.js。

是否需要导航网格

对于“在开阔平坦地面上直接走向目标”的情况,导航网格属于过度设计,直接转向即可。当智能体必须绕过障碍物、穿越不平坦或多层地形,或作为协调的群体行动时,导航网格才有价值。如果情况更简单,自行实现转向是正确选择。

版本变化与类型确认

本技能负责将你导向正确的功能与决策,不固定精确签名,因为 navcat 的 API(导出名称、选项字段、返回结构)会随版本变化。调用前,请阅读已安装包的导出/类型(navcat、navcat/blocks、navcat/three)以确认当前名称和字段。下文代码仅示意结构,不作为契约。

流程概览

  1. 提取几何体:使用 navcat/three 的 getPositionsAndIndices(meshes) 将可行走的 Three.js 网格(地板、地形、障碍物)转换为 positions/indices。
  2. 生成导航网格:一次调用,使用 navcat/blocks 的 generateSoloNavMesh(input, options) 生成单个区域(默认),或使用 generateTiledNavMesh 处理大世界和部分重建。
  3. 查询:在生成的导航网格上查询路径、最近可行走点、随机点、视线。
  4. 移动智能体:每帧自行跟随路径,或将多个智能体交给 crowd 模块。
import { findPath, DEFAULT_QUERY_FILTER } from 'navcat'
import { generateSoloNavMesh } from 'navcat/blocks'
import { getPositionsAndIndices, createNavMeshHelper } from 'navcat/three'

const [positions, indices] = getPositionsAndIndices([floor, ...obstacles])
const { navMesh } = generateSoloNavMesh({ positions, indices }, options)

scene.add(createNavMeshHelper(navMesh).object)

const result = findPath(navMesh, start, end, halfExtents, DEFAULT_QUERY_FILTER)
const waypoints = result.path.map((p) => p.position)

halfExtents 是用于将起点/终点吸附到网格上的搜索盒;如果查询失败,你的点很可能不在导航网格上,可加宽搜索盒或先用最近多边形查询吸附。

调优生成参数

生成选项决定导航网格如何适配智能体,并在细节与速度之间权衡。无需记忆字段列表(可从已安装的 SoloNavMeshOptions 读取),但需理解几个关键项:

  • 智能体尺寸:可行走半径(与墙壁保持的间隙)、高度(排除低天花板)、攀爬(最大可上台阶高度)、最大可行走坡度角。根据角色设置。
  • 分辨率:单元尺寸/高度(体素网格),越小越精细但越慢。常见起点是单元尺寸≈智能体半径/3。
  • 简化:区域/边缘/误差限制控制多边形输出的块状或平滑程度。

要自定义单个生成阶段(标记区域、注入区域),navcat 暴露了一次性生成器所基于的底层 recast 风格步骤;仅在生成器无法表达需求时使用。

查询导航网格

所有查询都接受导航网格和查询过滤器(除非标记区域成本/标志,否则使用 DEFAULT_QUERY_FILTER)。可导向的能力包括:

  • findPath:两点之间的完整路径,以路径点形式返回。findSmoothPath 用于沿表面的无拐角路径。(对于缓存/动态移动,节点路径+直线路径组合提供更细粒度控制。)
  • 最近可行走点:将世界坐标吸附到网格上;是判断“是否可达”和修复失败查询的基础。
  • 随机可行走点(任意位置或中心半径内):用于生成、巡逻目的地、游荡目标。
  • 沿表面的 raycast:两点在网格上的视线。注意未命中约定:畅通射线报告其命中参数为包的“无墙”哨兵值(最大值,而非 1.0 或 0),请在已安装类型中确认,不要假设。
  • moveAlongSurface:在保持可行走区域的同时将位置滑向目标;无需完整重寻路的简单控制器。
  • 越野连接:跨网格无法处理的缺口(跳跃、梯子、传送)的显式链接。

每帧跟随路径

findPath 给出路径点;移动智能体是循环的职责。走向当前路径点,到达后前进,目的地变化或智能体偏离时重新寻路:

let waypoints = result.path.map((p) => p.position)
let i = 0

function updateAgent(pos, speed, delta) {
  if (i >= waypoints.length) return
  const t = waypoints[i]
  const dx = t[0] - pos[0], dz = t[2] - pos[2]
  const dist = Math.hypot(dx, dz)
  if (dist < 0.2) { i++; return }
  pos[0] += (dx / dist) * speed * delta
  pos[2] += (dz / dist) * speed * delta
}

多智能体 → crowd 模块

对于群体(敌人蜂拥、单位一起移动),使用 navcat/blocks 中的 crowd API,而不是手动跟随路径——它为你处理帧分布式寻路、智能体间和墙壁避让以及间距。避免人群挤成一个重叠团块:

  • 给每个智能体匹配其身体的半径,让避让维持间距。不要每帧手动将每个智能体的速度直接设向同一点——这会覆盖避让并导致堆叠。
  • 要蜂拥目标,给每个智能体一个围绕目标的环形偏移目标(按索引/角度分布),使它们包围目标而不是争抢中心。
  • 调整避让强度和最大加速度,使智能体相互滑过而不是抖动或相互穿透。

对于高级需求,将 crowd 模块复制到项目中并修改。

限制

  • 导航网格是静态的,反映生成时的几何体。当可行走几何体变化(门打开、地形变形)时,必须重新生成——generateSoloNavMesh 重建整个区域;分块导航网格只重建受影响的分块。对于少量移动障碍物,在其上自行做局部转向/避让通常比不断重建更便宜。
  • 约定:navcat 遵循 OpenGL 约定(右手系,逆时针绕序)。如果你的数据不同,请在输入输出时变换坐标。导入的外部导航网格必须在相邻多边形之间共享/索引顶点。
  • 保持碰撞和导航网格对齐到相同形状的地形——不要在雕刻地面下放平坦地板,否则智能体会穿过可见的山丘寻路。
  • 导航网格是纯 JSON——可将生成的导航网格序列化,以在加载时跳过重新生成。

适用场景

  • 敌人绕障寻路、NPC 巡逻、单位命令移动、群体避让与包围。
  • 需要在 Three.js 场景中根据地形和障碍物动态生成可行走区域。

限制与注意事项

  • 静态导航网格需要在地形变化时重建;移动障碍物建议用局部转向补充。
  • API 随版本变化,调用前必须确认已安装包的类型。
  • 坐标约定需与 OpenGL 一致,外部网格需共享顶点索引。
  • 不适用于简单开阔地面的直接转向场景。
  • 未提供具体收费、价格或平台信息。