工坊手册

主题

TriggerUnit ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）

继承成员 ​

3 个来源 / 16 属性 / 43 函数 / 6 事件

TriggerUnit 是用于检测其他单位进入或离开指定区域的触发体，可配置物理网格、缩放、空间变换以及所属碰撞组等属性。它通过碰撞组白名单与具体单位配对黑名单两种方式筛选可触发对象，并在触发发生时以本地事件的形式回调进入与离开信息。CanTouch 决定该触发体能否被其他单位触发，配合 OnTriggerEnter、OnTriggerExit、OnLocalTriggerEnter、OnLocalTriggerExit 可完整掌握区域的进出情况。

适用场景 ​

常用于物品拾取范围、任务区域判定或场景机关的进出检测，例如在物品单位下挂载一个 TriggerUnit 作为拾取范围提示，或在世界中创建触发体后连接事件打印进入的单位。

使用要点 ​

通过 World:CreateUnit("TriggerUnit", config) 创建，并在 config 中为 PhysicsMeshId 传入 String 类型的有效资源 URI，为 Scale、Position 传入 Vector3。随后监听 OnTriggerEnter/OnTriggerExit 或本地对应事件；需要过滤时，使用 AddCollisionWithGroup 添加允许触发的碰撞组，或用 AddNoCollisionPairWithUnit 排除指定 Unit。

注意事项 ​

触发过滤分两类：AddCollisionWithGroup/RemoveCollisionWithGroup 操作碰撞组名称，是允许触发的白名单；AddNoCollisionPairWithUnit/RemoveNoCollisionPairWithUnit 操作具体 Unit 实例，是排除指定单位的黑名单。两类 API 不要混用，碰撞组传字符串，单位配对传 Unit。

代码示例 ​

创建触发区域并监听进入事件 ​

lua
-- @runtime client
local world = game:GetService("World")

local trigger = world:CreateUnit("TriggerUnit", {
    Name = "CheckpointTrigger",
    Position = Vector3.New(0, 5, 0),
    Scale = Vector3.New(3, 2, 1),
    CollisionGroup = "Trigger",
    CanTouch = true,
})
trigger:AddCollisionWithGroup("Player")

trigger.OnTriggerEnter:Once(function(otherUnit)
    print("进入触发区:", otherUnit.Name)
end)

属性 (8) ​

Name类型默认值说明
CFrameCFrame[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0]TriggerUnit 的空间变换属性，类型为 CFrame，用于表示该触发单位的整体位置与朝向（旋转）。读取该属性即可同时获得触发区域的位置和旋转信息。
ScaleVector3[1.0, 1.0, 1.0]TriggerUnit 的缩放属性，类型为 Vector3，描述该触发单位在三个轴向上的缩放系数。
PhysicsMeshIdStringofficial://mesh/59268TriggerUnit 的物理资源标识属性，类型为 String，用于指定该触发器单位所使用的物理网格资源，属于可编辑属性。
DisplayModelIdStringofficial://mesh/59268TriggerUnit 在编辑器中显示的预览模型资源 ID。
PhysicsActiveBooltrue控制 TriggerUnit 的物理模拟是否激活。
ModelBindParentBoolfalse启用后，当父节点为 WorldUnit、RenderUnit、TriggerUnit、PhysicsUnit 等支持父子带动的场景单位时，当前单位将整体跟随父节点运动，保持与父节点的相对位置和旋转。运行时可通过脚本设置 .ModelBindParent = true/false 动态切换该行为。
CollisionGroupString""TriggerUnit 所属的碰撞组名称。
CanTouchBooltrueTriggerUnit 的属性，类型为 Bool，用于控制该触发器的碰撞事件能否被其他单位触发。

关联类型 ​

事件 (4) ​

OnTriggerEnter ​

签名：OnTriggerEnter(otherUnit: Unit) 触发：local

当有单位进入该触发器范围时触发的事件，回调会收到一个参数 otherUnit，即进入触发器的 Unit 实例。

回调参数类型说明
otherUnitUnit-

示例代码

监听进入触发区域

lua
-- @runtime client
local world = game:GetService('World')
local trigger = world:CreateUnit('TriggerUnit', {})
if trigger == nil then return end
trigger.OnTriggerEnter:Once(function(otherUnit)
    print('进入触发区域:', otherUnit)
end)

OnTriggerExit ​

签名：OnTriggerExit(otherUnit: Unit) 触发：local

当有单位离开该触发器范围时触发的事件，回调会收到一个参数 otherUnit，即离开触发器的 Unit 实例。

回调参数类型说明
otherUnitUnit-

示例代码

监听离开触发区域

lua
-- @runtime client
local world = game:GetService('World')
local trigger = world:CreateUnit('TriggerUnit', {})
if trigger == nil then return end
trigger.OnTriggerExit:Once(function(otherUnit)
    print('离开触发区域:', otherUnit)
end)

OnLocalTriggerEnter ​

签名：OnLocalTriggerEnter(info: TriggerCallbackInfo) 触发：local

其他单位进入触发区域时在本地触发；info.OtherUnit 表示进入者，不限定为本地玩家单位。

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

示例代码

监听本地进入触发区域

