Rapier.js 物理引擎快速上手指南

Rapier.js 物理引擎快速上手指南

【免费下载链接】rapier.jsOfficial JavaScript bindings for the Rapier physics engine ⚠️ MIGRATED TO https://github.com/dimforge/rapier/tree/master/typescript ⚠️项目地址: https://gitcode.com/gh_mirrors/ra/rapier.js

Rapier.js 是 Rapier 物理引擎的官方 JavaScript 绑定:物理核心用 Rust 实现,编译为 WebAssembly 在浏览器和 Node.js 中运行,提供 2D/3D 刚体动力学、碰撞检测、关节约束与射线查询等能力。适合做网页小游戏、交互式物理演示,或需要多端一致的物理模拟。当前 npm 稳定版为 0.19.3(2025 年 11 月发布,对应 Rapier 0.30.0 核心)。

⚠️ 仓库的源码开发已并入 rapier 主仓库的 typescript 目录,本仓库主要维护 npm 发布线。按本文安装 npm 包即可,绝大多数场景无需从源码构建。

一、能力速览:Rapier.js 能做什么

📌完整刚体动力学:dynamic / fixed / kinematic 三种刚体,含休眠与唤醒、CCD 连续碰撞检测、可配置积分步长。 📌丰富几何体:2D 支持圆、凸多边形、长方体、折线;3D 支持球、长方体、凸包、三角网格、高度场与体素,其中体素采用稀疏存储以支持超大地图。 📌关节与控制器:冲量关节、多体关节(含六自由度),以及 KinematicCharacterController 角色控制器、PidController;3D 版额外提供射线车辆控制器。 📌查询与事件:世界射线投射、形状投射、接触事件队列,配合物理钩子可实现自定义碰撞回调。

分层架构:Rust 核心如何变成 JS API

理解下面四层后,出问题时能快速定位到是哪一层:

1. Rust 核心:碰撞检测、约束求解等算法,与运行环境无关;
2. WASM 层:核心编译为 wasm 模块,即 npm 包内随附的 .wasm 文件;
3. TypeScript 接口层:仓库src.ts/下按dynamics/、geometry/、pipeline/、control/分模块封装,World类聚合刚体集、碰撞器集、关节集与求解管线;
4. 应用层:仓库内置testbed2d/与testbed3d/演示工程,两个目录合计 20 多个可直接参考的场景。

二、环境自检与 npm 包选型

环境自检命令

✅ 确认 Node 与 npm 版本,建议 Node 16 LTS 以上(对应 npm 8+):

node -v # [Windows/macOS/Linux] npm -v

预期输出:v16.x 或更高、npm 8.x 或更高。npm 包内已附带编译好的 wasm,无需安装 Rust 或 wasm 工具链。

六个 npm 变体怎么选

📌原则:默认包覆盖绝大多数场景;只有在打包器处理不了 .wasm 文件,或明确需要 SIMD 优化 / 跨平台确定性时,再换变体。

三、最短路径:安装与最小示例

安装 Rapier.js

✅ 在 Node 项目中安装 2D 版(3D 项目把 2d 换成 3d):

npm install @dimforge/rapier2d # 执行耗时预估:10~30 秒,取决于网络

⚠️ 若后续打包时出现"找不到或无法解析 .wasm 文件"类报错,说明打包器不支持独立 wasm 资产,改装@dimforge/rapier2d-compat即可。

最小可运行示例

脚本创建一个固定地面,让 0.5×0.5 的方块从 y=5 处落下,模拟 1 秒后打印落点。保存为 demo.mjs(ESM 支持顶层 await):

import RAPIER from "@dimforge/rapier2d"; await RAPIER.init(); // 必须先完成 WASM 异步初始化 const world = new RAPIER.World(new RAPIER.Vector2(0, -9.81)); const ground = world.createRigidBody(RAPIER.RigidBodyDesc.fixed()); world.createCollider(RAPIER.ColliderDesc.cuboid(10, 0.5), ground); const box = world.createRigidBody( RAPIER.RigidBodyDesc.dynamic().setTranslation(0, 5) ); world.createCollider(RAPIER.ColliderDesc.cuboid(0.5, 0.5), box); for (let i = 0; i < 60; i++) world.step(); // 默认步长 1/60,共 1 秒 console.log("落点:", box.translation()); world.free(); // 释放整个世界占用的 WASM 内存

四、跑通示例:核对输出与官方 demo

核对最小示例输出

预期输出:{ x: 0, y: 1 }左右——地面顶面在 y=0.5,方块半高 0.5,落稳后中心约在 y=1。

📌结果偏大的排查:若 y 仍明显大于 1(比如 >3),多半是await RAPIER.init()未完成就创建了 World,或 step 时 wasm 尚未就绪;若控制台直接抛 wasm 相关错误,先核对包版本与 Node 版本是否匹配。

对照官方 demo

testbed2d/src/demos/与testbed3d/src/demos/下有 20 多个现成场景(立方体堆叠、关节、CCD、角色控制器、高度场、体素等),是核对 API 用法的最快参照。本地运行需先构建 wasm,依赖 Rust + wasm 工具链:

git clone https://gitcode.com/gh_mirrors/ra/rapier.js # 按根目录 README 执行 builds/prepare_builds/ 下两个准备与构建脚本,再: cd rapier.js/testbed2d && npm install && npm start # 执行耗时预估:首次 wasm 构建约 3~10 分钟,取决于机器

浏览器打开后切换到目标 demo 即可肉眼核对物理行为;2D 版基于 PixiJS 渲染,3D 版基于 WebGL。

五、避坑清单与进阶调优

高频坑

📌忘记 await init():WASM 是异步加载的;仓库测试rapier-compat/tests/World2d.test.ts里beforeAll(init)就是这个原因,未初始化就创建 World 会拿到未就绪实例。 📌确定性误解:默认包只保证同一台机器上结果一致;做联机同步必须换-deterministic变体,否则不同浏览器会算出不同轨迹。 📌大地图内存:0.19.1 起体素改用稀疏存储,可避免触及 WASM 4GB 内存上限;超大世界可调用reserveMemory()预扩容,减少运行期内存重分配。 📌释放时机:多世界并存时用world.free()整体释放,无需逐个释放子对象;已 free 的 world 再访问会直接崩溃。

进阶:性能观测与调参

📌内置性能统计:设置World.profilerEnabled = true后,用World.timing*系列方法读取碰撞、求解等阶段耗时,先定位瓶颈再调参。 📌调参位置:时间步长在world.integrationParameters上修改;World.maxCcdSubsteps(0.18.0 起可读写)控制 CCD 子步上限,高速小物体穿透时优先检查它。 📌版本红利:0.27.0 重写了宽相位,大场景不再需要每帧重建加速结构;升级前先看仓库CHANGELOG.md,注意 0.19.0 移除了旧 PGS 求解器相关 API。

如果你接下来要做角色移动,建议直接读testbed2d/src/demos/characterController.ts,把 KinematicCharacterController 接进自己的输入逻辑;做 3D 联机则直接上-deterministic变体加固定步长,先锁住一致性,再谈性能优化。

【免费下载链接】rapier.jsOfficial JavaScript bindings for the Rapier physics engine ⚠️ MIGRATED TO https://github.com/dimforge/rapier/tree/master/typescript ⚠️项目地址: https://gitcode.com/gh_mirrors/ra/rapier.js