RaycastResult

概览

字段	值
Kind	Data · 数据 Data
Realm	common

射线检测结果类型，承载 PhysicsService 各投射函数命中后返回的判定信息，可读取命中对象、命中点、命中面法线与命中距离。该类型无法自行创建，未命中时投射函数会返回 nil，因此使用前必须先做判空处理再访问其属性。

适用场景

常用于角色落地检测、视线遮挡判断、技能命中判定以及获取表面法线来调整模型贴合方向等需要把投射结果转换为具体数据的场合。

使用要点

先通过 PhysicsService:Raycast、PhysicsService:Blockcast、PhysicsService:Spherecast 或 PhysicsService:Shapecast 发起投射并接收返回值，判断返回值不为 nil 后，再依次读取 result.Instance 确认被命中的 Unit、result.Position 获取命中点坐标、result.Normal 获取命中面朝向、result.Distance 获取命中距离。

注意事项

RaycastResult 不可直接构造，只能由 PhysicsService 的投射函数返回。未命中时投射函数返回 nil，应先判空；结果非 nil 时再读取 Instance、Position、Normal 和 Distance。

代码示例

执行射线检测并读取命中结果

-- @runtime client
local PhysicsService = game:GetService('PhysicsService')
local origin = Vector3.New(0, 5, 0)
local direction = Vector3.New(0, -100, 0)
local result = PhysicsService:Raycast(origin, direction)
if result ~= nil then
    print('命中对象:', result.Instance)
    print('位置、法线和距离:', result.Position, result.Normal, result.Distance)
end

属性 (4)

Name	类型	默认值	说明
Instance	Unit	-	命中的 Unit，表示本次射线检测结果中被击中的 Unit 实例。该属性为 Unit 类型，可通过它继续访问命中对象自身的属性与函数。
Position	Vector3	-	命中点，表示射线与被击中对象相交位置在世界空间中的坐标，类型为 Vector3。
Normal	Vector3	-	命中面法线，表示射线击中位置处表面朝向的法线向量，类型为 Vector3。
Distance	Float	-	射线命中点与射线起点之间的距离，类型为浮点数。

关联类型

• Vector3