游戏引擎 / 系统课时
用触发器检测拾取范围
用触发器检测拾取范围
这一课为场景中的道具增加一个不会阻挡角色的三维检测范围:角色进入时提示可拾取,停留时维持资格,离开后取消资格,只有在范围内按 E 才能真正拾取。这样可以把“靠近道具”和“执行拾取”分开处理。
学习目标
- 区分实体碰撞体与
Is Trigger检测区域。 - 监听进入、停留、离开三个触发事件并管理状态。
- 在拾取前校验目标和范围状态,防止重复领奖。
配置角色与道具的检测范围
触发器仍然是 Collider,区别是勾选 Is Trigger 后只上报重叠关系,不产生把角色弹开的物理阻挡。示例采用一个可移动角色和一个固定道具:
- 给
Player添加RigidBody(DYNAMIC)与CapsuleCollider(关闭Is Trigger);角色应能在场景中移动。 - 创建
PickupItem节点,放入道具模型并添加SphereCollider。把半径设成允许拾取的范围,勾选Is Trigger,不必为固定道具增加刚体。 - 在
PickupItem上挂载PickupRange脚本,检查器中将Player节点拖入player属性。示例要求玩家的CapsuleCollider就挂在该Player节点上。 - 确认碰撞分组与掩码允许两个对象互相检测,运行场景。
在支持动力学的 3D 物理后端中,静态道具触发器与动态角色碰撞体可以产生触发事件;两个只有静态碰撞体的对象通常不会产生这组事件。范围大小以碰撞体形状为准,不以道具模型表面为准。

监听三个触发事件
新建 PickupRange.ts 并挂到 PickupItem。事件参数中的 selfCollider 表示本次事件属于哪个检测体,otherCollider 表示进入或离开它的碰撞体。先比对 Player 节点,避免其他道具或敌人也触发拾取提示。
import {
_decorator, Component, Collider, EventKeyboard,
ITriggerEvent, Input, KeyCode, Node, input
} from 'cc';
const { ccclass, property } = _decorator;
@ccclass('PickupRange')
export class PickupRange extends Component {
@property(Node) player: Node | null = null;
private zone: Collider | null = null;
private inRange = false;
private collected = false;
onEnable() {
this.zone = this.getComponent(Collider);
if (!this.zone || !this.player) {
console.warn('请配置道具触发器与 Player 引用');
return;
}
this.zone.on('onTriggerEnter', this.onEnter, this);
this.zone.on('onTriggerStay', this.onStay, this);
this.zone.on('onTriggerExit', this.onExit, this);
input.on(Input.EventType.KEY_DOWN, this.onKeyDown, this);
}
onDisable() {
this.zone?.off('onTriggerEnter', this.onEnter, this);
this.zone?.off('onTriggerStay', this.onStay, this);
this.zone?.off('onTriggerExit', this.onExit, this);
input.off(Input.EventType.KEY_DOWN, this.onKeyDown, this);
}
private isPlayer(event: ITriggerEvent): boolean {
return event.selfCollider === this.zone &&
event.otherCollider.node === this.player;
}
private onEnter(event: ITriggerEvent) {
if (!this.isPlayer(event) || this.collected) return;
this.inRange = true;
console.log('进入范围:按 E 拾取');
}
private onStay(event: ITriggerEvent) {
// 停留事件可能高频触发:仅保持状态,不重复发奖。
if (this.isPlayer(event) && !this.collected) this.inRange = true;
}
private onExit(event: ITriggerEvent) {
if (!this.isPlayer(event) || this.collected) return;
this.inRange = false;
console.log('离开拾取范围');
}
private onKeyDown(event: EventKeyboard) {
if (event.keyCode !== KeyCode.KEY_E ||
!this.inRange || this.collected) return;
this.collected = true;
this.inRange = false;
console.log('拾取成功');
this.node.destroy(); // 同一物品只能领取一次
}
}预期输出(先进入、离开,再重新进入并按 E):
进入范围:按 E 拾取
离开拾取范围
进入范围:按 E 拾取
拾取成功停留期间不会刷屏;只有进入、离开以及真正拾取时才打印日志。这里用销毁道具表现领取成功,项目中可改为增加背包数量、播放音效后再销毁道具,不要把奖励写到 onTriggerStay 内。
处理持续接近与重复拾取
onTriggerEnter 和 onTriggerExit 是范围状态的边界,适合显示或隐藏“按 E”提示;onTriggerStay 会重复调用,适合刷新距离或交互目标,但不能每次都执行奖励。inRange 只是当前是否可交互的标志;collected 是一次性道具的幂等保护,避免按键连发重复结算。
如果角色进入范围却没有日志,优先确认 Is Trigger、角色的动态刚体、物理后端、碰撞矩阵,以及 player 是否指向真正挂有实体碰撞体的节点。若进入后提示无法消失,检查角色是否确实离开触发体;销毁或禁用角色等异常中断场景还应在业务代码中主动清理 UI 状态。
验证时分别测试范围外按 E 无效、范围内按 E 成功、离开后再按 E 无效、同一道具无法重复拾取。确保检测范围足够宽容,但不能大到隔着墙也能领奖;需要遮挡判断时,可在按键确认阶段增加射线检测,而不要误把触发器当作视线检测。