Babylon.js 集成 Cannon.js 实现物理碰撞效果

缩略图：Babylon.js × Cannon.js 物理碰撞集成核心全景示意

一、物理引擎集成架构与工作原理

在深入编写代码之前，理解 Babylon.js 与 Cannon.js 的职责边界是避免后续逻辑混乱的关键。Babylon.js 核心专注于场景图树的组织、几何材质构建、光照计算以及将几何数据提交给 WebGL/WebGPU 渲染；而 Cannon.js 是一个轻量级、完全用 JavaScript 编写的 3D 刚体物理库，它内部维护一套纯数学的物理世界（CANNON.World），在此世界中仅计算质心、线速度、角速度、动量守恒与接触受力，完全不包含任何着色器或顶点渲染逻辑。

这两者之间通过 Babylon.js 提供的 CannonJSPlugin 桥接。开发者并不会直接操作复杂的 Cannon.js 底层类，而是为视觉网格（BABYLON.Mesh）赋予一个 BABYLON.PhysicsImpostor（物理代理体）。代理体内部持有与之对应的 CANNON.Body。在引擎的每一个渲染帧循环（scene.render()）开始前，Babylon.js 会调度物理插件执行步进计算（world.step()），计算完成后自动提取刚体的最新坐标与四元数（Quaternion），同步赋值给视觉网格的变换矩阵，从而呈现出符合经典力学规律的运动与碰撞画面。

图1：Babylon.js 与底层物理引擎解耦及每帧状态同步架构

值得注意的是，一旦为某个网格绑定了 PhysicsImpostor，该网格的运动轨迹就由物理引擎全权接管。此时如果直接在渲染帧中以硬编码方式修改 mesh.position.y += 0.1，会造成物理世界刚体与视觉网格的脱节，导致物体颤抖或碰撞失效。正确的交互方式是对刚体施加物理冲量（Impulse）、外力（Force）或修改线速度（Linear Velocity）。

二、集成步骤与环境初始化

要在 Babylon.js 中使用 Cannon.js，整个构建过程可归纳为规范的四个连续步骤：引入依赖库、在场景中激活物理引擎、配置并绑定碰撞体、监听碰撞或交互反馈。

图2：Babylon.js 集成 Cannon.js 的四步实现在位流程

1. 引入 Cannon.js 依赖

Babylon.js 的核心包自身不包含 Cannon.js 的源码实现，因此必须先确保 Cannon.js 在运行环境中可用。传统的 HTML 页面中，可以通过 <script> 标签将 cannon.js 引入，且必须先于或与 Babylon.js 一同加载，确保全局命名空间下存在 window.CANNON：

<!-- 1. 引入 Cannon.js 物理库 -->
<script src="https://cdn.babylonjs.com/cannon.js"></script>
<!-- 2. 引入 Babylon.js 核心引擎 -->
<script src="https://cdn.babylonjs.com/babylon.js"></script>

如果在现代 Vite、Webpack 等模块化工程中使用 npm 依赖，在导入 BABYLON 后，若遇到 CANNON is not defined 报错，可以将引入的模块显式挂载到 window.CANNON，或者作为参数传入 CannonJSPlugin 的构造函数：

import * as BABYLON from '@babylonjs/core';
import * as CANNON from 'cannon';

// 显式注入 CANNON 对象，避免作用域查找失败
const cannonPlugin = new BABYLON.CannonJSPlugin(true, 10, CANNON);

2. 启用物理世界（enablePhysics）

创建好场景 scene 后，调用 scene.enablePhysics() 方法激活物理模拟。该方法接受两个核心参数：全局重力加速度向量 Vector3 与物理插件实例：

// 设置地球标准重力加速度：Y 轴负方向 9.81 m/s²
const gravityVector = new BABYLON.Vector3(0, -9.81, 0);
const physicsPlugin = new BABYLON.CannonJSPlugin();

