PathWaypoint

概览

字段	值
Kind	Data · 数据 Data
Realm	common

PathWaypoint 表示寻路结果中的单个途经路点，记录该点的世界坐标位置、到达时需要执行的动作类型以及可选的自定义标签。它通常成组出现，构成一条完整的移动路径，供角色或单位按顺序行进。

适用场景

当单位需要沿计算出的路径移动时，遍历路点列表并依据每个路点的动作决定继续行走还是跳跃，从而驱动移动逻辑。

使用要点

先通过 PathfindingService:CreatePath 创建路径，调用 path:ComputeAsync(startPosition, destination) 传入起点和终点；成功后用 path:GetWaypoints() 获取路点数组。

注意事项

路点实例不可自行构造，PathWaypoint.New(...) 与 PathWaypoint(...) 均不可用，只能通过公开寻路 API 的返回值获取。比较 Action 时必须使用 Enums.PathWaypointAction 中的枚举项，不要使用数字。Position 为 Vector3，可直接参与位置计算或与单位当前位置进行比较。

代码示例

从成功计算的路径中读取路点

-- @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, waypoint.Action, waypoint.Label)
    end
end
path:Destroy()

属性 (3)

Name	类型	默认值	说明
Position	Vector3	-	PathWaypoint 的 Position 属性，类型为 Vector3，表示该路点在场景世界坐标系中的位置。该属性公开且可编辑，既可读取当前路点坐标，也可对它重新赋值以调整路点位置。
Action	PathWaypointAction	-	到达该路点时执行的动作类型，决定角色在该点的行为。
Label	String	-	路点的自定义标签，用于标识或分类路点。

关联类型

• PathWaypointAction
• Vector3