PathHitInfo

概览

字段	值
Kind	Data · 数据 Data
Realm	common

PathHitInfo 描述一次导航网格射线检测的命中结果，包含射线起点 StartPosition、终点 EndPosition、是否命中 IsHit，以及命中点在射线上的插值参数 HitT 和命中的世界坐标 HitPosition。它把“是否挡住去路”与“挡在何处”打包成一个结果对象，便于在寻路或落点判断时一次性读取。

适用场景

在寻路流程中判断两个路径点之间是否会穿透导航网格、或需要求出精确的命中位置时，先执行导航网格射线检测，再依据结果的 IsHit 与 HitPosition 决定后续路径点或落点。

使用要点

通过 Path:Raycast(startPosition, endPosition) 获取 PathHitInfo；第二个参数是射线终点坐标，不是方向向量。读取 IsHit 后，仅在命中时使用 HitPosition 和 HitT。

注意事项

不允许使用 PathHitInfo.New() 或 PathHitInfo() 构造实例，必须由公开 API 返回。未命中时 HitPosition 为 nil，HitT 也不具备有效含义，使用前应先检查 IsHit。StartPosition 与 EndPosition 反映的是发起射线检测时的起止位置，不会随命中结果改变。

代码示例

从导航网格射线检测结果读取命中信息

-- @runtime client
local path = game:GetService('PathfindingService'):CreatePath({})
local startPosition = Vector3.New(0, 2, 0)
local endPosition = Vector3.New(20, 2, 0)
local hit = path:Raycast(startPosition, endPosition)
if hit.IsHit then
    print('命中位置和插值参数:', hit.HitPosition, hit.HitT)
end
path:Destroy()

属性 (5)

Name	类型	默认值	说明
StartPosition	Vector3	-	PathHitInfo 的 StartPosition 属性，类型为 Vector3，表示本次路径射线检测所用射线的起点坐标。它与终点 EndPosition、命中位置 HitPosition 一起，构成一次射线检测的完整空间信息。
EndPosition	Vector3	-	PathHitInfo 的 EndPosition 属性，类型为 Vector3，表示本次路径射线检测所用射线的终点坐标。它记录的是射线检测在终点一侧的输入位置，与 StartPosition、HitPosition 共同刻画一次检测的空间关系。
IsHit	Bool	-	指示射线是否与导航网格发生碰撞。
HitT	Float	-	碰撞点在射线上的插值参数，范围 0 到 1，表示从起点到终点的比例。
HitPosition	Vector3	-	射线与导航网格相交位置的世界坐标；未命中时为 nil。

关联类型

• Vector3