// 激活场景物理引擎
scene.enablePhysics(gravityVector, physicsPlugin);

如果开发的是太空漫游、失重环境或顶视角台球碰撞游戏，可以将重力向量设为 new BABYLON.Vector3(0, 0, 0)，物体将保持匀速直线运动，直到碰撞或受到外力扰动。

三、碰撞体（PhysicsImpostor）选型与物理材质参数

真实三维模型的顶点数成千上万，如果直接使用模型原本的高密三角网格进行实时的空间碰撞检测，计算复杂度会急剧上升导致页面严重卡顿。因此物理引擎的核心原则是：用简化的数学几何体作为“碰撞代理”，包裹复杂外观的视觉网格。

图3：物理碰撞体（Impostor）形状选型与材质核心参数影响

1. 常用碰撞体形状类型

2. 物理材质参数（PhysicsImpostorParameters）解析

在实例化 PhysicsImpostor 时，第三个参数是物理属性配置对象，其核心配置决定了物体的动量表现：

• mass（质量）： 核心分水岭。当 mass = 0 时，物理引擎将其标记为静态刚体（Static Body），无论受到多大冲力或重力作用，都牢固固定在世界空间中不动，专门用于地面、承重柱与不可摧毁的障碍物；当 mass > 0 时，物体为动态刚体（Dynamic Body），受重力自然下落并在撞击时发生动量交换。
• restitution（恢复系数 / 弹性）： 取值范围通常为 0.0 ~ 1.0。设为 0.0 表示完全非弹性碰撞，球体撞击地面后会像一团黏土一样直接贴地停止弹跳；设为 0.8 以上时，撞击后将反弹释放大部分动能；两物体相撞时的综合弹力由双方的 restitution 共同推导。
• friction（摩擦因数）： 表面切向滑动阻力。取值 0.0 表示完全光滑的冰面，滑块在斜面上会加速滑到底且不产生翻滚；较高的摩擦力（如 0.6）会在触地瞬间产生切向力矩，带动球体或圆柱体自然自转。

四、完整可运行代码示例

下面是一个经过验证的单文件独立 HTML 示例。代码构建了一个完整的 3D 物理测试场：包含倾斜的滑道斜坡、平整的承重地面、若干具有不同弹性和摩擦力的彩色小球，并在小球撞击地面时通过 registerOnPhysicsCollide 监听触发反光高亮效果，同时支持点击鼠标为空中小球施加向上冲量：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>Babylon.js Cannon.js 碰撞测试场</title>
  <style>
    html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; }
    #renderCanvas { width: 100%; height: 100%; touch-action: none; }
  </style>
  <!-- 引入 Cannon.js 与 Babylon.js -->
  <script src="https://cdn.babylonjs.com/cannon.js"></script>
  <script src="https://cdn.babylonjs.com/babylon.js"></script>
