游戏引擎 / 系统课时
排查角色卡进墙体的问题
排查角色卡进墙体的问题
角色在墙边突然停住、抖动或穿进墙体,不能只靠调大碰撞体解决。本课用一条可复现的移动路径,先核对碰撞形状和场景阻挡,再检查移动是否绕开物理系统,最后用 Cocos Creator 3.8 的角色控制器验证修复。
学习目标
- 根据穿透、贴墙卡死和墙角抖动等现象缩小排查范围。
- 检查碰撞体尺寸、物理分组、移动接口与物理步进的关系。
- 搭建最小测试场景,验证角色能被墙体阻挡且不持续卡住。
先区分穿透和卡死
先保留一个只有地面、角色和单面墙的场景,关闭无关脚本。让角色从墙外沿固定方向接近墙,再贴墙横向移动。不要在运行中直接拖动角色节点来判断正常行走的碰撞结果,因为这种位移与游戏控制逻辑不是一回事。
| 观察到的现象 | 优先怀疑的环节 |
|---|---|
| 角色直接穿过墙 | 墙体没有 Collider、Is Trigger 开启、分组不碰撞,或脚本直接改位置 |
| 正面停住却无法沿墙移动 | 控制器没有处理滑墙、碰撞体过宽,或两处脚本同时驱动角色 |
| 靠墙抖动、角落被困 | 初始形状重叠、模型与碰撞体错位、墙角几何过密或容差不合适 |
| 低速正常、高速穿透 | 离散物理步进期间位移过大,需核对速度、步长和检测方式 |
核对碰撞形状和阻挡关系
角色的可见 Mesh 不等于参与阻挡的物理形状。第三人称角色通常用胶囊形状包住躯干,避免把手脚动画或衣物边缘变成会卡墙的突出部位。碰撞体中心应跟随角色根节点,尺寸应与通道宽度匹配,而不是盲目放大。

按下面的顺序检查,能避免一开始就修改物理参数:
- 确认墙体上存在启用的
BoxCollider等 3D 碰撞组件,Is Trigger为关闭状态;触发器只负责通知,不能充当实体墙。 - 检查角色与墙体所在物理组的碰撞矩阵,确认双方允许发生阻挡;不要把 2D 的
Collider2D当成 3D 碰撞体。 - 查看角色的碰撞体半径、中心和高度,并检查根节点缩放、模型子节点偏移;确认出生点没有与墙体或地面深度重叠。
- 暂时把复杂地形、门框和弯折墙角替换为简单盒体。如果问题消失,再逐块恢复,检查缝隙、叠放的碰撞体及通道宽度。
判断移动代码是否绕开物理
如果角色通过每帧调用 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 移动;墙在途中,正确结果应是在墙前停止,而不是强行到达目标位置。
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);
}
}预期输出(角色从墙外出发且碰撞配置正确时):
移动路径命中墙体
探测结束预期结果是角色停在墙外,中心 X 坐标接近 1.0,具体值会受 Skin Width 等容差影响;它不会移动满两秒对应的四米。若只出现“探测结束”,先核对物理后端、碰撞分组、墙体组件和起点,而不是直接扩大胶囊。
继续排查物理步进与墙角
若简化场景正常、原项目却异常,比较原移动脚本和该测试:是否同时有输入脚本与动画驱动根节点,是否把速度误当成位移传给 move(),或把 dt 重复相乘。墙角处还要观察两面墙的夹角、门洞净宽,以及角色胶囊是否大于可通行空间。
动态刚体出现高速穿过薄墙时,再检查固定物理步长、移动速度,并在物理后端支持的条件下考虑 RigidBody.useCCD;CCD 不能修复错误分组、缺失的碰撞体或出生点重叠。角色控制器若持续轻微贴墙抖动,可小幅检查 Skin Width、Step Offset 和 Slope Limit,每次只改一个参数并重复同一条测试路线。
只有简化测试、贴墙横移和原场景三项都通过,才应把问题视为修复;相关组件行为可对照官方 Cocos Creator 3.8 角色控制器文档。