游戏引擎 / 系统课时
排查碰撞检测不到的问题
排查碰撞检测不到的问题
玩家走进金币却没有拾取,或子弹碰到敌人却没有扣血时,问题不一定在交互脚本。这里以 Cocos Creator 3.8 的二维场景为例,把“没有接触”“没有回调”和“回调后没处理”分开检查,再用一份最小监听脚本验证修复效果。
学习目标
- 按碰撞体形状、分组和物理后端逐层定位接触失效。
- 区分
Sensor、Collider2D和RigidBody2D对事件的影响。 - 使用接触日志判断故障属于物理配置还是业务逻辑。
先把故障复现条件固定下来
准备 Player 与 Coin 两个节点,让玩家从金币外部缓慢移动到内部,再移出。记录是否有接触日志、角色是否被挡住、拾取数量是否变化。测试时不要同时修改速度、碰撞体和业务脚本,否则无法确定是哪次修改起效。
先到“项目 → 项目设置 → 功能裁剪”确认二维物理后端是 Builtin 还是 Box2D。Builtin 只有碰撞检测,没有刚体动力学;Box2D 支持刚体和物理响应,但接触回调还受刚体监听配置影响。不要混用 Collider 等三维组件与 Collider2D。
从碰撞条件逐层排查
按以下顺序检查,两物体必须先满足前面的条件,后面的监听才有意义:
- 检查节点已激活、
Collider2D组件已启用。开启碰撞体的Editing,看真实轮廓是否重叠;美术图片相交不代表Size、Offset或圆形半径相交。 - 检查两边的
Group与“项目设置 → 物理配置 → 碰撞矩阵”。如果玩家组与金币组被过滤,任何回调脚本都无法补救;使用 Box2D 时也要核对刚体的分组。 - 检查金币
Collider2D的Sensor。拾取区通常开启它:允许报告接触,但不产生实体碰撞的推挤效果。不开启Sensor不代表一定收不到事件。 - 使用 Box2D 时,确认角色与金币构成有效的刚体接触组合,例如移动角色使用
Dynamic刚体、金币使用静态碰撞对象;检查相应RigidBody2D的EnabledContactListener已开启。两个静态对象之间不会产生预期接触。 - 检查监听脚本是否挂在具有
Collider2D的同一节点、组件是否启用,以及监听是否在对象进入接触前注册。Builtin 只需要有效的二维碰撞体即可发送开始和结束接触回调。

用最小脚本确认回调是否到达
创建 ContactProbe.ts,挂在 Player 的碰撞体节点上。下例是 Cocos Creator 3.8 工程内可运行的组件,前提是场景中已按上文配置 Player、Coin 和二维物理后端。
import { _decorator, Component, Collider2D, Contact2DType } from 'cc';
const { ccclass } = _decorator;
@ccclass('ContactProbe')
export class ContactProbe extends Component {
private collider: Collider2D | null = null;
onEnable(): void {
this.collider = this.getComponent(Collider2D);
if (!this.collider) {
console.warn('[ContactProbe] 缺少 Collider2D');
return;
}
// 只监听本节点,避免全局回调混入其他碰撞对
this.collider.on(Contact2DType.BEGIN_CONTACT, this.onBegin, this);
this.collider.on(Contact2DType.END_CONTACT, this.onEnd, this);
}
onDisable(): void {
if (!this.collider) return;
// 组件停用时解除监听,防止再次启用时重复注册
this.collider.off(Contact2DType.BEGIN_CONTACT, this.onBegin, this);
this.collider.off(Contact2DType.END_CONTACT, this.onEnd, this);
this.collider = null;
}
private onBegin(self: Collider2D, other: Collider2D): void {
console.log(`[接触开始] ${self.node.name} -> ${other.node.name}`);
}
private onEnd(self: Collider2D, other: Collider2D): void {
console.log(`[接触结束] ${self.node.name} -> ${other.node.name}`);
}
}预期输出:玩家进入金币区域再退出,控制台依次出现以下日志(假设节点名称为 Player、Coin)。
[接触开始] Player -> Coin
[接触结束] Player -> Coin如果只出现开始日志,先确认两者确实分离;若接触后立即销毁或停用金币,不一定会再收到结束事件。回调中的接触信息可能由引擎复用,需要跨帧使用时应复制所需数值,不要直接持有接触对象。
根据观测结果修复并回归
完全没有日志:从碰撞轮廓、节点启用状态、分组矩阵、后端类型和 Box2D 刚体监听重新检查;同时确认脚本挂载位置。如果偶尔丢失高速子弹的接触,应再检查每次物理步进的位移和 Box2D Bullet 等连续碰撞相关设置,而不是只增加回调。
日志正常但金币数不变:物理层已经通过,检查业务脚本是否用正确的节点、Tag 或组件识别金币,是否调用加金币方法,以及拾取后是否被重复处理。可在拾取入口再加一条业务日志,将“接触发生”和“奖励生效”拆开验证。
有回调但角色没有被挡住:若金币启用了 Sensor,这是预期现象;若选用 Builtin,它也不会提供 Box2D 式的动力学阻挡。不要用“没有推开”当作“没有检测到”。
最后分别测试允许接触与禁止接触的分组、Sensor 开启与关闭、进入与退出三个场景。只有接触日志和交互结果都与配置相符,才算排除了这次碰撞失效。