Click to dismiss. Animation by Er Robin at codepen.io

# Pymunk

Pymunk is an easy-to-use pythonic 2d physics library that can be used whenever you need 2d rigid body physics from Python. Perfect when you need 2d physics in your game, demo or simulation! It is built on top of the very capable 2d physics library Chipmunk.

The first version was released in 2007 and Pymunk is still actively developed and maintained today, more than 15 years of active development!

Pymunk has been used with success in many projects, big and small. For example: 3 Pyweek game competition winners, dozens of published scientific papers and even in a self-driving car simulation! See the Showcases section on the Pymunk webpage for some examples.

2007 - 2023, Victor Blomqvist - vb@viblo.se, MIT License

This release is based on the latest Pymunk release (6.5.2), using Chipmunk 7 rev 5dd7d774053145fa37f352d7a07d2f75a9bd8039.

## Installation

In the normal case pymunk can be installed from PyPI with pip:

    > pip install pymunk

It has one direct dependency, CFFI.

Pymunk can also be installed with conda, from the conda-forge channel:

    > conda install -c conda-forge pymunk

For more detailed installation instructions, please see the complete Pymunk documentation.

## Example

Quick code example:

    import pymunk               # Import pymunk..

    space = pymunk.Space()      # Create a Space which contain the simulation
    space.gravity = 0,-981      # Set its gravity

    body = pymunk.Body()        # Create a Body
    body.position = 50,100      # Set the position of the body

    poly = pymunk.Poly.create_box(body) # Create a box shape and attach to body
    poly.mass = 10              # Set the mass on the shape
    space.add(body, poly)       # Add both body and shape to the simulation

    print_options = pymunk.SpaceDebugDrawOptions() # For easy printing

    for _ in range(100):        # Run simulation 100 steps in total
        space.step(0.02)        # Step the simulation one step forward
        space.debug_draw(print_options) # Print the state of the simulation

This will print (to console) the state of the simulation. For more visual, detailed and advanced examples, take a look at the included demos. They are included in the pymunk install, in the pymunk.examples subpackage. They can be run directly. To list the examples:

    > python -m pymunk.examples -l

And to run one of them:

    > python -m pymunk.examples.breakout

## Contact & Support

Homepage

  http://www.pymunk.org/

Stackoverflow

  You can ask questions/browse old ones at Stackoverflow, just look for the Pymunk tag. http://stackoverflow.com/questions/tagged/pymunk

E-Mail

  You can email me directly at vb@viblo.se

Issue Tracker

  Please use the issue tracker at github to report any issues you find. This is also the place for feature requests: https://github.com/viblo/pymunk/issues

Regardless of the method you use I will try to answer your questions as soon as I see them. (And if you ask on SO other people might help as well!)

## Documentation

The full documentation including API reference, showcase of usages and screenshots of examples is available on the Pymunk homepage, http://www.pymunk.org

## The Pymunk Vision

> “Make 2d physics easy to include in your game”

It is (or is striving to be):

- Easy to use - It should be easy to use, no complicated code should be needed to add physics to your game or program.

- “Pythonic” - It should not be visible that a c-library (Chipmunk) is in the bottom, it should feel like a Python library (no strange naming, OO, no memory handling and more)

- Simple to build & install - You shouldn’t need to have a zillion of libraries installed to make it install, or do a lot of command line tricks.

- Multi-platform - Should work on both Windows, *nix and OSX.

- Non-intrusive - It should not put restrictions on how you structure your program and not force you to use a special game loop, it should be possible to use with other libraries like Pygame and Pyglet.

## Dependencies / Requirements

Basically Pymunk have been made to be as easy to install and distribute as possible, usually pip install will take care of everything for you.

- Python (Runs on CPython 3.7 and later and Pypy3)

- Chipmunk (Prebuilt and included when using binary wheels)

- CFFI (will be installed automatically by Pip)

- Setuptools (should be included with Pip)

- GCC and friends (optional, you need it to compile Pymunk from source. On windows Visual Studio is required to compile)

- Pygame (optional, you need it to run the Pygame based demos)

- Pyglet (optional, you need it to run the Pyglet based demos)

- Matplotlib & Jupyter Notebook (optional, you need it to run the Matplotlib based demos)

- Sphinx & aafigure & sphinx_autodoc_typehints (optional, you need it to build documentation)

## Older Pythons

- Support for Python 2 (and Python 3.0 - 3.5) was dropped with Pymunk 6.0.

- Support for Python 3.6 was dropped with Pymunk 6.5.2.

If you use any of these legacy versions of Python, please use an older Pymunk version. (It might work on newer Pymunks as well, but its not tested and no wheels are built.)

## Contents

- Installation
  - Install Pymunk
  - Examples & Documentation
  - Troubleshooting
  - Advanced - Android Install
    - Kivy
    - Termux
  - Advanced - Development
  - Compile Chipmunk
  - CFFI Installation
- Overview
  - Basics
  - Model your physics objects
    - Object shape
    - Center of gravity
    - Mass, weight and units
    - Looks before realism
  - Game loop / moving time forward
  - Object tunneling
  - Unstable simulation?
  - Performance
  - Copy and Load/Save Pymunk objects
  - Additional info
