Path

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [Path]（1 属性 / 6 函数 / 2 事件）

继承成员

1 个来源 / 4 属性 / 25 函数 / 6 事件

• 来自 Unit（4 属性 / 25 函数 / 6 事件）
  • 属性：AssetId、Name、Desc、Parent
  • 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
  • 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

Path 承载一次寻路计算的结果，对外暴露路径状态与路点序列。它通过 ComputeAsync 计算起点到终点之间的路线，用 GetWaypoints 读取路点，并提供 SamplePosition 采样、Raycast 检测路径沿线是否被遮挡，以及 SetAreaCost、GetAreaCost 调整区域通行代价。当路径的某一段被阻挡或重新畅通时，Blocked 与 Unblocked 事件会携带段索引通知调用方。

适用场景

常用于让角色或单位在场景中自动绕开障碍移动到目标点：先取得路径对象并计算路线，再沿返回的路点逐个驱动移动，并在路径被阻挡时重新计算。也适合对固定路线做代价调整或对某段路径做射线检测的场合。

使用要点

通过 game:GetService("PathfindingService"):CreatePath() 取得 Path 实例，随后调用 path:ComputeAsync(start, dest)，待调用返回后读取 path.Status 判断是否为 Enums.PathStatus.Success，再调用 path:GetWaypoints() 遍历每个路点的 Position 驱动单位移动，也可用 path:SamplePosition 把某点吸附到导航网格上。若需要改变区域代价，可先调用 path:SetAreaCost 并用 path:GetAreaCost 校验，然后重新调用 ComputeAsync；路径不再使用时调用 path:Destroy() 释放。

注意事项

ComputeAsync 当前是同步执行接口，不会挂起协程；仍必须先调用 ComputeAsync(start, dest)，等调用返回后再读取 Status 和 GetWaypoints。直接在 ComputeAsync 之前调用 GetWaypoints 会返回空数组。典型端到端流程：CreatePath → ComputeAsync(start, dest) → 检查 Status 是否为 Success → GetWaypoints 遍历每个 PathWaypoint.Position 驱动单位移动。若 HasNavMesh 为 false 或起终点不在导航网格上，Status 会返回失败且 GetWaypoints 为空。Path 不再使用时必须显式调用 Destroy() 释放。

代码示例

计算路径并读取路点

-- @runtime client
local pathfindingService = game:GetService("PathfindingService")
local path = pathfindingService:CreatePath({})
local startPos = Vector3.New(0, 0, 0)
local destPos = Vector3.New(20, 0, 20)

path:ComputeAsync(startPos, destPos)
if path.Status == Enums.PathStatus.Success then
    for index, waypoint in ipairs(path:GetWaypoints()) do
        print("路点", index, waypoint.Position)
    end
else
    print("寻路失败，状态:", path.Status)
end
path:Destroy()

属性 (1)

Name	类型	默认值	说明
Status	PathStatus	Enums.PathStatus.NoPath	路径计算状态。初始值为 NoPath；ComputeAsync 成功后变为 Success，失败或无可达路径时为 NoPath。

关联类型

• Unit
• PathStatus

事件 (2)

Blocked

签名：Blocked(segmentIndex: Int) 触发：local

当路径上的某个路段被障碍物阻挡时触发。

回调参数	类型	说明
segmentIndex	Int	被阻断的线段索引，1-based。

示例代码

事件示例

-- @runtime client
local function demo(path)
    if path ~= nil then
        path.Blocked:Once(function(segmentIndex)
            print("segmentIndex: " .. tostring(segmentIndex))
        end)
    end
end

Unblocked

签名：Unblocked(segmentIndex: Int) 触发：local

当路径上之前被阻挡的路段恢复通行时触发。

回调参数	类型	说明
segmentIndex	Int	恢复通行的线段索引，1-based。

示例代码

事件示例

-- @runtime client
local function demo(path)
    if path ~= nil then
        path.Unblocked:Once(function(segmentIndex)
            print("segmentIndex: " .. tostring(segmentIndex))
        end)
    end
end

函数 (6)

ComputeAsync

签名：ComputeAsync(start: Vector3, dest: Vector3) -> void

根据起点和终点同步计算导航路径，并更新 Status 与路点列表；调用返回后再读取 GetWaypoints。