lua
-- @runtime client
local world = game:GetService('World')
local trigger = world:CreateUnit('TriggerUnit', {})
if trigger == nil then return end
trigger.OnLocalTriggerEnter:Once(function(info)
    print('本地进入信息:', info)
end)

OnLocalTriggerExit ​

签名：OnLocalTriggerExit(info: TriggerCallbackInfo) 触发：local

其他单位离开触发区域时在本地触发；info.OtherUnit 表示离开者，不限定为本地玩家单位。

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

示例代码

监听本地离开触发区域

lua
-- @runtime client
local world = game:GetService('World')
local trigger = world:CreateUnit('TriggerUnit', {})
if trigger == nil then return end
trigger.OnLocalTriggerExit:Once(function(info)
    print('本地离开信息:', info)
end)

函数 (7) ​

AddCollisionWithGroup ​

签名：AddCollisionWithGroup(groupName: String) -> void

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

⚙ 白名单语义：每次调用累加碰撞组到允许列表，而非替换。触发器仅与已添加的碰撞组中的单位发生碰撞交互。

参数类型说明
groupNameString要加入的碰撞组名称

返回值 void

示例代码

允许指定碰撞组触发

lua
-- @runtime client
local World = game:GetService("World")
local trigger = World:CreateUnit("TriggerUnit", { CollisionGroup = "Trigger" })
trigger:AddCollisionWithGroup("Player")
print("允许碰撞组:", table.concat(trigger:GetCollisionWithGroups(), ","))

RemoveCollisionWithGroup ​

签名：RemoveCollisionWithGroup(groupName: String) -> void

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

参数类型说明
groupNameString要移除的碰撞组名称

返回值 void

示例代码

移除允许触发的碰撞组

lua
-- @runtime client
local World = game:GetService("World")
local trigger = World:CreateUnit("TriggerUnit", { CollisionGroup = "Trigger" })
trigger:AddCollisionWithGroup("Player")
trigger:RemoveCollisionWithGroup("Player")

GetCollisionWithGroups ​

签名：GetCollisionWithGroups() -> Array<String>

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

返回值 Array<String>

示例代码

读取当前允许的碰撞组

lua
-- @runtime client
local World = game:GetService("World")
local trigger = World:CreateUnit("TriggerUnit", { CollisionGroup = "Trigger" })
trigger:AddCollisionWithGroup("Player")
for _, groupName in ipairs(trigger:GetCollisionWithGroups()) do
    print("允许碰撞组:", groupName)
end

AddNoCollisionPairWithUnit ​

签名：AddNoCollisionPairWithUnit(targetUnit: SpaceUnit) -> void

为当前 TriggerUnit 添加一个不碰撞单位对，使该触发器与传入的 SpaceUnit 之间不再产生碰撞。

⚙ 黑名单语义：针对具体 Unit 而非碰撞组，加入后该 Unit 不参与碰撞。

参数类型说明
targetUnitSpaceUnit要互不碰撞的目标单位

返回值 void

示例代码

排除指定单位触发

lua
-- @runtime client
local World = game:GetService("World")
local trigger = World:CreateUnit("TriggerUnit", { CollisionGroup = "Trigger" })
local targetUnit = World:CreateUnit("WorldUnit", { Name = "IgnoredTarget" })
trigger:AddNoCollisionPairWithUnit(targetUnit)

RemoveNoCollisionPairWithUnit ​

签名：RemoveNoCollisionPairWithUnit(targetUnit: SpaceUnit) -> void

从当前 TriggerUnit 的不碰撞记录中移除指定的单位对，使该触发器与传入的 SpaceUnit 恢复原有的碰撞关系。

参数类型说明
targetUnitSpaceUnit要恢复碰撞的目标单位

返回值 void

示例代码

恢复指定单位触发

lua
-- @runtime client
local World = game:GetService("World")
local trigger = World:CreateUnit("TriggerUnit", { CollisionGroup = "Trigger" })
local targetUnit = World:CreateUnit("WorldUnit", { Name = "IgnoredTarget" })
trigger:AddNoCollisionPairWithUnit(targetUnit)
trigger:RemoveNoCollisionPairWithUnit(targetUnit)

RemoveAllNoCollisionPairWithUnit ​

签名：RemoveAllNoCollisionPairWithUnit() -> void

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

返回值 void

示例代码

清空所有不碰撞单位配对

lua
-- @runtime client
local World = game:GetService("World")
local trigger = World:CreateUnit("TriggerUnit", { CollisionGroup = "Trigger" })
trigger:RemoveAllNoCollisionPairWithUnit()

GetNoCollisionPairUnitList ​

签名：GetNoCollisionPairUnitList() -> Array&lt;SpaceUnit&gt;

获取当前 TriggerUnit 已记录的全部不碰撞单位，返回一个 SpaceUnit 数组。

返回值 Array<SpaceUnit>

示例代码

读取不碰撞单位列表

lua
-- @runtime client
local World = game:GetService("World")
local trigger = World:CreateUnit("TriggerUnit", { CollisionGroup = "Trigger" })
local targetUnit = World:CreateUnit("WorldUnit", { Name = "IgnoredTarget" })
trigger:AddNoCollisionPairWithUnit(targetUnit)
for _, unit in ipairs(trigger:GetNoCollisionPairUnitList()) do
    print("不触发单位:", unit.Name)
end