- API Reference
  - `pymunk` Package
    - `pymunk.autogeometry` Module
    - `pymunk.constraints` Module
    - `pymunk.vec2d` Module
    - `pymunk.matplotlib_util` Module
    - `pymunk.pygame_util` Module
    - `pymunk.pyglet_util` Module
    - `pymunk.tests` Module
    - `pymunk.examples` Module
    - `Arbiter`
    - `BB`
    - `Body`
    - `Circle`
    - `CollisionHandler`
    - `ContactPoint`
    - `ContactPointSet`
    - `PointQueryInfo`
    - `Poly`
    - `Segment`
    - `SegmentQueryInfo`
    - `Shape`
    - `ShapeFilter`
    - `ShapeQueryInfo`
    - `Space`
    - `SpaceDebugDrawOptions`
    - `Transform`
    - `Vec2d`
    - `chipmunk_version`
    - `moment_for_box()`
    - `moment_for_circle()`
    - `moment_for_poly()`
    - `moment_for_segment()`
    - `version`
- Examples
  - Jupyter Notebooks
    - matplotlib_util_demo.ipynb
    - newtons_cradle.ipynb
  - Standalone Python
    - arrows.py
    - balls_and_lines.py
    - basic_test.py
    - bouncing_balls.py
    - box2d_pyramid.py
    - box2d_vertical_stack.py
    - breakout.py
    - camera.py
    - colors.py
    - constraints.py
    - contact_and_no_flipy.py
    - contact_with_friction.py
    - copy_and_pickle.py
    - damped_rotary_spring_pointer.py
    - deformable.py
    - flipper.py
    - index_video.py
    - newtons_cradle.py
    - planet.py
    - platformer.py
    - playground.py
    - point_query.py
    - pygame_util_demo.py
    - pyglet_util_demo.py
    - shapes_for_draw_demos.py
    - slide_and_pinjoint.py
    - spiderweb.py
    - tank.py
    - using_sprites.py
    - using_sprites_pyglet.py
  - Additional Examples
    - kivy_pymunk_demo
    - no_dependencies.py
    - py2exe_setup__basic_test.py
- Showcase
  - Games
  - Non-Games
  - Papers / Science
    - Cite Pymunk
- Tutorials
  - Slide and Pin Joint Demo Step by Step
    - Before we start
    - An empty simulation
    - Falling balls
    - A static L
    - Joints (1)
    - Joints (2)
    - Ending
  - External Tutorials
    - Pymunk Basics
    - Simulating physics in Python
    - Breakout game in Python, Pyglet and Pymunk
    - Pymunk physics in Pyglet
- Benchmarks
  - Micro benchmarks
    - Results:
  - Compared to Other Physics Libraries
    - Cymunk
- Advanced
  - Impulse Solver Algorithm
  - Collision Detection Algorithm
  - Why CFFI?
  - Why ctypes? (OBSOLETE)
  - Code Layout
  - Tests
  - Working with non-wrapped parts of Chipmunk
  - Weak References and free Methods
- Changelog
  - Pymunk 6.5.2 (2023-10-22)
  - Pymunk 6.5.1 (2023-06-26)
  - Pymunk 6.5.0 (2023-06-23)
  - Pymunk 6.4.0 (2022-11-20)
  - Pymunk 6.3.0 (2022-11-04)
  - Pymunk 6.2.1 (2021-10-31)
  - Pymunk 6.2.0 (2021-08-25)
  - Pymunk 6.1.0 (2021-08-11)
  - Pymunk 6.0.0 (2020-12-07)
  - Pymunk 5.7.0 (2020-09-16)
  - Pymunk 5.6.0 (2019-11-02)
  - Pymunk 5.5.0 (2019-05-03)
  - Pymunk 5.4.2 (2019-01-07)
  - Pymunk 5.4.1 (2018-12-31)
  - Pymunk 5.4.0 (2018-10-24)
  - Pymunk 5.3.2 (2017-09-16)
  - Pymunk 5.3.1 (2017-07-15)
  - Pymunk 5.3.0 (2017-06-11)
  - Pymunk 5.2.0 (2017-03-25)
  - Pymunk 5.1.0 (2016-10-17)
  - Pymunk 5.0.0 (2016-07-17)
  - Pymunk 4.0.0 (2013-08-25)
  - Pymunk 3.0.0 (2012-09-02)
  - Pymunk 2.1.0 (2011-12-03)
  - Pymunk 2.0.0 (2011-09-04)
  - Pymunk 1.0.0 (2010-07-16)
  - Pymunk 0.8.3 (2009-07-26)
  - Pymunk 0.8.2 (2009-04-22)
  - Pymunk 0.8.1 (2008-11-02)
  - Pymunk 0.8 (2008-06-15)
  - Pymunk 0.1 (2007-08-01)
- Downloads
- Issue Tracker
- Source Repository
- License

## Indices and tables

- Index

- Module Index

- Search Page