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.jsRapier.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理解下面四层后,出问题时能快速定位到是哪一层:Rust 核心:碰撞检测、约束求解等算法,与运行环境无关;WASM 层:核心编译为 wasm 模块,即 npm 包内随附的 .wasm 文件;TypeScript 接口层:仓库src.ts/下按dynamics/、geometry/、pipeline/、control/分模块封装,World类聚合刚体集、碰撞器集、关节集与求解管线;应用层:仓库内置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 优化 / 跨平台确定性时,再换变体。包(2D/3D 规则相同)SIMD 优化跨平台确定性适用场景影响dimforge/rapier2d/rapier3d❌❌(仅单机一致)默认选择体积最小,浏览器支持面最广*-simd✅❌性能优先场景要求浏览器支持 SIMD128*-deterministic❌✅联网同步、锁步回放性能略低于默认包以上任意 -compat同基础包同基础包打包器无法单独处理 .wasm体积增大(wasm 以 base64 内嵌),打包兼容性最好三、最短路径:安装与最小示例安装 Rapier.js✅ 在 Node 项目中安装 2D 版(3D 项目把 2d 换成 3d):npm install dimforge/rapier2d # 执行耗时预估:10~30 秒,取决于网络⚠️ 若后续打包时出现找不到或无法解析 .wasm 文件类报错,说明打包器不支持独立 wasm 资产,改装dimforge/rapier2d-compat即可。最小可运行示例脚本创建一个固定地面,让 0.5×0.5 的方块从 y5 处落下,模拟 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 }左右——地面顶面在 y0.5,方块半高 0.5,落稳后中心约在 y1。结果偏大的排查:若 y 仍明显大于 1(比如 3),多半是await RAPIER.init()未完成就创建了 World,或 step 时 wasm 尚未就绪;若控制台直接抛 wasm 相关错误,先核对包版本与 Node 版本是否匹配。对照官方 demotestbed2d/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考