用途
本技能用于将 AI/智能体的寻路任务交给 navcat。navcat 根据原始几何体构建导航网格(navmesh,即关卡中互联的可行走多边形),并在其上回答寻路查询。当有对象需要在世界中智能移动时使用它,例如敌人绕过障碍物、NPC 巡逻、单位被命令前往某点、智能体必须避开墙壁和缺口。navcat 与渲染无关;navcat/three 可将其适配到 Three.js。
是否需要导航网格
对于“在开阔平坦地面上直接走向目标”的情况,导航网格属于过度设计,直接转向即可。当智能体必须绕过障碍物、穿越不平坦或多层地形,或作为协调的群体行动时,导航网格才有价值。如果情况更简单,自行实现转向是正确选择。
版本变化与类型确认
本技能负责将你导向正确的功能与决策,不固定精确签名,因为 navcat 的 API(导出名称、选项字段、返回结构)会随版本变化。调用前,请阅读已安装包的导出/类型(navcat、navcat/blocks、navcat/three)以确认当前名称和字段。下文代码仅示意结构,不作为契约。
流程概览
- 提取几何体:使用 navcat/three 的 getPositionsAndIndices(meshes) 将可行走的 Three.js 网格(地板、地形、障碍物)转换为 positions/indices。
- 生成导航网格:一次调用,使用 navcat/blocks 的 generateSoloNavMesh(input, options) 生成单个区域(默认),或使用 generateTiledNavMesh 处理大世界和部分重建。
- 查询:在生成的导航网格上查询路径、最近可行走点、随机点、视线。
- 移动智能体:每帧自行跟随路径,或将多个智能体交给 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 一致,外部网格需共享顶点索引。
- 不适用于简单开阔地面的直接转向场景。
- 未提供具体收费、价格或平台信息。