跳转到内容
Estella

物理

物理系统提供基于独立 Box2D WASM 模块的 2D 刚体模拟。编辑器和构建流程会自动处理模块加载——你只需在设置中启用物理并为实体添加组件。

设置

在编辑器中启用物理：Settings → Physics → Enable Physics。

在同一面板中配置模拟参数：

设置项默认值说明
Gravity X0水平重力
Gravity Y-9.81垂直重力（负数 = 向下）
Fixed Timestep1/60物理步进间隔（秒）
Sub-Step Count4每次物理步进的子步数，用于提高精度
Contact Hertz30接触刚度（周期/秒）。越高穿透越少但抖动越明显。范围：1–500
Contact Damping Ratio10接触弹性阻尼。越低重叠恢复越快但弹性越强。范围：0.1–100
Contact Speed3最大重叠修正速度（米/秒）。范围：1–100

坐标转换 (PPU)

碰撞体尺寸（halfExtents、radius、halfHeight）以**物理单位（米）**设定。Canvas 组件的 pixelsPerUnit（默认 100）决定像素坐标与物理坐标之间的换算比例。

位置转换自动完成——实体位置（像素）在发送到 Box2D 时除以 PPU，读回时乘以 PPU。Physics API 的值（force、velocity、impulse、gravity）同样使用物理单位，无需手动换算。

刚体类型

Static（0）

不移动。用于墙壁、地面和平台。

rigidBody.bodyType = 0;

Kinematic（1）

通过代码（变换）移动，不受物理力影响。其他刚体会与之碰撞但不会推动它。用于移动平台和电梯。

rigidBody.bodyType = 1;

Dynamic（2）

完全模拟。响应重力、力和碰撞。用于玩家、投射物和物理对象。

rigidBody.bodyType = 2;

组件

在场景编辑器中将物理组件与 Transform 一起添加到实体上。每个物理实体需要一个 RigidBody 和至少一个碰撞体。

示例：简单平台跳跃

在编辑器中设置地面、玩家和金币传感器，然后用代码处理事件：

import { defineSystem, addSystem, Res, Input, Query, Mut, Transform } from 'esengine';
import { RigidBody, PhysicsEvents } from 'esengine/physics';
import { Player, Coin } from './components';


addSystem(defineSystem(
    [Res(PhysicsEvents)],
    (events) => {
        for (const e of events.sensorEnters) {
            // 金币收集
        }
    }
));

编辑器设置：

  • 地面：Transform + RigidBody（bodyType=0 Static）+ BoxCollider（halfExtents={x:10, y:0.5}）+ Sprite
  • 玩家：Transform + RigidBody（bodyType=2 Dynamic，fixedRotation=true）+ BoxCollider + Sprite + Player 标签
  • 金币：Transform + RigidBody（bodyType=0 Static）+ CircleCollider（isSensor=true）+ Sprite + Coin 标签

下一步