OverlapParams

概览

字段	值
Kind	Data · 数据 Data
Realm	common

OverlapParams 是空间重叠查询所用的过滤参数对象，配合 PhysicsService 的 GetPartBoundsInBox、GetPartBoundsInRadius 与 GetPartsInPart 使用。它通过 FilterType 与 FilterDescendantsInstances 决定包含还是排除指定 Unit，通过 CollisionGroup 按碰撞组筛选，并用 MaxParts 限制返回数量。

适用场景

常用于以盒体或球体范围做命中检测、拾取判定与范围效果结算，例如先构造一份过滤参数，再查询范围内的单位并逐一处理。

使用要点

先用 OverlapParams.New() 构造实例（也可使用等价简写 OverlapParams()），随后按需设置 FilterType、FilterDescendantsInstances、CollisionGroup 与 MaxParts，最后把该对象作为参数传入 PhysicsService 的 GetPartBoundsInBox、GetPartBoundsInRadius 或 GetPartsInPart 取得结果列表。

注意事项

OverlapParams 是 PhysicsService 空间重叠查询的过滤参数。使用时先用 OverlapParams.New() 构造，再按需设置 FilterType、FilterDescendantsInstances、CollisionGroup、MaxParts；FilterType 使用 Enums.RaycastFilterType.Include/Exclude。CollisionGroup 是用于按已配置碰撞关系过滤的组名，不是只按 WorldUnit.CollisionGroup 字符串同名匹配；最终结果同时受目标 WorldUnit.CollisionGroup、碰撞关系配置和实例过滤影响。不设置（nil，Meta 默认值）表示不启用碰撞组过滤。

代码示例

创建 OverlapParams 并传入空间查询

-- @runtime client
local PhysicsService = game:GetService('PhysicsService')
local World = game:GetService('World')
local targetUnit = World:CreateUnit('WorldUnit', { Position = Vector3.New(0, 0, 0) })
local params = OverlapParams.New()
params.FilterType = Enums.RaycastFilterType.Include
params.FilterDescendantsInstances = { targetUnit }
params.MaxParts = 10
local units = PhysicsService:GetPartBoundsInRadius(Vector3.New(0, 0, 0), 20, params)
print('命中数量:', #units)
targetUnit:Destroy()

属性 (4)

Name	类型	默认值	说明
FilterType	Int	Enums.RaycastFilterType.Exclude	过滤模式：Exclude 排除列表中的实例，Include 仅检测列表中的实例。
FilterDescendantsInstances	Array<Unit>	[]	FilterDescendantsInstances 是 OverlapParams 提供的过滤 Unit 列表属性，类型为数组，默认为空数组，可读写。它用于在空间查询中指定需要参与或排除的 Unit 集合，具体是包含还是排除由同一个 OverlapParams 实例的 FilterType 属性决定，常与 PhysicsService 的 GetPartBoundsInBox、GetPartBoundsInRadius、GetPartsInPart 等查询接口配合使用。
CollisionGroup	String	-	用于按已配置碰撞关系过滤的碰撞组名称，不是只按 WorldUnit.CollisionGroup 字符串同名匹配；不设置（nil，Meta 默认值）表示不启用碰撞组过滤。
MaxParts	Int	0	限制区域查询返回的最大实例数量。

函数 (1)

New

签名：New() -> OverlapParams

创建空间重叠查询过滤参数，供 GetPartBoundsInBox、GetPartBoundsInRadius 和 GetPartsInPart 使用；射线与形状投射应使用 RaycastParams。

返回值 OverlapParams

示例代码

构造重叠查询过滤参数

-- @runtime client
local params = OverlapParams.New()
params.FilterType = Enums.RaycastFilterType.Exclude
params.FilterDescendantsInstances = {}
params.MaxParts = 10
-- 仅在项目已配置相应碰撞组关系时再设置 CollisionGroup
print("OverlapParams 构造完成，MaxParts =", params.MaxParts)