ammo.js 入门：Web 项目中引入库与初始化物理世界

一、理解 ammo.js 的特殊性：从 C++ 到 WebAssembly

在着手编写代码之前，必须明确 ammo.js 与普通前端 npm 包的核心差异。Bullet Physics 原生由 C++ 编写，Mozilla 的 Emscripten 工具链通过两套文件将其转换为浏览器可用资源：

• ammo.wasm.js：胶水代码（Glue Code）。负责在 JavaScript 与底层编译内存之间搭建桥梁，声明全局工厂函数，并在执行时挂载所有导出的 C++ 类结构映射。
• ammo.wasm.wasm：编译后的二进制模块。包含 Bullet 引擎完整的数值积分、碰撞检测与几何算法机器码，运行在浏览器的 WebAssembly 虚拟机中。

因为 WASM 文件必须经过网络请求拉取并由浏览器异步编译，所以 Ammo 导出的并非一个已经初始化的工具对象，而是一个返回 Promise 的工厂函数。在 Promise 兑现之前，任何试图创建物理对象（如 new Ammo.btVector3()）的代码都会抛出运行时未定义错误。

此外，ammo.js 内部的对象分配在 WebAssembly 的线性内存（C++ 堆内存）中。V8 等浏览器的垃圾回收器（Garbage Collector）无法追踪这些分配，这也意味着开发者在物理世界生命周期结束或销毁物体时，必须遵循显式释放的准则。

二、在 Web 项目中正确引入 ammo.js

无论采用传统的 HTML 原生脚本引入，还是使用 Vite、Webpack 等现代构建工具，核心任务都是：保证 glue 脚本能够精准定位到对应的 .wasm 二进制文件，并等待其初始化完毕。

图 1：Web 项目中引入 ammo.js 的四步装载流水线

1. 文件存放与静态托管

通常推荐使用官方仓库构建出的 WASM 版本（位于 ammo.js 仓库的 builds/ammo.wasm.js 与 builds/ammo.wasm.wasm）。在基于 Vite 或 Webpack 的工程中，应将这两个文件放置在不受打包工具哈希重命名的静态目录（例如 public/ammo/）。

2. 静态页面与模块化引入方式

在传统 HTML 中，可以直接通过 <script> 标签载入胶水文件，胶水代码会在全局作用域暴露一个名为 Ammo 的工厂函数：

<!-- index.html -->
<script src="/ammo/ammo.wasm.js"></script>
<script>
  // Ammo 是一个全局工厂函数，传入配置对象或直接调用
  Ammo().then((ammoInstance) => {
    // 此时 WebAssembly 已编译挂载，ammoInstance 即具备完整 API 的物理库
    console.log("ammo.js 物理运行时初始化就绪");
    startPhysicsApp(ammoInstance);
  });
</script>

如果是在 Vite 或现代工程中按模块引入，由于胶水代码通常采用 UMD/Global 导出，可以配置 locateFile 钩子显式指定 wasm 路径，避免浏览器去错误的根路径请求二进制文件导致 404：

// physicsLoader.js
export async function loadAmmo() {
  if (window.Ammo) {
    // 调用工厂函数，并通过 locateFile 告知 wasm 资源的绝对访问 URL
    const ammoInstance = await window.Ammo({
      locateFile(path) {
        if (path.endsWith('.wasm')) {
          return '/ammo/ammo.wasm.wasm';
        }
        return path;
      }
    });
    return ammoInstance;
  }
  throw new Error("ammo.wasm.js 未在全局挂载，请检查 script 标签引入路径");
}

三、初始化物理世界的五大核心构件

许多刚接触 Bullet 或 ammo.js 的开发者会困惑：为什么不能像其他引擎那样一行 new World() 搞定，而是必须依序构造好几个看起来冗长复杂的类？

原因在于 Bullet 引擎采用了高度解耦的工业级架构设计。一个完整的刚体动力学系统需要分别处理内存策略、碰撞分发、空间索引和数学约束求解。在 ammo.js 中，顶层的 btDiscreteDynamicsWorld 只是一个装配容器，它需要将以下四个构件注入其中才能正常运转。

图 2：Bullet 物理世界的五大核心构件与装配依赖模型

1. 碰撞配置（btDefaultCollisionConfiguration）

负责为整个物理模拟期间的碰撞检测预分配内存池，并注册系统内置的标准碰撞算法（例如球体对球体、盒体对盒体、凸多面体对凸多面体等）。它为底层的碰撞算法分配器提供策略支撑。

2. 碰撞分发器（btCollisionDispatcher）

以 btDefaultCollisionConfiguration 为构造参数。它的职责是细测阶段（Narrowphase）的碰撞调度：当系统发现两个物体的包围盒发生重叠时，分发器会检索对应的几何类型，调用具体的数学算法计算接触点（Contact Points）、碰撞法向量以及穿透深度（Penetration Depth），生成接触流形（Contact Manifolds）。

3. 粗测宽相位（btDbvtBroadphase）

全称是基于动态边界体积树（Dynamic Bounding Volume Tree）的粗测阶段接口。三维场景中如果有成百上千个物体，两两计算几何相交的时间复杂度是 O(n²)。Broadphase 使用动态 AABB 空间分割树，以极高效率过滤掉空间相距甚远的物体，仅将可能发生碰撞的“潜在对”传递给分发器。

4. 序列冲量约束求解器（btSequentialImpulseConstraintSolver）

Bullet 物理仿真真实感的数学核心。负责在离散时间步内，依据牛顿力学、能量守恒与阻尼系数，求解重力加速度、支撑接触反作用力、静摩擦力与动摩擦力，以及铰链、滑块等机械约束。

