#moonphys

let world = @moonphys.World::new()

// 静态地面
ignore(
  world.add_body(
    @moonphys.Body::fixed(@moonphys.Shape::box(10.0, 0.1)).at(0.0, -0.1),
  ),
)

// 一个自由下落的方块
ignore(world.add_body(@moonphys.Body::box(0.5, 0.5).at(0.0, 4.0)))

// 固定步长推进 2 秒
for _ in 0..<120 {
  world.step(1.0 / 60.0)
}

println(world.body(1).position().y()) // 0.5：稳稳落在有厚度的地面上

#特性

#安装

moon add weopqrst/moonphys

import {
  "weopqrst/moonphys" @moonphys,
}

#五分钟上手

// main.mbt
fn main {
  let world = @moonphys.World::builder()
    .ground(20.0)                        // 静态地面，上表面 y = 0
    .ball(0.4, 0.0, 6.0)                 // 半径 0.4，位于 (0, 6)
    .box(0.5, 0.5, 1.5, 8.0)             // 半宽 0.5、半高 0.5
    .body(@moonphys.Body::ball(0.3).at(-2.0, 9.0).with_restitution(0.8))
    .build()
  for _ in 0..<240 {
    world.step(1.0 / 60.0)
  }
  println(world.snapshot_json())          // 直接喂给前端/回放
}

moon run examples/bounce      # 20 行：弹球落地，逐步打印位置与速度
moon run examples/pyramid     # 金字塔随动能衰减整体入睡
moon run examples/ragdoll     # 四段布娃娃，铰链连成的链条

let world = @moonphys.World::new()
let a = world.add_body(@moonphys.Body::box(0.2, 0.05).at(0.0, 5.0))
let b = world.add_body(@moonphys.Body::box(0.2, 0.05).at(0.4, 5.0))
world.add_revolve_joint(a, b, @moonphys.Vec2::new(0.2, 5.0))

#演示

moon run cmd/main --target js > docs/index.html

1. Pyramid stack — 6 层 21 个方块的金字塔，左上方斜面滚球（摩擦），三颗弹球砸下来。
2. Five link chain · double pendulum — 5 节链条与双摆，铰链约束在重力下的混沌运动。
3. Linear actuator · angular motor · soft rope — 电动滑轨推箱、角马达带动的旋转臂与软弹簧绳、重力压在角限位上的跷跷板。

#可交互 playground（wasm-gc）

python -m http.server 8123        # 仓库根目录
# 浏览器打开 http://127.0.0.1:8123/docs/playground/

powershell -File tools/build-playground.ps1   # 或 bash tools/build-playground.sh
node tools/check-playground.mjs               # 校验 24 个导出 + 6 场景各 180 步

#API 速览

// 世界
let world = @moonphys.World::new()                 // 重力默认 (0, -9.81)
world.set_gravity(@moonphys.Vec2::new(0.0, -3.0))  // 低重力
world.set_velocity_iterations(10)                  // 迭代次数，越大越硬
world.set_sleep_enabled(true)
world.step(1.0 / 60.0)                             // 固定步长
world.run(120, 1.0 / 60.0)                         // 等价于循环 step
world.time()                                       // 累计仿真时间
world.arbiter_count()                              // 当前接触对
world.snapshot()                                   // 渲染/测试用的不可变快照
world.snapshot_json()                              // 同上，序列化成 JSON
world.state_hash()                                 // 状态指纹，用于确定性回归

// 链式建场景（等价于逐个 add_body）
@moonphys.World::builder()
  .gravity(0.0, -9.81).iterations(10).sleep_enabled(true)
  .ground(20.0).ball(0.4, 0.0, 4.0).box(0.5, 0.5, 1.0, 6.0)
  .body(some_preconfigured_body)
  .build()

