同步路径查找：FindPathToLocationSynchronously

函数功能概述

UNavigationSystemV1::FindPathToLocationSynchronously 是一个同步路径查找函数，用于在两个位置之间计算导航路径。它会在当前帧立即执行路径计算并返回结果。

参数详解

1. WorldContextObject (世界上下文对象)

• 类型: UObject*
• 作用: 提供当前世界的上下文信息，用于获取正确的World对象

2. PathStart (路径起点)

• 类型: const FVector&
• 作用: 路径计算的起始位置（世界坐标）

3. PathEnd (路径终点)

• 类型: const FVector&
• 作用: 路径计算的目标位置（世界坐标）

4. PathfindingContext (路径查找上下文)

• 类型: AActor*
• 作用: 提供路径查找的上下文信息，如：
  • 导航代理的大小和属性
  • 影响路径计算的Actor信息
  • 如果为nullptr，使用默认的导航代理设置

5. FilterClass (过滤器类)

• 类型: TSubclassOf<UNavigationQueryFilter>
• 作用: 自定义导航查询过滤器，用于：
  • 定义哪些区域可以通行
  • 设置不同区域的成本权重
  • 实现复杂的导航约束

返回值

• 类型: UNavigationPath*
• 作用: 返回计算出的导航路径对象，包含：
  • 路径点序列
  • 路径长度信息
  • 路径状态（有效/无效）

工作流程

1. 验证输入: 检查起点和终点是否有效
2. 投影到导航网格: 将3D坐标投影到最近的导航网格表面
3. 路径计算: 使用A*算法或其他路径查找算法
4. 路径优化: 对计算出的路径进行平滑和优化
5. 返回结果: 返回包含路径点的UNavigationPath对象

使用场景示例

// 在角色类中使用
void AMyCharacter::MoveToLocation(const FVector& TargetLocation)
{
    // 同步计算路径
    UNavigationPath* Path = UNavigationSystemV1::FindPathToLocationSynchronously(
        this,                    // WorldContextObject
        GetActorLocation(),      // PathStart
        TargetLocation,          // PathEnd
        this,                    // PathfindingContext (使用角色自身)
        nullptr                  // FilterClass (使用默认过滤器)
    );
    
    if (Path && Path->IsValid())
    {
        // 路径有效，开始移动
        FollowPath(Path->PathPoints);
    }
}

重要特性

1. 同步执行

• 在当前帧立即完成计算
• 阻塞当前线程直到计算完成
• 适用于需要立即结果的场景

2. 线程安全

• 可以在游戏线程中安全调用
• 内部处理了必要的同步机制

3. 导航网格依赖

• 依赖于预先构建的导航网格
• 如果位置不在导航网格上，会自动投影到最近的可导航点

替代方案

如果需要异步路径查找，可以使用：

• FindPathToLocationSynchronously 的异步版本
• AI移动组件的内置路径查找功能

这个函数是Unreal Engine AI和移动系统的基石，广泛应用于角色移动、AI寻路、自动导航等场景。