Python Pymunk Physics — Core Concepts

What Pymunk Is

Pymunk is a Python wrapper around the Chipmunk2D physics library, a lightweight and fast C engine for 2D rigid-body simulation. It handles collision detection, gravity, friction, elasticity, joints, and constraints — everything you need to make objects in a 2D world behave physically.

The Three Core Objects

Space

A Space is the simulation world. It holds all bodies and shapes, defines gravity, and steps the simulation forward in time. You create one space per simulation.

Body

A Body represents the physical properties of an object — mass, moment of inertia (resistance to rotation), position, velocity, and angular velocity. A body has no visible shape on its own; it is pure physics data.

Bodies come in three types:

• Dynamic — affected by forces, gravity, and collisions. A falling ball.
• Static — never moves. The ground, walls, permanent obstacles.
• Kinematic — moves at a set velocity but is not affected by forces. A moving platform.

Shape

A Shape is the collision geometry attached to a body. Pymunk offers circles, segments (lines), and convex polygons. Each shape carries physical surface properties:

• Elasticity (0.0 = no bounce, 1.0 = perfect bounce)
• Friction (0.0 = ice, 1.0 = rubber)

One body can have multiple shapes — for example, a car body plus four wheel shapes.

Stepping the Simulation

The space does not run continuously by itself. You call space.step(dt) in a loop, where dt is the time increment (commonly 1/60 second). Each step:

1. Apply gravity and external forces to all dynamic bodies.
2. Detect collisions between shapes.
3. Resolve collisions — calculate impulses, separate overlapping shapes.
4. Update positions and velocities.

Calling step with a consistent dt ensures deterministic simulation. If your game’s frame rate varies, you still step physics at a fixed rate and interpolate visuals.

Collision Detection and Callbacks

When two shapes overlap, Pymunk generates a collision event. You can listen for specific collisions using collision handlers:

handler = space.add_collision_handler(BALL_TYPE, WALL_TYPE)
handler.begin = on_ball_hits_wall  # called when contact starts
handler.separate = on_ball_leaves_wall  # called when contact ends

The callback receives an Arbiter object containing contact points, collision normal, and the involved shapes. Returning False from begin tells Pymunk to ignore the collision (useful for one-way platforms or trigger zones).

Joints and Constraints

Pymunk includes several constraint types that connect bodies:

• PinJoint — rigid connection at a point (like a nail).
• SlideJoint — connection with minimum and maximum distance (like a rope).
• PivotJoint — two bodies rotate around a shared point (like a hinge).
• GearJoint — rotation of one body drives rotation of another.
• DampedSpring — elastic connection that pulls bodies together and dampens oscillation.
• SimpleMotor — applies constant rotational velocity (like a motor).

Combining joints creates complex mechanisms — a ragdoll is pivot joints connecting limb segments, a car is a body with damped springs to wheel bodies.

Integrating with Graphics

Pymunk is graphics-agnostic. It calculates positions and rotations; you draw them however you like. Common pairings:

• Pygame — read body positions each frame and blit sprites.
• Arcade — use Arcade’s built-in Pymunk physics engine wrapper.
• Pyglet — draw shapes using OpenGL primitives.
• Matplotlib — for scientific visualization and teaching.

Pymunk also ships with pymunk.pygame_util and pymunk.pyglet_util modules that draw collision shapes directly for quick prototyping.

Common Misconception

“Pymunk is slow because it’s Python.” The actual physics computation runs in compiled C code (Chipmunk2D). Python is only the scripting layer that sets up the world and reads results. For typical 2D games with hundreds of objects, Pymunk runs comfortably at 60 FPS.

The one thing to remember: Pymunk gives you a ready-made physics world — create a Space, add Bodies with Shapes, step the simulation, and let Chipmunk2D handle all the collision math.