RaycastParams

概览

字段	值
Kind	Data · 数据 Data
Realm	common

RaycastParams 用于封装 PhysicsService 各物理检测函数的过滤条件，通过 FilterType 与 FilterDescendantsInstances 决定检测时包含或排除哪些 Unit，并可用 CollisionGroup 与 TargetCollisionGroupList 按碰撞组进一步筛选。它把过滤规则从单次检测调用中抽离成可复用的数据对象，让射线、球体、方块与形状检测能针对不同目标切换策略。

适用场景

常用于地面探测、视线判断或点击选中这类需要排除自身角色、只针对特定 Unit 的物理查询，例如向下发射射线时排除测试箱体、仅保留地面。

使用要点

先调用 RaycastParams.New() 得到过滤参数对象，再把 FilterType 设为 Enums.RaycastFilterType.Exclude 或 Enums.RaycastFilterType.Include，并用 FilterDescendantsInstances 填入参与筛选的 Unit 列表；如需按碰撞组筛选，可继续设置 CollisionGroup 或 TargetCollisionGroupList。最后把该对象作为第三个参数传给 PhysicsService:Raycast、Blockcast、Spherecast 或 Shapecast，同一份参数可在多次检测中复用。

注意事项

RaycastParams 是 PhysicsService:Raycast/Blockcast/Spherecast/Shapecast 的可选过滤参数；需要过滤时先用 RaycastParams.New() 构造，再设置 FilterType、FilterDescendantsInstances、CollisionGroup。FilterType 建议使用 Enums.RaycastFilterType.Include/Exclude。CollisionGroup 是用于按已配置碰撞关系过滤的组名，不是只按 WorldUnit.CollisionGroup 字符串同名匹配；最终结果同时受目标 WorldUnit.CollisionGroup、碰撞关系配置和实例过滤影响。不设置（nil，Meta 默认值）表示不启用碰撞组过滤。

代码示例

创建 RaycastParams 并传入 PhysicsService:Raycast

-- @runtime client
local PhysicsService = game:GetService("PhysicsService")

local params = RaycastParams.New()
params.FilterType = Enums.RaycastFilterType.Exclude
-- 如需忽略某些单位，将已存在的 Unit 实例放入数组；空数组表示不排除特定单位
params.FilterDescendantsInstances = {}
-- CollisionGroup 默认是 nil；仅在已配置碰撞组关系时再设置组名

-- direction 的长度就是最大检测距离
local origin = Vector3.New(0, 5, 0)
local direction = Vector3.New(0, -100, 0)
local result = PhysicsService:Raycast(origin, direction, params)
if result ~= nil then
    print("命中位置:", result.Position)
end

属性 (4)

Name	类型	默认值	说明
FilterType	Int	Enums.RaycastFilterType.Exclude	过滤模式：Exclude 排除列表中的实例，Include 仅检测列表中的实例。
FilterDescendantsInstances	Array<Unit>	[]	过滤的 Unit 列表，类型为数组，保存参与过滤判断的 Unit 集合。该属性可读写，默认值为空数组。
CollisionGroup	String	-	用于按已配置碰撞关系过滤的碰撞组名称，不是只按 WorldUnit.CollisionGroup 字符串同名匹配；不设置（nil，Meta 默认值）表示不启用碰撞组过滤。
TargetCollisionGroupList	Array<String>	[]	RaycastParams 的目标碰撞组列表属性，类型为 Array，默认值为空表，且可编辑。该属性用于在射线检测中指明所关注的目标碰撞组列表，是 RaycastParams 多项筛选配置之一。

函数 (1)

New

签名：New() -> RaycastParams

创建新的 RaycastParams 参数实例，用于配置射线检测的过滤条件。

返回值 RaycastParams

示例代码

调用 RaycastParams.New 的示例。

-- @runtime client
local result = RaycastParams.New()  -- 返回 RaycastParams
if result ~= nil then
    print("调用成功，结果: " .. tostring(result))
end