详解 Matter.js 核心架构：Engine、World 与 Body 的关系

一、核心架构层级：包含关系与数据流转拓扑

初学 Matter.js 时，很多人会将 Engine、World 和 Body 视为并列的同级对象，或者混淆它们在主循环中的职责。实际上，它们在内存组织上遵循严格的树状所有权模型（Ownership Hierarchy），而在物理计算上则通过流水线数据流（Pipeline Data Flow）进行协作。

从数据结构的角度来看：

• Engine 是顶层的主机实例（Host Instance）：当我们通过 Matter.Engine.create() 创建引擎时，系统内部会自动为其分配一个专门的 world 属性（即 engine.world）。Engine 本身并不保存任何单独的刚体或力学约束，它通过持有 World 实例来感知整个物理世界。
• World 是特化的复合容器（Composite Root）：在 Matter.js 源码实现中，World 并非完全独立的物理实体，其实质是一个根级别的 Matter.Composite 容器。World 负责汇聚和组织所有的 Body（刚体）、Constraint（关节约束）以及可能存在的嵌套子复合体（Sub-Composite）。
• Body 是力学计算的最小原子单元（Physics Primitive）：Body 记录了单个物理实体的具象属性，包括质心坐标、线速度、角速度、旋转角度、多边形凸包顶点集合、碰撞分组过滤掩码以及反弹系数等。Body 必须被注册进 World 容器树后，才能被 Engine 捕获并参与每帧的物理求解。

它们之间的数据与控制流向遵循“时钟触发 → 遍历容器 → 碰撞解算 → 更新刚体”的单向循环回路。如下图所示：

如图 1 所示，Engine 与 World 是“控制者与被驱动数据”的关系，World 与 Body 则是“容器与叶子节点”的包含关系。外部的时钟驱动（如 Runner 模块）向 Engine 灌入时间步进脉冲，Engine 读取 engine.world 中所有的刚体，经过碰撞与求解流水线计算后，将全新的速度与坐标写回 Body 实例中。最后，表现层（如 Render 模块或自定义 WebGL/Canvas 渲染器）以只读方式提取 Body 的最新状态完成画面重绘。

二、Engine（引擎）：物理仿真的驱动核心与计算管线

Engine 是 Matter.js 物理世界的大脑。它的主要职责并非保存几何外形，而是掌控时间的推移，并协调底层各个数学解算子系统（包含宽相粗筛、窄相碰撞检测、冲量迭代求解器与半隐式数值积分）。

1. Engine 的核心配置参数

在创建 Engine 实例时，开发者可以通过配置选项精准调控仿真的精度与性能表现：

• positionIterations（位置解算迭代次数，默认值为 6）：在每次物理步进中，求解器修正刚体间重叠穿透的循环次数。若场景中存在高速运动物体或堆叠场景容易穿模，可将其提升至 8 ~ 10。
• velocityIterations（速度解算迭代次数，默认值为 4）：在碰撞法线上计算弹性反冲与摩擦冲量的循环迭代次数。
• enableSleeping（休眠优化开关，默认值为 false）：启用后，当某些刚体的线速度与角速度在若干帧内均低于设定阈值时，引擎会将其置为“休眠（Sleeping）”状态，跳过窄相碰撞与受力积分，从而显著降低大场景下的 CPU 开销。
• timing.timeScale（时间流速缩放，默认值为 1.0）：用于实现物理世界的慢动作（例如设为 0.5）或快进效果。

2. 物理步进的执行流水线（Pipeline）

每次调用 Engine.update(engine, delta) 时，引擎内部都会依次执行严格的六个阶段计算。理解这个计算推导流程，是排查物体穿模、抖动和事件监听异常的核心关键：

该流水线的关键处理逻辑如下：

1. 触发 beforeUpdate 事件：引擎向外广播前置钩子。如果开发者需要在当前物理帧根据外部用户输入施加外力（如按键跳跃施加冲量），必须在此阶段通过 Body.applyForce 注入，以便该外力被完整计入后续的动量积分。
2. Broadphase（宽相粗筛）：当场景内存在成百上千个刚体时，两两比对几何碰撞的时间复杂度高达 O(N²)。Broadphase 通过轴对齐包围盒（AABB）和网格划分算法，快速排除在空间上毫无重叠可能的刚体对，只输出可能相交的候选配对（Pairs）。
3. Narrowphase（窄相精算）：针对筛选出的候选对，检查两者的 collisionFilter 碰撞掩码。若允许碰撞，则使用分离轴定理（Separating Axis Theorem, SAT）沿着各多边形法线测定重叠深度，并精确定位接触点（Contacts）。
4. Resolver（约束与冲量求解器）：采用顺序脉冲算法（Sequential Impulses）。依据物体的质量反比（inverseMass）、恢复系数（restitution）与摩擦力（friction），在多次迭代中逐步解算出接触法线上的反冲冲量和切线上的摩擦冲量，同时拉伸或收缩弹性约束（Constraints）。
5. Integration（辛欧拉数值积分）：将最终合外力转化为加速度，利用半隐式欧拉方法推进线速度与角速度，并结合空气阻力（frictionAir）衰减，最后累加得出刚体的新位置（position）和旋转角（angle）。
6. afterUpdate 与休眠检测：更新刚体状态，判断物体是否满足静止休眠条件，清空单帧外力累加器，并触发后置更新事件。

