更新记录

0.1.0（2026-07-19）

首发：自研高性能原生 2D 物理引擎核心，提供 uni-app 可调的 JS 对象 API：建一个世界、加刚体（圆/矩形/凸多边形/线段墙）、每帧 step 推进，原

平台兼容性

uni-app x(5.14)

nex-physics · 2D 物理引擎

自研高性能原生 2D 物理核心，提供 uni-app 可调的 JS 对象 API。

思路：原生侧算物理（重力/碰撞/关节/查询），JS 每帧只负责把图片画到对应像素坐标。比引入几兆且卡顿的 JS 物理引擎轻得多。

适用：抽奖转盘、金币掉落堆积、小球碰撞、弹球、轻量小游戏特效、营销活动页。

支持 App 端（Android / iOS） 与 H5 端（PhysicsWorld 全部 32 方法全量可用； H5 端建议应用启动时 await ensureReady() 一次）；小程序不支持。 uni-app x（uvue）与经典 uni-app（vue3）都可引入。

能力一览

• 世界：new PhysicsWorld(config) / step（每帧推进，返回所有刚体变换）/ transforms / getTransform / setGravity / bodyCount / clear
• 刚体：addBall / addBox / addPolygon（凸多边形）/ addWall（静态线段墙）/ removeBody / bodyExists
• 操控：速度 setLinearVelocity/getLinearVelocity/setAngularVelocity/getAngularVelocity、冲量/力 applyImpulse/applyTorqueImpulse/applyForce/applyTorque、setTransform（瞬移）、setBodyType、wakeUp、setRestitution/setFriction
• 关节：addRevoluteJoint（铰链，含马达/限位）/ addFixedJoint（焊接）/ addPrismaticJoint（滑轨）/ removeJoint
• 查询：castRay（射线）/ pointQuery（点）/ queryAabb（矩形范围）
• 事件：drainEvents（碰撞开始/结束，需 enableEvents）

约定（重要）

• 单位用像素（位置/速度/尺寸/冲量），内部按 pixelsPerMeter 换算为物理世界的米。
• y 轴向下（屏幕坐标系），重力默认 gravityY: 980（正值 = 下落），与 CSS/canvas 一致。
• 角度用弧度。
• step() 返回扁平数组 [handle, x, y, angle] × N，按 4 个一组拆。
• addXxx 返回一个 number 句柄，后续操控/查询都用它。

最小用法（金币掉落）

import { PhysicsWorld } from '@/uni_modules/nex-physics';

const w = new PhysicsWorld({ gravityY: 980 });
w.addWall({ x1: 20, y1: 600, x2: 355, y2: 600 });   // 地面
w.addWall({ x1: 20, y1: 100, x2: 20, y2: 600 });    // 左墙
w.addWall({ x1: 355, y1: 100, x2: 355, y2: 600 });  // 右墙

const sizeOf = new Map<number, number>();
for (let i = 0; i < 30; i++) {
  const h = w.addBall({ bodyType: 'dynamic', x: 40 + (i * 37) % 300, y: 80, radius: 14, restitution: 0.2 });
  sizeOf.set(h, 28); // 直径，用于渲染
}

// 每帧（uvue 用 setInterval，经典 uni-app 可用 requestAnimationFrame）：
function frame() {
  const t = w.step(16.6667);          // [handle,x,y,angle] × N
  for (let i = 0; i < t.length; i += 4) {
    const handle = t[i], x = t[i + 1], y = t[i + 2], angle = t[i + 3];
    // 把 handle 对应的 sprite 画到 (x, y) 中心、旋转 angle 弧度
  }
}

完整 API、错误码、三场景配方（转盘/金币/弹球）见仓库 docs/physics-plugin-contract.md。

错误处理

addXxx / 操控 / 查询在参数非法或 handle 不存在时会 throw（InvalidParam / NotFound / TooManyBodies / TooManyVertices），调用方按需 try/catch。所有非法数值（NaN/Inf、半径≤0、非凸多边形）都被挡在边界，绝不闪退。

打包

最终 App 打包需在 HBuilderX / @dcloudio CLI 完成（App 端含原生库，需自定义基座或云打包）。