本页目录

Pymunk — Python 2D 刚体物理库

pymunk · viblo/pymunk

Pymunk 是一个易用的 Python 风格 2D 刚体物理库,底层基于 Munk2D(Chipmunk2D 的分支),适合为游戏、演示或模拟加入 2D 物理效果。项目首个版本发布于 2007 年,README 称至今仍在活跃开发与维护,采用 MIT 许可,可通过 pip 安装。RE...

其他 Pygame Python 跳跃与重力 碰撞检测 物理系统 中级
★ Stars 1,081 Forks 201 License MIT 更新 2026-11-19

国内开发环境适配

Windows
官方声明支持
Linux
官方声明支持
macOS
官方声明支持
引擎 / 框架:Pygame 暂无中文教程标记 未标记站长实测
pip 安装的二进制 wheel 已内置预编译的 Chipmunk,通常无需本地编译;唯一直接依赖为 CFFI。国内网络建议使用 PyPI 镜像源加速;也可使用 conda-forge 渠道。若需从源码编译,Windows 需 Visual Studio、Linux/macOS 需 GCC 工具链,具体是否可用待核验。

中文项目介绍

Pymunk 是一个易用、贴近 Python 习惯的 2D 刚体物理库。只要你的程序需要 2D 刚体物理效果,无论是游戏、演示还是模拟程序,都可以直接引入它。它构建在 Munk2D 之上,而 Munk2D 是成熟的 2D 物理库 Chipmunk2D 的一个分支,因此 Pymunk 并不是从零实现的物理求解器,而是在一套经过验证的物理内核外,封装了一层 Python 接口。

项目首个版本发布于 2007 年,README 中明确写到它至今仍在活跃开发与维护,已持续超过 15 年。代码以 MIT 许可发布,作者为 Victor Blomqvist。README 还提到,Pymunk 已被用于各种规模的项目,例如 3 个 Pyweek 游戏竞赛的获奖作品、数十篇已发表的科研论文,以及自动驾驶仿真;具体案例可在官网 Showcases 一节查看。

核心功能

易于使用

为游戏或程序加入物理时,不应该需要写复杂的代码。

Pythonic

底层虽然是 C 库 Chipmunk,但使用者不应感觉到它的存在,接口命名、面向对象风格、内存管理都应像纯 Python 库。

构建与安装简单

不应该为了装上它而预先准备一大堆依赖,也不需要执行很多命令行技巧。

跨平台

应能在 Windows、*nix 与 OSX 上工作。

非侵入式

不限制你如何组织程序,不强制使用某种特定的游戏循环,并且能与 Pygame、Pyglet 等库配合使用。

技术架构分析

技术要点

从 README 的示例可以看出 Pymunk 的基本对象模型:

  • Space 代表承载整个模拟的物理空间,可以直接设置 gravity 重力向量;
  • Body 代表刚体,通过 position 设置其在空间中的位置;
  • Shape 代表附着在刚体上的形状,例如用 Poly.create_box(body) 创建一个盒子形状,再通过 mass 设置质量;
  • 把 Body 与 Shape 一起 add 进 Space 后,调用 space.step(0.02) 即可把模拟向前推进一个时间步;
  • SpaceDebugDrawOptions 配合 space.debug_draw(...) 可用于输出模拟状态,示例中直接把状态打印到控制台。

这个例子把最常见的用法串了起来:创建空间、设置重力、创建刚体与形状、添加进空间、循环步进。文档说明完整的 API 参考、使用展示与示例截图都放在 Pymunk 官网 http://www.pymunk.org。

补充说明

安装与运行

常规情况下,Pymunk 从 PyPI 安装:

pip install pymunk

它只有一个直接依赖 CFFI。也可以走 conda,从 conda-forge 渠道安装:

conda install -c conda-forge pymunk

更详细的安装说明请看完整文档。README 同时说明,当前发布基于 Pymunk 7.3.1,使用的 Munk2D 版本为 2.1.0(rev 3d2070976911b7e4b659a5365b0313f99dc98788)。

自带示例

Pymunk 的安装包中内置了示例,位于 pymunk.examples 子包,可直接运行。列出全部示例:

python -m pymunk.examples -l

运行其中一个:

python -m pymunk.examples.index_video

想要更直观、更详细的示例,建议直接阅读这些 demo 的源码。

依赖与版本支持

README 给出的运行要求包括:

  • Python:支持 CPython 3.9 及更高版本,以及 PyPy3;
  • Chipmunk:使用二进制 wheel 时会预编译并内置;
  • CFFI:由 pip 自动安装;
  • Setuptools:通常随 pip 一起提供。

可选依赖按用途区分:从源码编译需要 GCC 及同类工具链(Windows 上需要 Visual Studio);运行基于 Pygame 的示例需要 Pygame 或 Pygame-CE;运行基于 Pyglet 的示例需要 Pyglet;运行基于 Matplotlib 的示例需要 Matplotlib 与 Jupyter Notebook;少数示例需要 NumPy;构建文档需要 Sphinx、aafigure 与 sphinx_autodoc_typehints。

旧版 Python 的支持是被逐步移除的:Python 2(以及 3.0–3.5)在 Pymunk 6.0 中停止支持,3.6 在 6.5.2 中移除,3.7 在 6.9.0 中移除,3.8 在 7.0.0 中移除。若必须使用这些旧解释器,应选择较旧的 Pymunk 版本;新版本或许能跑,但未经测试,也不提供预编译 wheel。

获取支持与参与

README 列出了几条支持渠道:官网 http://www.pymunk.org、Stack Overflow 上的 pymunk 标签(可提问也可检索历史问题,且其他人也可能帮忙解答)、作者邮箱 vb@viblo.se,以及 GitHub issue tracker(既用于报告问题,也用于提交功能请求)。作者表示会尽快回复。

学习建议

如果你第一次接触物理库,建议按 README 的路径推进:先跑通上面的最小示例,理解 Space / Body / Shape 三者的关系与 step 的时间步含义;再浏览 pymunk.examples 中的示例,观察形状、约束、调试绘制等能力在实际代码中的写法;最后回到官网文档查 API 细节。由于 Pymunk 不强制游戏循环、可与 Pygame、Pyglet 等配合,把物理模拟接入已有项目时,通常只需在每帧调用一次 step,再把刚体的位置同步到渲染对象即可。

开源许可证与版权说明

许可证标识:MIT。源码、资源与依赖许可可能不同,请以官方仓库为准。本站仅做索引,不托管源码。

相似项目

台球物理沙盒(pooltool)

台球物理沙盒(pooltool)

pooltool 是一款用 Python 编写的台球沙盒游戏,主打贴近真实的物理模拟,标...

竞速体育 无明确引擎
★ 437 Fork 96