Ray

概览

字段	值
Kind	Data · 数据 Data
Realm	common

Ray 是一个由起点和方向向量构成的几何数据结构，用来描述从起点沿给定方向延伸的一条射线。它提供 ClosestPoint 与 Distance 两个计算接口，可求出任意空间点在射线上的最近点以及该点到射线的距离；Unit 属性则给出方向向量归一化后的射线形式。

适用场景

适用于需要判断空间点相对一条射线位置的场合，例如计算某个目标点到射线方向的偏移距离，或求出目标点在射线上的最近点以辅助吸附、朝向判断等几何运算。

使用要点

先用起点和方向两个 Vector3 调用 Ray.New(起点, 方向)，或使用等价简写 Ray(起点, 方向) 构造射线。构造后可通过 Origin 与 Direction 读取射线定义，也可读取 Unit 获取方向归一化后的射线实例。对目标点调用 ray:ClosestPoint(point) 得到射线上的最近点，调用 ray:Distance(point) 得到该点到射线的距离。若要进行物理检测，需要把 ray.Origin 与 ray.Direction 分别传给 PhysicsService:Raycast，而不是整体传入 Ray 实例。

注意事项

Ray 是用于最近点和距离计算的几何数据结构。PhysicsService:Raycast 不直接接收 Ray 实例，而是分别接收 origin、direction 和可选 RaycastParams；需要执行物理检测时，应传入 ray.Origin 与 ray.Direction。

代码示例

Ray 射线构造与最近点/距离计算

-- @runtime client
-- Ray 表示一条带起点与方向的射线，常用于计算空间点到射线的最短距离
local origin = Vector3.New(0, 5, 0)      -- 射线起点：悬空 5 个单位处
local direction = Vector3.New(0, -1, 0)  -- 射线方向：竖直向下
local ray = Ray.New(origin, direction)   -- 构造 Ray 实例，供后续几何计算复用

-- 读取 Ray 的公开属性，确认起点与方向已正确写入
print("起点:", ray.Origin.x, ray.Origin.y, ray.Origin.z)
print("方向:", ray.Direction.x, ray.Direction.y, ray.Direction.z)

-- 计算空间某点到射线的最近点：相当于把该点垂直投影回射线上
local probe = Vector3.New(3, 0, 4)
local closest = ray:ClosestPoint(probe)
print("最近点:", closest.x, closest.y, closest.z)

-- 计算点到射线的垂直距离，可用于判断物体是否偏离射线路径
local distance = ray:Distance(probe)
print("点到射线距离:", distance)

属性 (3)

Name	类型	默认值	说明
Origin	Vector3	-	射线的起点，类型为 Vector3，与 Direction 一起确定整条射线。该属性可读可写。
Direction	Vector3	-	射线的方向向量，类型为 Vector3，与 Origin 一起确定射线的走向。该属性可读可写。
Unit	Ray	-	方向归一化后的射线，类型为 Ray，其方向向量已被单位化。该属性为只读。

关联类型

• Vector3

函数 (3)

New

签名：New(origin: Vector3, direction: Vector3) -> Ray

Ray 的构造方法，接收起点 origin 与方向 direction 两个 Vector3 参数，返回一个新的 Ray 实例；也可以使用等价简写 Ray(origin, direction) 进行构造。

参数	类型	说明
origin	Vector3	-
direction	Vector3	-

返回值 Ray

示例代码

构造射线

-- @runtime client
local origin = Vector3.New(0, 10, 0)
local direction = Vector3.New(0, -1, 0)  -- 向下
local ray = Ray.New(origin, direction)
print('起点:', tostring(ray.Origin))
print('方向:', tostring(ray.Direction))

ClosestPoint

签名：ClosestPoint(point: Vector3) -> Vector3

Ray 的 ClosestPoint 方法接收一个 Vector3 坐标点，返回射线上距离该点最近的位置，返回值类型同样为 Vector3。也就是说，它把外部传入的点投影到由起点和方向确定的射线上，得到射线上的对应点。

参数	类型	说明
point	Vector3	-

返回值 Vector3

示例代码

获取射线上离目标点最近的位置

-- @runtime client
-- 构造一条起点在原点、沿 X 轴正方向延伸的射线
local origin = Vector3.New(0, 0, 0)
local ray = Ray.New(origin, Vector3.New(10, 0, 0))

-- 目标点在射线正上方，最近点应落在射线上的 (5, 0, 0) 附近
local point = Vector3.New(5, 3, 0)
local closest = ray:ClosestPoint(point)
print("射线上离目标点最近的位置:", closest)

Distance

签名：Distance(point: Vector3) -> Float

Ray 的 Distance 方法接收一个 Vector3 坐标点，返回该点到射线的最短距离，返回值类型为数值（Float）。

参数	类型	说明
point	Vector3	-

返回值 Float

示例代码

计算点到射线的最短距离

-- @runtime client
-- 构造一条起点在原点、沿 X 轴正方向延伸的射线
local ray = Ray.New(Vector3.New(0, 0, 0), Vector3.New(10, 0, 0))

-- 该点位于射线上方，与射线的最短距离为 3
local point = Vector3.New(5, 3, 0)
local distance = ray:Distance(point)
print("点到射线的最短距离:", distance)

-- 换一个正好落在射线上的点，距离应为 0
local onRayPoint = Vector3.New(2, 0, 0)
print("射线上点到射线的距离:", ray:Distance(onRayPoint))