⚙ 当前版本直接同步返回，不需要额外包装为协程调用。

参数	类型	说明
start	Vector3	寻路起点的世界坐标。
dest	Vector3	寻路终点的世界坐标。

返回值 void

示例代码

计算路径并检查状态

-- @runtime client
local path = game:GetService('PathfindingService'):CreatePath({})
path:ComputeAsync(Vector3.New(0, 0, 0), Vector3.New(20, 0, 20))
print('寻路状态:', path.Status)
path:Destroy()

GetWaypoints

签名：GetWaypoints() -> Array<PathWaypoint> (PathWaypoint 数组副本。)

获取当前计算出的路径点列表。

返回值 Array<PathWaypoint> (PathWaypoint 数组副本。)

示例代码

计算后遍历路径点

-- @runtime client
local path = game:GetService('PathfindingService'):CreatePath({})
path:ComputeAsync(Vector3.New(0, 0, 0), Vector3.New(20, 0, 20))
if path.Status == Enums.PathStatus.Success then
    for index, waypoint in ipairs(path:GetWaypoints()) do
        print('路点', index, waypoint.Position)
    end
end
path:Destroy()

SamplePosition

签名：SamplePosition(sourcePosition: Vector3, maxDistance: Float, areaMask: Int) -> Vector3 (最近的导航网格坐标；采样失败时返回 nil。)

SamplePosition 是 Path 提供的导航网格采样函数，从给定位置出发，在指定距离与区域掩码条件下寻找距离最近的导航网格坐标，成功时返回一个 Vector3，采样失败时返回 nil。

参数	类型	说明
sourcePosition	Vector3	采样查询的世界坐标。
maxDistance	Float	从源坐标开始搜索的最大半径。
areaMask	Int	用于限制可采样区域的掩码。此参数暂未使用

返回值 Vector3 (最近的导航网格坐标；采样失败时返回 nil。)

示例代码

在导航网格上采样最近位置

-- @runtime client
local path = game:GetService('PathfindingService'):CreatePath({})
local sampled = path:SamplePosition(Vector3.New(0, 2, 0), 10, 0)
if sampled ~= nil then print('采样位置:', sampled) end
path:Destroy()

Raycast

签名：Raycast(startPosition: Vector3, endPosition: Vector3) -> PathHitInfo (导航网格射线检测结果对象。)

Raycast 是 Path 提供的导航网格射线检测函数，接收起点与终点两个 Vector3 坐标，返回一个 PathHitInfo 对象，用于描述这段区间在导航网格上的检测结果。

参数	类型	说明
startPosition	Vector3	射线起点的世界坐标。
endPosition	Vector3	射线终点的世界坐标。

返回值 PathHitInfo (导航网格射线检测结果对象。)

示例代码

执行导航网格射线检测

-- @runtime client
local path = game:GetService('PathfindingService'):CreatePath({})
local hit = path:Raycast(Vector3.New(0, 2, 0), Vector3.New(20, 2, 0))
if hit ~= nil then print('是否命中:', hit.IsHit, '位置:', hit.HitPosition) end
path:Destroy()

SetAreaCost

签名：SetAreaCost(area_index: String, cost: Float) -> void

设置指定区域索引的寻路代价值。

参数	类型	说明
area_index	String	导航区域或 Link/Modifier 的 Label。
cost	Float	该区域的寻路代价值。

返回值 void

示例代码

设置并读取指定区域的寻路代价

-- @runtime client
local path = game:GetService("PathfindingService"):CreatePath({})
local areaIndex = "default"
local cost = 2.0

path:SetAreaCost(areaIndex, cost)
local currentValue = path:GetAreaCost(areaIndex)
print("当前区域代价:", currentValue)
path:Destroy()

GetAreaCost

签名：GetAreaCost(area_index: String) -> Float (区域寻路代价值。)

获取指定区域索引的寻路代价值。

参数	类型	说明
area_index	String	导航区域或 Link/Modifier 的 Label。

返回值 Float (区域寻路代价值。)

示例代码

读取指定区域的寻路代价

-- @runtime client
local path = game:GetService("PathfindingService"):CreatePath({})
local areaIndex = "default"
local currentValue = path:GetAreaCost(areaIndex)
print("当前区域代价:", currentValue)
path:Destroy()