三、World（世界）：基于 Composite 的实体拓扑容器

在 Matter.js 中，World 本质上是一个 Composite（复合体）。官方源码中 Matter.World.create() 的内部实现其实就是 Composite.create({ label: 'World' })。因此，掌握 World 的核心就是理解 Matter.js 的组合模式（Composite Pattern）。

1. Composite 容器的树状组织模型

World 作为顶层复合容器，其内部可以容纳三类实体：

• 直接刚体（Bodies）：场景中的固定墙壁、运动小球、地面等基本刚体。
• 物理约束（Constraints）：用于在两个刚体之间（或刚体与固定点之间）建立弹簧、铰链、绳索或销钉连接。
• 子复合体（Sub-Composites）：可以将多个刚体与约束组合成一个语义单元。例如，一辆机械小车可以封装为一个独立的 Composite，包含车身底盘刚体、两个车轮刚体以及连接车轮与车身的轮轴约束。随后将该小车 Composite 整体加入 engine.world。

2. World 空间级属性配置

作为整个仿真场景的物理环境容器，World 承担了空间级别的物理环境设定，其中最关键的是全局重力矢量：

// 获取并配置全局重力
engine.world.gravity.x = 0;         // 水平重力分量
engine.world.gravity.y = 1;         // 垂直重力方向（正数向下）
engine.world.gravity.scale = 0.001; // 重力加速度缩放系数

当需要模拟失重太空环境时，只需将 engine.world.gravity.scale = 0；若需要实现类似反重力机关，直接反转 world.gravity.y = -1 即可作用于世界中的所有动态物体。

3. 现代 API 演进与操作规范

在早期教程中，常见写法为 World.add(engine.world, body)。但在现代 Matter.js 版本中，官方推荐统一使用 Matter.Composite 提供的标准方法操作实体，这不仅语义更严谨，而且适用于树状层级的任意嵌套节点：

• Composite.add(engine.world, [item1, item2])：向世界容器中注入刚体、约束或子复合体，支持单对象或数组批量传入。
• Composite.remove(engine.world, targetBody)：从容器中彻底移除目标实体。此时引擎会自动同步清理 engine.pairs 中涉及该实体的所有碰撞缓存，防止内存泄漏。
• Composite.allBodies(engine.world)：递归深度遍历整个复合体树，获取场景内所有最底层的叶子刚体列表，常用于全局遍历统计或碰撞排查。
• Composite.clear(engine.world, false)：在关卡切换或场景重置时，清空容器内的一切实体。

四、Body（刚体）：动力学与几何特性的基本承载单元

Body 是物理世界中真正受力、发生位移与相互碰撞的几何实体。所有可视化的弹跳、摩擦、旋转与阻挡效果，最终都落实于 Body 对象的属性与状态改变。

1. 核心属性归类解析

2. 刚体状态干预的规范操作流（生命周期）

刚体在运行时的状态修改是最容易引发仿真 Bug 的环节。很多开发者习惯像修改普通 DOM 或三维对象那样，直接编写 body.position.x += 10。这是严重的误区！

Matter.js 内部采用半隐式辛欧拉（Semi-implicit Euler）数值积分，刚体的速度是通过前后两帧的坐标差分与加速度共同推算的。直接修改 body.position.x 会破坏历史位置差分缓存（positionPrev），导致引擎在下一个时间步算出一个极大的瞬时虚拟速度，物体会瞬间震荡、甚至剧烈飞出屏幕；同时，多边形顶点 vertices 与空间索引 bounds 也未能得到同步刷新，极易造成穿模。

如上图所示，规范干预 Body 的唯一途径是调用 Matter.Body 提供的工具函数：

• 安全瞬移位置：必须使用 Matter.Body.setPosition(body, { x, y })。该方法不仅会重写坐标，还会自动调用 Vertices.translate 更新所有的凸包顶点，并重新计算空间 bounds。
• 安全赋予线速度：必须使用 Matter.Body.setVelocity(body, { x: vx, y: vy })，直接改写速度向量并同步更新内部前序位置。
• 连续物理推力：推荐在 beforeUpdate 事件中使用 Matter.Body.applyForce(body, position, force)。引擎会将推力累加到刚体内部，在积分阶段平滑加速。

五、实战工程范式：初始化、关联与运行的完整代码

下面提供一份完全遵循现代 Matter.js 架构规范的完整代码示例。示例演示了如何创建 Engine，配置 World 重力与边界，组装不同类型的 Body 和 Constraint，并由 Runner 启动物理模拟：

