nape-js

面向 TypeScript 和 JavaScript 的完全类型化 2D 物理引擎——Nape 的现代化重写

刚体 • 圆形、多边形与胶囊体 • 约束 • 流体模拟 • 碰撞回调 • 射线检测与空间查询 • 断裂 • 基于约束的软体 • 确定性多人同步 • 序列化 • Web Worker 支持 —— 零依赖、约 174 KB gzip。

v3.43.5 约 175 KB gzip
npm install @newkrok/nape-js

交互式演示

在画布上点击/拖动即可交互。请在下方选择一个演示。 物理 游戏

正在加载引擎…
FPS: — 刚体数: — 步进: —
源代码

最新完整游戏演示

基于该引擎的最新多系统游戏——AI、波次、摄像机和 3D 骨架,每个都是可在 CodePen 打开的单个文件。

Hitch & Park — gameplay screenshot开始 →

完整游戏Hitch & Park

一款俯视视角的拖车停车游戏:五个场景——超市停车场、立体停车楼、码头下水坡道、商业街、露营地——每处都有一个标记车位,拖车必须停进去,车头朝外、摆正、停稳。停着的车可以被顶开(它们的双闪会出卖你),锥桶会被撞倒,柱子、树篱和树木纹丝不动;每次碰撞都会扣分,计时器与标准时间赛跑。↑ ↓ 前进 / 倒车,← → 转向,空格 刹车,G 轨迹辅助;触屏上按住并拖动。物理:汽车由车身加四个独立的车轮刚体组成——后轮用 WeldJoint 固定,前轮挂在 PivotJoint 上,并由按阿克曼角度设置的 AngleJoint 转向——而且只有前轮驱动,所以真的是转向的前轮把车拉着转弯;拖车通过拖球处的 PivotJoint 挂接,倒车方向不对就会折叠。3D 模式下有带阴影的场景、会转动和转向的车轮、刹车灯与倒车灯,以及倒车影像小窗。

玩法载具JointsTop-downListeners移动端
Flipper Fray — gameplay screenshot开始 →

完整游戏Flipper Fray

一场四人弹珠台混战:一张圆桌、四个球袋,每个球袋由一对挡板守护。台面是一个穹顶:一切都从中心向外滚,因此每颗球最终都会成为某个人的麻烦;弹碰器、弹射器和赛道立柱把弹珠抛来抛去,每一颗越过你挡板的球都要你付出一条命——五条命,坚持到最后的球袋获胜,三分钟到时则比剩余命数。你守住底部球袋,对抗三名 AI 守门员;多球按时间表投放额外弹珠,每半分钟还会滚出一颗炸弹球:掉进袋里扣两条命,没人吞下它就会爆炸。← → / A D 拨动挡板,空格同时拨动两侧;触屏按住屏幕左半或右半。物理:挡板是用 setVelocityFromTarget 驱动的运动学刚体,因此一击会把真实的角速度传给弹珠;弹珠是带子弹标记的圆形,不会穿过纤薄的环形墙;弹碰器和弹射器的冲击以及进球判定都经由 InteractionListener 送达。3D 模式是一座霓虹竞技场:镀铬弹珠、发光球袋和赛道灯光,从你自己的球袋后方观看。

玩法PinballAIKinematicCCDListeners移动端
Swarm Night — gameplay screenshot开始 →

完整游戏Swarm Night

一款吸血鬼幸存者风格的幸存者类 roguelite:在围栏墓园里熬过五分钟,你只需移动——所有武器自动开火。击杀掉落经验宝石;经验条满时夜晚暂停,从六种武器(鞭、杖、飞刀、蒜环、灵珠、闪电)和八种被动中提供三张升级卡。六种怪物按时间表登场,另有携带宝藏的冲锋墓骑士和 4:00 登场的骨巨像,其震地一击能掀飞整群怪物。5:00 黎明即为胜利。WASD / 方向键移动,1 / 2 / 3 或点击选卡;触屏上按住任意位置操控。物理:最多 420 只怪物都是零重力 Space 中的动态圆形,怪群无需群集代码即可挤压流动;击退是按质量缩放的冲量,法球、飞刀、唾液与灵珠都是传感器刚体,命中通过 InteractionListener 与传感器掩码阵营过滤送达。3D 模式是月光墓园,每只怪物都是实例化的低多边形模型。

玩法类肉鸽AI摄像机传感器性能移动端

全部游戏 →

为什么选择 nape-js?

nape-js 是少数几个同时提供刚体动力学、关节约束(PivotJoint、DistanceJoint、WeldJoint、AngleJoint、MotorJoint、LineJoint、PulleyJoint、SpringJoint)、流体浮力、断裂、基于约束网络构建的软体与布料、射线检测与凸形扫掠、内置角色控制器、用于多人回滚的确定性步进、二进制序列化、回放录制以及独立线程 Web Worker 桥接的 JavaScript / TypeScript 2D 物理引擎——作为单一 ESM 包发布(约 174 KB gzip),带有完整的 TypeScript 类型且零 DOM 依赖。

在寻找 Box2D、Matter.js、Planck.js 或 Rapier 的替代方案?运行浏览器内性能测试进行正面对比,或直接进入交互式示例——物理演示和可玩的小游戏(平台跳跃、MOBA、塔防、弹弓、弹珠台、俯视射击)。

为 AI 辅助开发而生

编程智能体最擅长处理那些可读取、可类型检查、并且能真正运行的库。nape-js 三者兼备。

已提供 llms.txt

完整 API 汇总为一个纯文本文件,位于 /llms.txt,另有完整参考文档 /llms-full.txt —— 这是把文档喂给模型的新兴标准。把 URL 交给你的智能体,无需抓取 HTML。

模型可信赖的类型

全程手写 TypeScript 并启用 strict: true,以生成的声明文件发布。智能体能拿到真实签名和悬停 TSDoc,从而更少臆造不存在的方法。

可在 Node 中无头运行

零 DOM 依赖:智能体可以导入引擎、推进模拟,并直接在终端断言结果 —— 无需浏览器、画布或任何 mock。

确定性,测试才站得住

设置 space.deterministic = true 后,同一平台上相同输入必得相同输出。智能体编写的回归测试会因为正确的原因保持绿色。

已记录的陷阱

反模式指南与排错指南明确列出了模型在物理 API 上最常犯的错误。

按任务组织的范例

实用手册按目标划分 —— 平台跳跃、布娃娃、流体、回放 —— 这正是提示词通常出现的形式。

性能测试

此刻正在你的浏览器中测量。每项测试都在紧凑循环中运行物理 step(),并报告每步的中位耗时。

按下按钮开始。

API 一览

核心

形状

支持 nape-js

nape-js 采用 MIT 许可并公开开发。如果它为你节省了时间——或者驱动着你的游戏——赞助能让演示、指南和版本持续更新。