5. 离散动力学物理世界（btDiscreteDynamicsWorld）

物理系统的最高统筹者。构造函数严格按顺序接收：(dispatcher, broadphase, solver, collisionConfiguration)。它统领所有注册的刚体、幽灵对象（Ghost Objects）和约束，并在每帧步进中驱动上述构件协调工作。

四、完整实战：从零构建物理世界实例

下面给出可以在 Web 项目中直接复用的完整物理世界初始化函数。代码清晰展示了从等待模块就绪、实例化五大构件、配置重力向量，到构建仿真循环的基础闭环。

/**
 * 物理上下文封装对象
 */
class PhysicsContext {
  constructor(Ammo) {
    this.Ammo = Ammo;

    // 1. 实例化碰撞配置 (管理算法与内存分配)
    this.collisionConfiguration = new Ammo.btDefaultCollisionConfiguration();

    // 2. 实例化碰撞分发器 (依赖配置对象)
    this.dispatcher = new Ammo.btCollisionDispatcher(this.collisionConfiguration);

    // 3. 实例化粗测宽相位 (动态 AABB 树)
    this.broadphase = new Ammo.btDbvtBroadphase();

    // 4. 实例化约束求解器 (序列冲量求解器)
    this.solver = new Ammo.btSequentialImpulseConstraintSolver();

    // 5. 装配离散动力学世界 (注意参数顺序：分发器、粗测、求解器、配置)
    this.world = new Ammo.btDiscreteDynamicsWorld(
      this.dispatcher,
      this.broadphase,
      this.solver,
      this.collisionConfiguration
    );

    // 6. 设置物理世界的全局重力向量 (标准地球重力沿 Y 轴负方向 9.8 m/s²)
    const gravityVector = new Ammo.btVector3(0, -9.8, 0);
    this.world.setGravity(gravityVector);

    // 注意：传参完毕后释放临时向量，避免占用 WASM 内存
    Ammo.destroy(gravityVector);

    console.log("Bullet 物理世界装配完成，重力已设为 -9.8 m/s²");
  }

  /**
   * 物理时间步进更新
   * @param {number} deltaTime 距上一帧的实际流逝时间 (秒)
   */
  update(deltaTime) {
    if (this.world) {
      // 最大子步数设为 10，内部固定子步长为 1/60 秒
      this.world.stepSimulation(deltaTime, 10, 1 / 60);
    }
  }
}

关键参数解析：理解 stepSimulation 的运转方式

在渲染主循环（如 requestAnimationFrame）中，我们不能直接依赖不稳定的浏览器帧间隔来更新物理。如果用户屏幕发生掉帧，直接单步积分会导致物体穿透墙面。Bullet 的 stepSimulation 设计巧妙地解决了这一矛盾。

图 3：stepSimulation 物理时间步进与渲染管线同步机制

stepSimulation(deltaTime, maxSubSteps, fixedTimeStep) 接受三个参数：

1. deltaTime：外部渲染循环计算出的实际耗时。例如 60 FPS 时大约为 0.016 秒，发生卡顿时可能飙升至 0.05 秒。
2. maxSubSteps：引擎单帧允许插值计算的最大子步次数（默认常用 10）。当渲染掉帧较多时，引擎会在一帧内连续计算多个微小步长追平时间，但不会超过此限制，从而防止“掉帧引起物理过载，物理过载导致更严重掉帧”的死亡螺旋。
3. fixedTimeStep：内部固定仿真步长（默认 1/60 秒）。物理世界在此恒定粒度下进行刚体受力与碰撞解算，确保计算结果具备高度的物理确定性与可复现性。

五、内存释放：避免 WebAssembly 内存泄漏

由于 JavaScript 虚拟机的垃圾回收器完全无法感知由 new Ammo.bt*() 在 WebAssembly 线性堆中分配的 C++ 实例，如果销毁页面或重置关卡时只清空 JS 变量引用，WASM 内存占用将持续攀升，最终导致 RuntimeError: memory access out of bounds 崩溃。

显式释放必须遵从逆序销毁原则：即最后构造的高层依赖对象必须最先释放，底层基础配置最后释放。

/**
 * 完整逆序销毁物理世界及所有基础设施构件
 */
destroyPhysics(context) {
  const Ammo = context.Ammo;

  // 1. 先销毁物理世界总控实例
  Ammo.destroy(context.world);

  // 2. 销毁约束求解器
  Ammo.destroy(context.solver);

  // 3. 销毁粗测阶段索引树
  Ammo.destroy(context.broadphase);

  // 4. 销毁细测碰撞分发器
  Ammo.destroy(context.dispatcher);

  // 5. 最后释放碰撞基础配置内存池
  Ammo.destroy(context.collisionConfiguration);

  context.world = null;
  console.log("物理世界底层 C++ 内存已完全释放");
}

六、核心要点总结与排错对照

初学者在集成 ammo.js 时遇到的绝大多数 Bug 集中在异步加载时序、静态托管路径以及装配参数次序上。下表与图示梳理了关键组件的职责与高频报错的对策：

图 4：ammo.js 初始化要点与高频陷阱排查手册

完成物理世界的初始化后，您便可以在该世界中通过 btRigidBody 添加静态地面与动态物体，并在渲染循环中读取 btTransform 将三维刚体的位置和四元数旋转同步给 Three.js 或 Babylon.js 的网格。掌握了上述引入规范与装配逻辑，便为后续构建具备真实刚体碰撞、重力坠落及弹力物理交互的 Web 3D 项目奠定了坚实的基础。