</head>
<body>
  <canvas id="renderCanvas"></canvas>

  <script>
    const canvas = document.getElementById("renderCanvas");
    const engine = new BABYLON.Engine(canvas, true);

    const createScene = function () {
      const scene = new BABYLON.Scene(engine);
      scene.clearColor = new BABYLON.Color4(0.98, 0.97, 0.95, 1.0);

      // 1. 相机与环境光照
      const camera = new BABYLON.ArcRotateCamera(
        "camera", -Math.PI / 2.2, Math.PI / 2.8, 22,
        new BABYLON.Vector3(0, 3, 0), scene
      );
      camera.attachControl(canvas, true);

      const hemiLight = new BABYLON.HemisphericLight(
        "hemiLight", new BABYLON.Vector3(0, 1, 0), scene
      );
      hemiLight.intensity = 0.85;

      // 2. 启用 Cannon.js 物理引擎
      const gravity = new BABYLON.Vector3(0, -9.81, 0);
      const cannonPlugin = new BABYLON.CannonJSPlugin();
      scene.enablePhysics(gravity, cannonPlugin);

      // 3. 创建静态地面 (质量为 0)
      const ground = BABYLON.MeshBuilder.CreateBox("ground", { width: 18, height: 1, depth: 18 }, scene);
      ground.position.y = -0.5; // 顶面与 y=0 水平
      const groundMat = new BABYLON.StandardMaterial("groundMat", scene);
      groundMat.diffuseColor = new BABYLON.Color3(0.22, 0.28, 0.34);
      ground.material = groundMat;

      ground.physicsImpostor = new BABYLON.PhysicsImpostor(
        ground,
        BABYLON.PhysicsImpostor.BoxImpostor,
        { mass: 0, friction: 0.5, restitution: 0.6 },
        scene
      );

      // 4. 创建倾斜滑道 (静态斜板)
      const ramp = BABYLON.MeshBuilder.CreateBox("ramp", { width: 6, height: 0.5, depth: 10 }, scene);
      ramp.position = new BABYLON.Vector3(-3, 4, 0);
      ramp.rotation = new BABYLON.Vector3(0, 0, -Math.PI / 6); // 倾斜 30 度

      ramp.physicsImpostor = new BABYLON.PhysicsImpostor(
        ramp,
        BABYLON.PhysicsImpostor.BoxImpostor,
        { mass: 0, friction: 0.2, restitution: 0.3 },
        scene
      );

      // 5. 创建动态弹跳球体 (质量为 1)
      const sphere = BABYLON.MeshBuilder.CreateSphere("bouncingBall", { diameter: 1.2 }, scene);
      sphere.position = new BABYLON.Vector3(-4.5, 9, 0); // 位于斜面上方空中
      const sphereMat = new BABYLON.StandardMaterial("sphereMat", scene);
      sphereMat.diffuseColor = new BABYLON.Color3(0.68, 0.54, 0.35); // 暗金色
      sphere.material = sphereMat;

      sphere.physicsImpostor = new BABYLON.PhysicsImpostor(
        sphere,
        BABYLON.PhysicsImpostor.SphereImpostor,
        { mass: 1.0, friction: 0.3, restitution: 0.75 },
        scene
      );

      // 6. 监听小球与地面的物理碰撞事件
      sphere.physicsImpostor.registerOnPhysicsCollide(
        ground.physicsImpostor,
        function (mainImpostor, collidedImpostor) {
          // 发生碰撞时闪烁白色，随后恢复
          sphere.material.emissiveColor = new BABYLON.Color3(0.5, 0.3, 0.1);
          setTimeout(() => {
            sphere.material.emissiveColor = BABYLON.Color3.Black();
          }, 120);
        }
      );

      // 7. 交互：点击画布时给小球施加向上冲量 (Impulse)
      canvas.addEventListener("pointerdown", () => {
        const impulseDir = new BABYLON.Vector3(0, 8, 0);
        const contactPoint = sphere.getAbsolutePosition();
        sphere.physicsImpostor.applyImpulse(impulseDir, contactPoint);
      });

      return scene;
    };

    const scene = createScene();
    engine.runRenderLoop(() => { scene.render(); });
    window.addEventListener("resize", () => { engine.resize(); });
  </script>
</body>
</html>

在浏览器中运行上述代码，读者将观察到：小球在重力作用下竖直下落，撞击 30 度倾斜板并由于法向弹力向右下方滑动弹跳，随后落到深蓝灰色地面上进行多轮递减弹跳，每次触碰地面均会短暂触发发光回调；单击鼠标屏幕时，小球会被赋予竖直向上的瞬时冲量再次跃起。整个物理轨迹完全由 Cannon.js 积分计算并驱动渲染。

五、常见问题排查与性能调优指南

在实际复杂项目的物理碰撞落地中，常会遇到穿模、抖动或帧率下降等现象。以下是高频问题与其对症解决手段的系统总结：