// 刚体
let body = @moonphys.Body::box(0.5, 0.5)           // 动态方块
  .at(0.0, 3.0)                                    // 质心位置
  .with_rotation(0.3)                              // 弧度
  .with_velocity(1.0, 0.0)
  .with_angular_velocity(-0.5)
  .with_friction(0.6)
  .with_restitution(0.2)                           // 弹性
  .with_density(1.0)                               // 质量 = 密度 × 面积
  .with_damping(0.05, 0.05)                        // 线/角阻尼
  .with_allow_sleep(true)
  .with_user_data(3)                               // 渲染配色用的自定义标记
ignore(world.add_body(body))

// 形状
@moonphys.Shape::box(0.5, 0.5)                     // 半宽半高
@moonphys.Shape::circle(0.4)
@moonphys.Shape::convex(vertices)                  // 逆时针凸多边形

// 力与冲量
body.apply_force(@moonphys.Vec2::new(0.0, 10.0))   // 本步有效
body.apply_impulse(@moonphys.Vec2::new(2.0, 0.0), body.position())
body.point_velocity(body.position())

// 查询
body.mass(); body.inertia(); body.aabb(); body.contains_point(p)
body.local_to_world(p); body.world_to_local(p)

// 关节
world.add_distance_joint(index_a, index_b)                     // 保持当前中心距
world.add_revolve_joint(index_a, index_b, @moonphys.Vec2::new(0.0, 5.0)) // 世界锚点
world.add_revolve_joint_local(a, b, local_a, local_b)          // 各自的局部锚点
world.add_prismatic_joint(a, b, anchor, axis)                  // 滑轨，可 .with_limits/.with_motor
world.add_angle_limit_joint_at(a, b, anchor, -0.6, 0.6)        // 绕锚点的角限位
world.add_motor_joint(a, b, 2.0, 200.0)                        // 目标角速度, 最大力矩
world.add_soft_distance_joint(a, b, 4.0, 1.0)                  // 频率 Hz, 阻尼比

#实现要点

1. 同步 AABB → 宽相配对（复用上一帧的排序数组与 pair 缓冲区）
2. 窄相生成接触点；命中已有 Arbiter 则按 feature id 迁移旧冲量（暖启动），否则新建
3. 积分重力、外力、阻尼，清除累积力
4. 每个 Arbiter / 关节计算有效质量与偏置
5. 迭代 velocity_iterations 次求解速度约束
6. 积分位置 → 更新睡眠状态 → 同步 AABB

#性能

moon run bench --target js        # 或 --target wasm-gc

1. 宽相：原先每步重建数组并整表插入排序，改为跨帧复用排序结果 + 近序插入排序，并把持久接触的查找从「每条 pair 扫全部 arbiter」改成按低位 body 下标分桶。方块塔从 0.62 → 0.50 ms/step，摘要不变（说明只是变快，没有改变轨迹）。
2. 唤醒策略：原先「邻居醒着就唤醒我」会让堆里的第一个入睡者每步被邻居惊醒，整堆永远睡不下去；改成邻居必须真的在移动（速度超过睡眠阈值）才唤醒后，静置的堆会整体入睡、不再参与求解，方块塔因此降到 0.40 ms/step。

#测试

moon test                # 64 项
moon test --target js    # 同一套断言在 JS 后端上再跑一遍
node tools/check-playground.mjs    # playground 的 wasm：24 个导出 + 6 场景各 180 步
powershell -File tools/acceptance.ps1   # 模拟验收：克隆仓库 + 从 mooncakes 装包，各跑一遍

#移植来源与许可

• Box2D-Lite — Erin Catto，https://github.com/erincatto/box2d-lite （MIT）：Arbiter/顺序冲量、裁剪式多边碰撞的经典教学实现
• Box2D — Erin Catto，https://github.com/erincatto/box2d （MIT）：宽相、睡眠、关节的工业级参考
• Planck.js — Ali Shakiba，https://github.com/shakiba/planck.js （MIT）：JavaScript 移植版，本文的 API 风格参考