游戏引擎 / 系统课时

排查角色卡进墙体的问题

排查角色卡进墙体的问题

角色在墙边突然停住、抖动或穿进墙体,不能只靠调大碰撞体解决。本课用一条可复现的移动路径,先核对碰撞形状和场景阻挡,再检查移动是否绕开物理系统,最后用 Cocos Creator 3.8 的角色控制器验证修复。

学习目标

  • 根据穿透、贴墙卡死和墙角抖动等现象缩小排查范围。
  • 检查碰撞体尺寸、物理分组、移动接口与物理步进的关系。
  • 搭建最小测试场景,验证角色能被墙体阻挡且不持续卡住。

先区分穿透和卡死

先保留一个只有地面、角色和单面墙的场景,关闭无关脚本。让角色从墙外沿固定方向接近墙,再贴墙横向移动。不要在运行中直接拖动角色节点来判断正常行走的碰撞结果,因为这种位移与游戏控制逻辑不是一回事。

观察到的现象 优先怀疑的环节
角色直接穿过墙 墙体没有 Collider、Is Trigger 开启、分组不碰撞,或脚本直接改位置
正面停住却无法沿墙移动 控制器没有处理滑墙、碰撞体过宽,或两处脚本同时驱动角色
靠墙抖动、角落被困 初始形状重叠、模型与碰撞体错位、墙角几何过密或容差不合适
低速正常、高速穿透 离散物理步进期间位移过大,需核对速度、步长和检测方式

核对碰撞形状和阻挡关系

角色的可见 Mesh 不等于参与阻挡的物理形状。第三人称角色通常用胶囊形状包住躯干,避免把手脚动画或衣物边缘变成会卡墙的突出部位。碰撞体中心应跟随角色根节点,尺寸应与通道宽度匹配,而不是盲目放大。

角色碰撞形状、墙体厚度与两种移动路径的关系

按下面的顺序检查,能避免一开始就修改物理参数:

  1. 确认墙体上存在启用的 BoxCollider 等 3D 碰撞组件,Is Trigger 为关闭状态;触发器只负责通知,不能充当实体墙。
  2. 检查角色与墙体所在物理组的碰撞矩阵,确认双方允许发生阻挡;不要把 2D 的 Collider2D 当成 3D 碰撞体。
  3. 查看角色的碰撞体半径、中心和高度,并检查根节点缩放、模型子节点偏移;确认出生点没有与墙体或地面深度重叠。
  4. 暂时把复杂地形、门框和弯折墙角替换为简单盒体。如果问题消失,再逐块恢复,检查缝隙、叠放的碰撞体及通道宽度。

判断移动代码是否绕开物理

如果角色通过每帧调用 node.setPosition()、直接累加世界坐标或动画改写根节点位置来推进,即使场景有碰撞体,也不能指望普通位置赋值自动替你计算安全的滑动路径。

Cocos Creator 3.8 中可采用两条不同路线:需要稳定地沿地面走动、贴墙停止和爬小台阶,可选 CapsuleCharacterController 并调用 move(位移增量);需要受重力、冲量和推挤影响的物体,可选动态 RigidBody 加 Collider,以速度或力驱动。不要在同一个角色节点上混用角色控制器与动态刚体,也不要让别的脚本继续直接覆盖它的位置。

角色控制器的 move() 会沿路径检查碰撞,并按坡度与台阶条件决定继续移动还是停止;但它不会自动施加重力。下面只做平地水平方向的排障测试,避免把重力实现混进问题。

用固定路径复现并验证

在启用 3D 物理且选择 PhysX 或 Bullet 后,新建简化场景:Player 放在 (0, 1, 0),添加 CapsuleCharacterController,设置 Center=(0,0,0)、Radius=0.4、Height=1.2;这里的 Height 是胶囊两端半球球心间距。Wall 位于 (1.5,1,0),添加 BoxCollider 并设置 Size=(0.2,2,3);地面放在 y=-0.1,盒体厚度设为 0.2。三者使用允许碰撞的物理组,墙和地面不是 Trigger,角色根节点不再挂 RigidBody。

把以下完整脚本保存为 WallProbe.ts,挂在 Player 上。它持续两秒尝试沿世界 +X 移动;墙在途中,正确结果应是在墙前停止,而不是强行到达目标位置。

ts
import { _decorator, Component, CharacterController, CharacterControllerContact, Vec3 } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('WallProbe')
export class WallProbe extends Component {
  @property speed = 2;
  private controller: CharacterController | null = null;
  private elapsed = 0;
  private reportedHit = false;

  start() {
    this.controller = this.getComponent(CharacterController);
    if (!this.controller) {
      console.error('缺少 CharacterController');
      this.enabled = false;
      return;
    }
    this.controller.on('onControllerColliderHit', this.onHit, this);
  }

  update(dt: number) {
    if (!this.controller || this.elapsed >= 2) return;
    const step = Math.min(dt, 2 - this.elapsed);
    this.elapsed += step;
    // move 接收位移增量,不是绝对目标坐标
    this.controller.move(new Vec3(this.speed * step, 0, 0));
    if (this.elapsed >= 2) console.log('探测结束');
  }

  private onHit(hit: CharacterControllerContact) {
    // 地面也可能触发碰撞回调,只统计名为 Wall 的障碍
    if (this.reportedHit || hit.collider.node.name !== 'Wall') return;
    this.reportedHit = true;
    console.log('移动路径命中墙体');
  }

  onDestroy() {
    this.controller?.off('onControllerColliderHit', this.onHit, this);
  }
}

预期输出(角色从墙外出发且碰撞配置正确时):

text
移动路径命中墙体
探测结束

预期结果是角色停在墙外,中心 X 坐标接近 1.0,具体值会受 Skin Width 等容差影响;它不会移动满两秒对应的四米。若只出现“探测结束”,先核对物理后端、碰撞分组、墙体组件和起点,而不是直接扩大胶囊。

继续排查物理步进与墙角

若简化场景正常、原项目却异常,比较原移动脚本和该测试:是否同时有输入脚本与动画驱动根节点,是否把速度误当成位移传给 move(),或把 dt 重复相乘。墙角处还要观察两面墙的夹角、门洞净宽,以及角色胶囊是否大于可通行空间。

动态刚体出现高速穿过薄墙时,再检查固定物理步长、移动速度,并在物理后端支持的条件下考虑 RigidBody.useCCD;CCD 不能修复错误分组、缺失的碰撞体或出生点重叠。角色控制器若持续轻微贴墙抖动,可小幅检查 Skin Width、Step Offset 和 Slope Limit,每次只改一个参数并重复同一条测试路线。

只有简化测试、贴墙横移和原场景三项都通过,才应把问题视为修复;相关组件行为可对照官方 Cocos Creator 3.8 角色控制器文档。

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

目录与阅读设置

阅读设置

17

记录一个想法

排查角色卡进墙体的问题

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

登录哪都通