游戏引擎 / 系统课时

排查碰撞检测不到的问题

排查碰撞检测不到的问题

玩家走进金币却没有拾取,或子弹碰到敌人却没有扣血时,问题不一定在交互脚本。这里以 Cocos Creator 3.8 的二维场景为例,把“没有接触”“没有回调”和“回调后没处理”分开检查,再用一份最小监听脚本验证修复效果。

学习目标

  • 按碰撞体形状、分组和物理后端逐层定位接触失效。
  • 区分 Sensor、Collider2D 和 RigidBody2D 对事件的影响。
  • 使用接触日志判断故障属于物理配置还是业务逻辑。

先把故障复现条件固定下来

准备 Player 与 Coin 两个节点,让玩家从金币外部缓慢移动到内部,再移出。记录是否有接触日志、角色是否被挡住、拾取数量是否变化。测试时不要同时修改速度、碰撞体和业务脚本,否则无法确定是哪次修改起效。

先到“项目 → 项目设置 → 功能裁剪”确认二维物理后端是 Builtin 还是 Box2D。Builtin 只有碰撞检测,没有刚体动力学;Box2D 支持刚体和物理响应,但接触回调还受刚体监听配置影响。不要混用 Collider 等三维组件与 Collider2D。

从碰撞条件逐层排查

按以下顺序检查,两物体必须先满足前面的条件,后面的监听才有意义:

  1. 检查节点已激活、Collider2D 组件已启用。开启碰撞体的 Editing,看真实轮廓是否重叠;美术图片相交不代表 Size、Offset 或圆形半径相交。
  2. 检查两边的 Group 与“项目设置 → 物理配置 → 碰撞矩阵”。如果玩家组与金币组被过滤,任何回调脚本都无法补救;使用 Box2D 时也要核对刚体的分组。
  3. 检查金币 Collider2D 的 Sensor。拾取区通常开启它:允许报告接触,但不产生实体碰撞的推挤效果。不开启 Sensor 不代表一定收不到事件。
  4. 使用 Box2D 时,确认角色与金币构成有效的刚体接触组合,例如移动角色使用 Dynamic 刚体、金币使用静态碰撞对象;检查相应 RigidBody2D 的 EnabledContactListener 已开启。两个静态对象之间不会产生预期接触。
  5. 检查监听脚本是否挂在具有 Collider2D 的同一节点、组件是否启用,以及监听是否在对象进入接触前注册。Builtin 只需要有效的二维碰撞体即可发送开始和结束接触回调。

二维碰撞失效的分层排查流程

用最小脚本确认回调是否到达

创建 ContactProbe.ts,挂在 Player 的碰撞体节点上。下例是 Cocos Creator 3.8 工程内可运行的组件,前提是场景中已按上文配置 Player、Coin 和二维物理后端。

ts
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)。

text
[接触开始] Player -> Coin
[接触结束] Player -> Coin

如果只出现开始日志,先确认两者确实分离;若接触后立即销毁或停用金币,不一定会再收到结束事件。回调中的接触信息可能由引擎复用,需要跨帧使用时应复制所需数值,不要直接持有接触对象。

根据观测结果修复并回归

完全没有日志:从碰撞轮廓、节点启用状态、分组矩阵、后端类型和 Box2D 刚体监听重新检查;同时确认脚本挂载位置。如果偶尔丢失高速子弹的接触,应再检查每次物理步进的位移和 Box2D Bullet 等连续碰撞相关设置,而不是只增加回调。

日志正常但金币数不变:物理层已经通过,检查业务脚本是否用正确的节点、Tag 或组件识别金币,是否调用加金币方法,以及拾取后是否被重复处理。可在拾取入口再加一条业务日志,将“接触发生”和“奖励生效”拆开验证。

有回调但角色没有被挡住:若金币启用了 Sensor,这是预期现象;若选用 Builtin,它也不会提供 Box2D 式的动力学阻挡。不要用“没有推开”当作“没有检测到”。

最后分别测试允许接触与禁止接触的分组、Sensor 开启与关闭、进入与退出三个场景。只有接触日志和交互结果都与配置相符,才算排除了这次碰撞失效。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查碰撞检测不到的问题

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通