TriggerUnit

触发区域单位，用于在场景中圈定一块可感知其他单位进入与离开的区域，并在单位通过时对外抛出触发事件。它支持通过碰撞组白名单或指定单位黑名单两种方式精确筛选触发对象，同时提供空间变换、缩放、物理网格、预览模型、物理开关与碰撞组等配置属性。

概览

触发区域单位，用于在场景中圈定一块可感知其他单位进入与离开的区域，并在单位通过时对外抛出触发事件。它支持通过碰撞组白名单或指定单位黑名单两种方式精确筛选触发对象，同时提供空间变换、缩放、物理网格、预览模型、物理开关与碰撞组等配置属性。

继承自 BasePart；可通过 World:CreateUnit("TriggerUnit", ...) 创建；返回单个单位

函数

AddCollisionWithGroup

签名：AddCollisionWithGroup(groupName: String)

把指定碰撞组加入当前触发器的允许触发白名单。

注意： 当前 Editor Surface 不公开 PhysicsService 或其它已验证的碰撞组注册来源；调用时 groupName 必须使用项目中已经存在的碰撞组名称，因此不提供会臆造组名的自动示例。

参数	类型	说明
groupName	String	碰撞组名

RemoveCollisionWithGroup

签名：RemoveCollisionWithGroup(groupName: String)

从当前触发器的允许触发白名单中移除指定碰撞组。

注意： 当前 Editor Surface 不公开 PhysicsService 或其它已验证的碰撞组查询来源；调用时 groupName 必须使用项目中已经存在的碰撞组名称，因此不提供会臆造组名的自动示例。

参数	类型	说明
groupName	String	碰撞组名

GetCollisionWithGroups

签名：GetCollisionWithGroups() -> Array

获取当前触发器允许触发的碰撞组名称列表。

注意： 该方法返回当前单位所属的碰撞组名称。当前 Editor Surface 不公开碰撞组注册服务，暂不把它与不存在的 PhysicsService 获取链组合成示例。

返回值 Array

AddNoCollisionPairWithUnit

签名：AddNoCollisionPairWithUnit(targetUnit: SpaceUnit)

添加不碰撞单位对，将指定的 SpaceUnit 登记为本 TriggerUnit 的不碰撞单位，参数 targetUnit 为要登记的单位对象。

注意： targetUnit 必须是已有的 SpaceUnit；实际项目中取得目标单位后再登记排除关系。

参数	类型	说明
targetUnit	SpaceUnit	目标单位

排除指定单位触发

-- @runtime client
local world = game:GetService('World')
local trigger = world:CreateUnit('TriggerUnit', {})
local target = world:CreateUnit('WorldUnit', {})
if trigger == nil or target == nil then return end
trigger:AddNoCollisionPairWithUnit(target)
target:Destroy()
trigger:Destroy()

RemoveNoCollisionPairWithUnit

签名：RemoveNoCollisionPairWithUnit(targetUnit: SpaceUnit)

移除不碰撞单位对，将指定的 SpaceUnit 从本 TriggerUnit 的不碰撞单位中解除登记，参数 targetUnit 为要解除的单位对象。

注意： 传入先前登记的同一个 SpaceUnit，解除其排除关系。

参数	类型	说明
targetUnit	SpaceUnit	目标单位

恢复指定单位触发

-- @runtime client
local world = game:GetService('World')
local trigger = world:CreateUnit('TriggerUnit', {})
local target = world:CreateUnit('WorldUnit', {})
if trigger == nil or target == nil then return end
trigger:AddNoCollisionPairWithUnit(target)
trigger:RemoveNoCollisionPairWithUnit(target)
target:Destroy()
trigger:Destroy()

RemoveAllNoCollisionPairWithUnit

签名：RemoveAllNoCollisionPairWithUnit()

移除 TriggerUnit 的所有不碰撞单位对，恢复与所有单位的正常碰撞。

清空所有排除配对

-- @runtime client
local world = game:GetService('World')
local trigger = world:CreateUnit('TriggerUnit', {})
local target = world:CreateUnit('WorldUnit', {})
if trigger == nil or target == nil then return end
trigger:AddNoCollisionPairWithUnit(target)
print('清空前:', #trigger:GetNoCollisionPairUnitList())
trigger:RemoveAllNoCollisionPairWithUnit()
print('清空后:', #trigger:GetNoCollisionPairUnitList())
target:Destroy()
trigger:Destroy()

GetNoCollisionPairUnitList

签名：GetNoCollisionPairUnitList() -> Array

获取不碰撞单位列表，返回当前已登记为本 TriggerUnit 不碰撞单位的 SpaceUnit 数组。

注意： 返回当前已登记的不碰撞 SpaceUnit 列表；先按项目实际对象建立配对，再读取列表。

返回值 Array

读取排除配对列表

-- @runtime client
local world = game:GetService('World')
local trigger = world:CreateUnit('TriggerUnit', {})
local target = world:CreateUnit('WorldUnit', {})
if trigger == nil or target == nil then return end
trigger:AddNoCollisionPairWithUnit(target)
for _, unit in ipairs(trigger:GetNoCollisionPairUnitList()) do
    print(unit.Name)
end
target:Destroy()
trigger:Destroy()

属性

名称	类型	默认值	说明
CFrame	CFrame	[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]	TriggerUnit 的空间变换属性，类型为 CFrame，用于描述该触发器单位在世界中的位置与朝向。该属性为公开属性，代码中可直接读取其取值。
Scale	Vector3	[1.0, 1.0, 1.0]	TriggerUnit 的缩放比例。
PhysicsMeshId	String	official://mesh/59268	TriggerUnit 的物理资源标识属性，类型为 String，用于指定该触发器单位所使用的物理网格资源，属于可编辑属性。
DisplayModelId	String	official://mesh/59268	TriggerUnit 在编辑器中显示的预览模型资源 ID。
PhysicsActive	Bool	true	是否启用物理模拟，关闭后物体不参与碰撞和物理计算
ModelBindParent	Bool	false	启用后，当父节点为 WorldUnit、RenderUnit、TriggerUnit、PhysicsUnit 等支持父子带动的场景单位时，当前单位将整体跟随父节点运动，保持与父节点的相对位置和旋转。运行时可通过脚本设置 .ModelBindParent = true/false 动态切换该行为。
CollisionGroup	String	""	TriggerUnit 所属的碰撞组名称。
CanTouch	Bool	true	其他物体碰到此物体时，是否触发此物体的碰撞事件

事件

OnTriggerEnter

签名：OnTriggerEnter(otherUnit: Unit)

参数	类型	说明
otherUnit	Unit

OnTriggerExit

签名：OnTriggerExit(otherUnit: Unit)

参数	类型	说明
otherUnit	Unit

OnLocalTriggerEnter

签名：OnLocalTriggerEnter(info: TriggerCallbackInfo)

当其他单位进入本触发区域时在本地触发，回调参数为 TriggerCallbackInfo

参数	类型	说明
info	TriggerCallbackInfo	触发回调信息

OnLocalTriggerExit

签名：OnLocalTriggerExit(info: TriggerCallbackInfo)

当其他单位离开本触发区域时在本地触发；若其他单位在离开前被销毁，也会补发该事件。回调参数为 TriggerCallbackInfo

参数	类型	说明
info	TriggerCallbackInfo	触发回调信息