图4：Babylon.js + Cannon.js 碰撞集成问题排查与优化总结全景

1. 高速物体穿模击穿（Tunneling）

当炮弹、弓箭或极速下落的刚体撞击较薄的墙面或地面时，常发生“瞬间直接穿透”的 BUG。这是因为 Cannon.js 默认采用离散时间碰撞检测（Discrete Collision Detection）。如果一个物体在一个时间步长内移动的距离大于阻挡物的厚度，那么在 $t$ 时刻物体在墙前，在 $t + \Delta t$ 时刻物体已经移动到墙后，两个离散状态下均未发生几何相交，碰撞判定直接漏检。

• 解法一：增加障碍物厚度。 静态地面或阻挡墙的几何厚度不要设为 0 或极薄的单片平面（Plane）。建议使用深度至少为 0.5m ~ 1m 的 BoxImpostor。
• 解法二：加密物理时间步长。 默认的物理刷新为 1/60 秒，通过调用 cannonPlugin.setTimeStep(1 / 120) 可以将步长缩短一倍，增加检测频次以消除大部分穿模。
• 解法三：对速度设定上限。 在每帧渲染钩子中限制动态物体的最大线速度模长，防止加速度无限累加导致单帧瞬移距离失控。

2. 外部模型枢轴点（Pivot）与缩放烘焙

使用 SceneLoader.ImportMesh 导入外部导出的 GLTF/OBJ 模型时，经常出现碰撞包围盒漂移在模型身体外侧的现象。产生该问题的根本原因是模型的原点（Origin / Pivot Point）位于脚底甚至世界坐标系原点，并未与几何体网格的几何中心重合。

3. 刚体休眠机制（Sleep）与性能维护

在场景中生成几十个甚至上百个堆叠的刚体木箱时，帧率往往会明显下跌。这是由于即便箱子已经在地面静止，物理引擎在每一帧依然在对所有接触点进行微小摩擦力与约束求解。

Cannon.js 支持刚体休眠机制。通过访问底层物理世界对象开启休眠功能：

// 获取底层 CANNON.World 实例并开启自动休眠
const cannonWorld = physicsPlugin.world;
cannonWorld.allowSleep = true;

开启后，当刚体的线速度与角速度在一段时间内低于设定的静止阈值时，引擎会将其置为休眠状态，完全跳过受力迭代计算；直到有其他活动刚体再次撞击它时，才会被瞬间自动唤醒。这能显著降低大规模碰撞场景下的 CPU 负荷。

4. 使用 PhysicsViewer 进行可视化线框调试

碰撞代理体在默认渲染中是隐形的，这常常导致排查“为何物体悬空”或“为何斜着滑行”变得盲目。Babylon.js 提供了官方的物理调试工具 PhysicsViewer，它可以直接在场景中绘制出底层实际参与计算的半透明刚体线框：

// 实例化物理透视工具
const physicsViewer = new BABYLON.Debug.PhysicsViewer(scene);

// 注册需要观察线框的物理代理体
physicsViewer.showImpostor(ground.physicsImpostor);
physicsViewer.showImpostor(sphere.physicsImpostor);

开启该工具后，屏幕上会高亮显示对应的立方体或球体物理包围线。开发者可以直观看到物理体与视觉网格是否存在尺寸偏差、姿态旋转偏移或未对齐问题，是排查物理疑难杂症不可或缺的开发利器。

结语

通过 Babylon.js 内置的 CannonJSPlugin 与 PhysicsImpostor 体系，开发者无需直接操纵繁杂的物理微分方程，就能以清晰的结构为 3D 网格赋予质量、阻尼与碰撞边界。在实际开发中，谨记“静态刚体质量设 0”、“避免对动态网格强行硬改坐标”、“选用简化几何体作为碰撞代理”，并善用 PhysicsViewer 辅助线框调试，就能稳定高效地构建出具有丰富力学交互与生动表现力的 Web 3D 物理应用。