游戏引擎 / 系统课时
给角色添加碰撞体
给角色添加碰撞体
本课将为 Cocos Creator 3.8 的三维角色添加胶囊碰撞体,并为地面配置盒体碰撞形状。完成后,你可以检查碰撞体与模型的尺寸、中心偏移和节点层级是否匹配,再使用物理模拟验证角色不会直接穿过地面,为后续角色移动、阻挡与接地检测建立可靠基础。
学习目标
- 根据角色与场景形状选择合适的三维碰撞体。
- 正确配置碰撞体尺寸、局部中心和节点层级。
- 通过 TypeScript 和物理预览检查配置及碰撞效果。
先确定角色需要什么碰撞形状
碰撞体是供物理系统计算接触和阻挡的简化几何形状,并不是可见模型本身。一个角色模型可能包含复杂的四肢、装备和骨骼,但身体移动通常不需要按每个三角面进行碰撞检测。
| 形状 | 适合的对象 | 主要参数 |
|---|---|---|
| BoxCollider | 地面、墙壁、箱体 | Center、Size |
| SphereCollider | 球形道具、简单检测区域 | Center、Radius |
| CapsuleCollider | 站立角色、NPC | Center、Radius、CylinderHeight |
| MeshCollider | 不规则静态场景表面 | Mesh、Convex 等配置 |
普通第三人称角色优先使用沿 Y 轴竖直的胶囊体。圆柱部分覆盖躯干,上下半球让角色更容易处理平面与边缘接触。与逐骨骼碰撞相比,这种方案成本更低,形状也更稳定。
本例角色可见高度约为 1.8 个世界单位,约定角色根节点原点位于双脚落地点,根节点缩放为 (1,1,1)。胶囊参数设置为 Radius = 0.3、CylinderHeight = 1.2、Center = (0,0.9,0),方向为 Y。
需要特别注意:Cocos Creator 3.8 的 CapsuleCollider 中,CylinderHeight 表示中间圆柱段的高度,不是整个胶囊的高度。因此总体高度等于圆柱段高度加两倍半径,本例为 1.8,底端刚好位于角色根节点的 Y=0 位置。

