游戏引擎 / 系统课时
让机关只响应一次事件
让机关只响应一次事件
玩家第一次踏入机关区域时,门应当打开且奖励只发一次;再次进出、其他物体误入或脚本重新启用都不应重复结算。本课在 Cocos Creator 3.8 中为触发回调加入目标过滤与一次性状态,并通过日志验证机关只生效一次。
学习目标
- 区分物理触发回调与真正的玩法生效次数。
- 使用状态门闩阻止重复开门和重复发奖。
- 正确管理监听生命周期,并识别跨场景去重的边界。
回调发生多次,不代表机关应当生效多次
onTriggerEnter 表示一对碰撞器开始进入触发关系,不代表“本关仅发生一次”。玩家离开后再进入,会形成新的进入事件;其他碰撞体进入也可能产生回调。如果误订阅多次,还可能出现一个事件对应多个处理函数的问题。
因此,不能只依靠回调名称保证机关只执行一次,也不应仅使用 Collider.once()。因为第一个进入触发区的可能是箱子或 NPC,直接使用 once() 可能提前消耗监听机会。
为机关定义两个状态:待触发和已触发。只有指定玩家的首次进入能将状态从前者改为后者,其余事件全部忽略。目标过滤必须早于状态切换,否则无关物体就可能消耗机关机会。

在场景中准备触发区
使用 Cocos Creator 3.8 创建一个可以进入、离开并再次进入的机关区域。机关触发区和实际的门应使用不同节点,避免开门时把事件脚本一起销毁。
- 创建独立的
MechanismTrigger节点,挂载BoxCollider,勾选 Is Trigger,调整盒体覆盖玩家可进入的范围。 - 玩家碰撞节点挂载
Collider。若使用 PhysX 等非内置物理后端,确保参与检测的一侧具有非静态RigidBody,并检查碰撞分组是否允许检测。 - 创建单独的
Door节点。示例通过停用该节点模拟开门,因此门的可见模型和碰撞体应放在这个节点下。 - 把下面的
OneShotMechanism.ts挂到MechanismTrigger,在检查器中分别绑定玩家实际承载碰撞体的节点与Door。不要把门节点绑定成触发区自身。
这里选择 onTriggerEnter 而不是 onTriggerStay,因为机关只关心开始进入这一刻。onTriggerStay 会在持续接触期间反复触发,不适合作为一次性奖励的直接执行入口。
用状态门闩拦截重复回调
activated 是机关当前实例的状态开关。代码在执行开门动作之前将它置为 true,防止后续回调重复执行。组件启用时订阅事件,停用时移除事件,避免重复绑定或产生无效监听。
import { _decorator, Collider, Component, ITriggerEvent, Node } from 'cc';
const { ccclass, property } = _decorator;
@ccclass('OneShotMechanism')
export class OneShotMechanism extends Component {
@property({ type: Node })
playerColliderNode: Node | null = null;
@property({ type: Node })
doorNode: Node | null = null;
private activated = false;
private trigger: Collider | null = null;
protected onEnable(): void {
this.trigger = this.getComponent(Collider);
if (!this.trigger) {
console.warn('机关缺少 Collider');
return;
}
this.trigger.on('onTriggerEnter', this.onTriggerEnter, this);
}
protected onDisable(): void {
// 只清理自己注册的回调,避免影响其他组件。
this.trigger?.off('onTriggerEnter', this.onTriggerEnter, this);
this.trigger = null;
}
private onTriggerEnter(event: ITriggerEvent): void {
// 先筛选玩家,再检查机关是否已消耗。
if (!this.playerColliderNode ||
event.otherCollider.node !== this.playerColliderNode ||
this.activated) return;
this.activated = true; // 先锁定状态,后执行副作用。
if (this.doorNode) this.doorNode.active = false;
console.log('机关生效次数:1');
}
}预期输出:玩家第一次进入时,控制台仅出现一次以下日志,门节点停用;离开再进入不会追加同一日志。
机关生效次数:1这里的日志表示机关生效一次,不代表真实奖励已经发放。doorNode.active = false 是最简单的开门演示,适合没有动画需求的测试场景。正式项目可以将这一行替换为播放开门动画、切换碰撞状态或向玩法系统发送机关激活事件。
关键在于执行顺序:先判断碰撞对象,再判断是否已激活,最后修改状态并执行动作。即使后续有多条进入事件到达,也只能观察到已激活状态,无法再次进入执行分支。
验证重入与生命周期边界
完成脚本挂载后,依次测试以下情况:
- 让箱子或其他非玩家碰撞体进入触发区,门应保持关闭,控制台不出现机关生效日志。
- 让玩家首次进入触发区,门应打开,控制台出现一条生效日志。
- 让玩家反复离开、重新进入,控制台仍然只有一条日志。
- 禁用再启用
OneShotMechanism组件,已经激活的状态仍应保留,本次实例不应重新生效。
如果完全没有事件,优先检查 Is Trigger、碰撞分组、刚体类型以及玩家节点引用是否与 event.otherCollider.node 一致。若玩家的碰撞体在子节点上,而检查器绑定了父级 PlayerRoot,直接比较节点会失败;应绑定实际碰撞节点,或另行实现明确的角色身份识别。
当前 activated 仅保存在这个组件实例中。销毁机关并重新创建,状态将回到初始值。如果设计要求重新开局后重置机关,应由关卡重置逻辑显式恢复状态;如果要求存档恢复后仍保持已激活,则需要保存机关的唯一标识和激活状态。
对于联网奖励,客户端状态只能用于阻止重复表现,不能作为最终发奖依据。权威服务还应依据机关 ID、玩家 ID 和领取记录进行幂等校验,避免重复请求、断线重试或重新登录造成重复发奖。