// 1. 结构化解构引入 Matter.js 核心模块
const {
  Engine,
  Render,
  Runner,
  Bodies,
  Composite,
  Constraint,
  Body,
  Events
} = Matter;

// 2. 创建物理引擎实例 (Engine)
const engine = Engine.create({
  positionIterations: 6, // 位置求解迭代，防止穿透
  velocityIterations: 4, // 速度求解迭代，保证弹性稳定
  enableSleeping: true   // 开启静止物体休眠以节省计算资源
});

// 3. 配置空间容器 (World) 的全局物理常数
const world = engine.world;
world.gravity.y = 1;     // 设置常规垂直重力
world.gravity.scale = 0.001;

// 4. 创建刚体实体 (Body)
// 4.1 静态场景边界刚体 (isStatic: true)
const ground = Bodies.rectangle(400, 590, 810, 40, {
  isStatic: true,
  render: { fillStyle: '#345E82' }
});

const leftWall = Bodies.rectangle(5, 300, 20, 600, { isStatic: true });
const rightWall = Bodies.rectangle(795, 300, 20, 600, { isStatic: true });

// 4.2 自由落体动态刚体 (Dynamic Bodies)
const dynamicBox = Bodies.rectangle(350, 100, 60, 60, {
  restitution: 0.6, // 弹性系数
  friction: 0.2,    // 表面摩擦
  density: 0.002
});

const ball = Bodies.circle(450, 80, 25, {
  restitution: 0.8,
  frictionAir: 0.005 // 空气阻力
});

// 4.3 物理约束 (Constraint): 建立绳索摆锤
const anchorPoint = { x: 450, y: 50 };
const pendulumPin = Constraint.create({
  pointA: anchorPoint,
  bodyB: ball,
  stiffness: 0.9,
  damping: 0.05
});

// 5. 将刚体与约束统一注册到 World 容器中
Composite.add(world, [ground, leftWall, rightWall, dynamicBox, ball, pendulumPin]);

// 6. 运行与事件监听
// 6.1 注册 beforeUpdate 事件，演示规范施加外力
Events.on(engine, 'beforeUpdate', (event) => {
  // 仅在特定条件下给 dynamicBox 施加向右上的微小推力
  if (dynamicBox.position.y > 500) {
    Body.applyForce(dynamicBox, dynamicBox.position, { x: 0.005, y: -0.01 });
  }
});

// 6.2 监听碰撞事件
Events.on(engine, 'collisionStart', (event) => {
  const pairs = event.pairs;
  pairs.forEach(pair => {
    if ((pair.bodyA === dynamicBox && pair.bodyB === ground) ||
        (pair.bodyB === dynamicBox && pair.bodyA === ground)) {
      // 成功捕获指定刚体间的碰撞
      // console.log('DynamicBox 接触地面');
    }
  });
});

// 7. 启动时钟驱动器 (Runner)
const runner = Runner.create();
Runner.run(runner, engine);

// 8. 视图层渲染 (Render 模块仅负责绘制展示，与物理逻辑完全解耦)
const render = Render.create({
  element: document.body,
  engine: engine,
  options: {
    width: 800,
    height: 600,
    wireframes: false, // 启用实体颜色填充
    background: '#F2F6FA'
  }
});
Render.run(render);

六、架构协作关系与高频问题排查总结

为了在工程开发中能够快速定位问题，我们将 Engine、World 和 Body 的核心职责、典型 API 与协作边界整理为全景蓝图：

常见疑难问题排查清单（Troubleshooting）

• 问题一：高速运动物体发生穿墙/穿模（Tunneling 穿透现象）
  原因分析：Matter.js 默认采用离散时间步检测（Discrete Collision Detection）。如果物体在一个时间步内的位移大于障碍物的厚度，AABB 与 SAT 判定均无法捕捉到重叠。
  解决对策：
  1. 避免使用厚度极小的墙体，将边界刚体的厚度增加至 30px ~ 60px 以上；
  2. 提升 engine.positionIterations（如调至 8 ~ 12），并在 Runner 步长较长时缩小 delta；
  3. 针对极高速的子弹类小刚体，可在配置中启用 bullet: true 提升连续碰撞检测倾向。
• 问题二：刚体移除后依然发生神秘碰撞或内存占用持续攀升
  原因分析：仅仅在业务代码中执行 myBody = null，并没有将其从物理世界的 Composite 树中剥离，Engine 依然在每帧轮询该刚体并保留其碰撞配对缓存。
  解决对策：必须显式调用 Composite.remove(engine.world, myBody)。如果要清空整个关卡场景，必须调用 Composite.clear(engine.world, false)。
• 问题三：刚体在受到外力或修改位置时发生剧烈弹飞或抖动
  原因分析：直接对 body.position.x 或 body.angle 进行数值递增赋值，导致速度微分器失效。
  解决对策：立即全局搜索代码，将所有直接修改 position 的赋值语句重构为 Matter.Body.setPosition()、Matter.Body.setVelocity() 或 Matter.Body.applyForce()。