把碰撞体放在正确节点上
建议将角色拆成负责整体移动的 PlayerRoot 和负责外观表现的 ModelRoot。碰撞体与刚体放在 PlayerRoot 上,骨骼模型、蒙皮渲染和动画放在 ModelRoot 上。这样模型播放跑步、摆臂等动作时,不会直接改变身体主碰撞形状。
以下是搭建最小测试场景的步骤:
- 在场景中创建空节点 PlayerRoot,将位置设为 (0,2,0),缩放保持 (1,1,1)。
- 将角色模型作为子节点 ModelRoot 放入 PlayerRoot,调整可见模型,使双脚在 PlayerRoot 的局部 Y=0 附近。
- 在 PlayerRoot 的属性检查器中,通过 Add Component 添加 Physics 下的 CapsuleCollider 和 RigidBody。
- 创建空节点 Ground,位置设为 (0,-0.1,0),缩放保持 (1,1,1),添加 Physics 下的 BoxCollider。
- 在 Ground 下创建 GroundVisual 子节点,用立方体或其他模型显示地面,并使其可见尺寸与碰撞盒一致。
- 在项目的物理系统设置中启用支持刚体物理响应的后端,例如 Bullet 或 PhysX,并确认角色与地面所在物理分组允许碰撞。
在这一布局中,Ground 碰撞盒高度为 0.2,中心位于局部原点,因此地面顶面世界高度为 Y=0。角色初始放在 Y=2,启动后便有足够空间向下运动并接触地面。
用脚本固定碰撞体尺寸
编辑器中可以直接修改这些参数。为了避免不同 Prefab 实例之间出现尺寸偏差,也可以使用脚本集中初始化。
创建 ColliderSetup.ts,将脚本挂到场景中的独立控制节点,并在 Inspector 中将 PlayerRoot 和 Ground 分别拖入对应属性。以下代码使用真实的 Cocos Creator 3.8 物理组件接口:
import {
_decorator, Component, Node, Vec3,
CapsuleCollider, BoxCollider, RigidBody
} from 'cc';
const { ccclass, property } = _decorator;
@ccclass('ColliderSetup')
export class ColliderSetup extends Component {
@property(Node)
playerRoot: Node | null = null;
@property(Node)
groundRoot: Node | null = null;
start() {
if (!this.playerRoot || !this.groundRoot) {
console.error('请绑定 PlayerRoot 和 Ground');
return;
}
// 胶囊放在角色根节点,避免骨骼动画影响主体碰撞。
const capsule = this.playerRoot.getComponent(CapsuleCollider)
?? this.playerRoot.addComponent(CapsuleCollider);
capsule.radius = 0.3;
capsule.cylinderHeight = 1.2;
capsule.center = new Vec3(0, 0.9, 0);
capsule.isTrigger = false;
// 动态刚体接受重力和碰撞响应。
const body = this.playerRoot.getComponent(RigidBody)
?? this.playerRoot.addComponent(RigidBody);
body.type = RigidBody.Type.DYNAMIC;
body.useGravity = true;
const ground = this.groundRoot.getComponent(BoxCollider)
?? this.groundRoot.addComponent(BoxCollider);
ground.size = new Vec3(10, 0.2, 10);
ground.center = new Vec3(0, 0, 0);
ground.isTrigger = false;
console.log(`Collider ready: radius=${capsule.radius}, cylinder=${capsule.cylinderHeight}`);
console.log(`Ground: ${ground.size.x}x${ground.size.y}x${ground.size.z}`);
}
}预期输出:正确绑定节点并启动预览后,控制台应出现以下配置日志,实际控制台可能另外显示时间和脚本来源。
Collider ready: radius=0.3, cylinder=1.2
Ground: 10x0.2x10这些日志只证明组件参数已经成功设置,并不单独证明物理碰撞已经生效。实际验收还需要观察角色的运动结果。
验证角色是否真正被阻挡
运行前先确认 Ground 不需要额外添加动态刚体。只有 BoxCollider 而没有 RigidBody 的地面,在支持完整物理模拟的后端中可作为静态碰撞对象;角色则使用 Dynamic RigidBody 接受重力。
启动预览后,预期结果是角色从 Y=2 开始下落,接触 Ground 顶面后停止继续穿透。由于角色胶囊的底部恰好对齐 PlayerRoot 原点,静止时根节点的 Y 坐标应接近 0;实际数值可能因为物理接触容差、求解器和休眠状态略有差异。
如果角色穿透地面,优先检查:
- 物理后端是否支持完整碰撞响应,物理模拟是否启用。
- 两个碰撞体的 IsTrigger 是否均为 false,物理分组和碰撞矩阵是否允许相互接触。
- Ground 的 BoxCollider 是否真的覆盖可见地面,尤其检查 Size 和 Center。
- PlayerRoot 是否拥有 Dynamic RigidBody,而不是只有一个胶囊形状。
- 场景中是否还有脚本每帧直接覆盖角色位置,与物理模拟争夺控制权。
如果角色看起来悬浮,应检查可见模型的脚底高度与胶囊底端是否一致。若角色进门时被卡住,应检查胶囊直径是否超过可通行宽度,而不是只观察模型肩膀宽度。
避免尺寸和层级引入隐藏误差
碰撞体的 Center 与 Size 等参数通常定义在所属节点的局部空间中,最终世界形状还会受到节点变换影响。尤其需要留意父节点的缩放:当父节点存在非等比缩放或旋转组合时,碰撞体的实际形状可能与直观设置不一致。
建议承载物理组件的 PlayerRoot 和 Ground 保持单位缩放,让子节点负责模型的视觉尺寸调整。比如地面显示模型可以放大,但不要再把 Ground 本身放大十倍,同时又将 BoxCollider.Size 设置成十倍尺寸,否则容易重复放大碰撞范围。
还要区分普通碰撞体和 Trigger。普通碰撞体用于物理阻挡,Trigger 用于进入、停留、离开等检测事件,不应依赖 Trigger 自动阻止角色穿越。需要复杂角色滑墙、爬坡和台阶移动时,应进一步评估 Character Controller,而不是把动态刚体与直接修改节点位置的移动方式随意混合。
完成本课后,角色的外观和物理体积应能分别调整,同时保持脚底、地面高度和根节点原点一致。这比盲目依赖自动生成的模型碰撞范围更容易维护,也更适合作为后续移动与跳跃系统的基础。