游戏 AI / 系统课时
怎样可视化一条失败路径
怎样可视化一条失败路径
寻路失败时,最有效的做法不是先调参数,而是把“代理在哪里、目标在哪里、NavMesh 能算到哪里、路径在哪一段断掉”同时画出来。本节用 Unity 的 NavMesh.CalculatePath、路径角点和代理状态建立最小调试视图,让“角色不走”变成可观察的证据。
学习目标
- 能把起点、终点、路径角点与失败位置画在 Scene 视图中
- 能结合
pathStatus、isOnNavMesh和采样结果判断失败发生在哪一层 - 能区分完整路径、部分路径与无效路径,并据此决定下一步排查方向
先把失败拆成可见证据
一条“失败路径”至少涉及四类信息:角色当前位置、目标位置、NavMesh 上可落点的位置,以及路径计算结果。只看角色是否移动,会把“目标不在网格上”“只有部分路径”“代理根本没绑定到 NavMesh”等问题混在一起。
调试时可以固定颜色语义:起点为绿色、目标为红色、实际路径为蓝色、采样后的最近可行走点为黄色。这样即使日志很多,也能先从空间关系判断问题在哪。

用一个脚本同时画路径和状态
下面脚本挂到带 NavMeshAgent 的角色上,再把 target 指向场景中的目标对象。它不会替代正常移动逻辑,只负责计算路径、输出关键状态,并在 Scene 视图中画出原始目标、采样目标和路径段。
using UnityEngine;
using UnityEngine.AI;
public class NavPathDebugView : MonoBehaviour
{
[SerializeField] private NavMeshAgent agent;
[SerializeField] private Transform target;
[SerializeField] private float sampleRadius = 2f;
private readonly NavMeshPath path = new NavMeshPath();
private Vector3 sampledTarget;
private bool hasSampledTarget;
private void Reset()
{
agent = GetComponent<NavMeshAgent>();
}
private void Update()
{
if (agent == null || target == null)
{
return;
}
// 先确认目标附近是否真的存在可用的 NavMesh 点。
hasSampledTarget = NavMesh.SamplePosition(
target.position,
out NavMeshHit hit,
sampleRadius,
NavMesh.AllAreas);
if (hasSampledTarget)
{
sampledTarget = hit.position;
}
if (!agent.isOnNavMesh || !hasSampledTarget)
{
return;
}
// 单独计算调试路径,不依赖角色当前是否正在移动。
NavMesh.CalculatePath(
agent.transform.position,
sampledTarget,
NavMesh.AllAreas,
path);
}
private void OnDrawGizmos()
{
if (agent == null || target == null)
{
return;
}
Gizmos.color = Color.green;
Gizmos.DrawSphere(agent.transform.position, 0.15f);
Gizmos.color = Color.red;
Gizmos.DrawSphere(target.position, 0.15f);
if (hasSampledTarget)
{
Gizmos.color = Color.yellow;
Gizmos.DrawSphere(sampledTarget, 0.12f);
Gizmos.DrawLine(target.position, sampledTarget);
}
if (path.corners == null || path.corners.Length < 2)
{
return;
}
Gizmos.color = Color.cyan;
for (int i = 1; i < path.corners.Length; i++)
{
Gizmos.DrawLine(path.corners[i - 1], path.corners[i]);
Gizmos.DrawSphere(path.corners[i], 0.08f);
}
}
[ContextMenu("Print Nav Path State")]
private void PrintState()
{
Debug.Log(
$"isOnNavMesh={agent.isOnNavMesh}, " +
$"pathStatus={path.status}, " +
$"cornerCount={path.corners.Length}, " +
$"targetSampled={hasSampledTarget}");
}
}预期结果:运行后在 Scene 视图中能看到起点、原始目标、采样目标和当前能计算出的路径段。通过组件菜单执行 Print Nav Path State 时,Console 会输出类似下面的状态,实际角点数量取决于场景。
isOnNavMesh=True, pathStatus=PathPartial, cornerCount=<COUNT>, targetSampled=True按路径状态缩小范围
NavMeshPathStatus.PathComplete 表示路径能到达传入的终点。如果角色仍不移动,问题通常已经从“路径查询”转向 NavMeshAgent 的停止状态、速度、位置更新或其他角色控制逻辑冲突。
PathPartial 更有诊断价值:路径存在,但只能到达离目标最近的某个连通区域。此时重点看最后一个 corner 停在哪里,再检查网格是否断开、Area 是否被排除、目标是否隔着无法连接的平台或门。
PathInvalid 表示当前条件下没有得到有效路径。先确认 agent.isOnNavMesh,再看 NavMesh.SamplePosition 是否能在合理半径内找到终点附近的可行走点;不要为了让采样成功而无限放大半径,否则可能把目标吸附到墙另一侧或其他楼层。
用最后一个角点决定下一步
如果路径是部分路径,把最后一个角点当成“断点”最有效。断点靠近窄门,优先检查 Agent Radius 与可通行宽度;断点停在台阶前,检查网格连接和允许跨越的高度;断点停在动态障碍前,则检查障碍是否切断了唯一通路。
如果连第一段路径都没有,优先确认起点是否真的位于当前 NavMesh 数据上,以及运行时是否已经加载对应导航数据。可视化的目的不是把调试画面做得更复杂,而是把失败明确归到起点、终点、路径连通性或代理状态中的某一层,再针对该层继续排查。