Chipmunk2D: a C99 2D physics library that now lives on Codeberg

What Chipmunk2D solves, and who it is for

Chipmunk2D is a 2D rigid body physics library written in C. The README describes the aim as giving 2D developers access to the same quality of physics found in newer 3D games. That sentence is the whole pitch, and it is a narrow one: this is not a game engine, not a renderer, and not a scene graph. It is the piece that decides where a crate lands after it is pushed, how a chain of links behaves when you pull one end, and whether a player standing on a one-way platform falls through it.

The intended audience is game developers working in C or C++, plus anyone on Apple platforms who wants the bundled Objective-C API. The library is a C99 implementation with, in the README's words, no external dependencies outside of the Std. C library. For a team shipping a game, that matters more than any feature list: there is no runtime to install, no shared object to ship alongside the executable, and no version skew between your physics library and its transitive dependencies.

The feature set is aimed at 2D gameplay rather than simulation fidelity. Collision primitives are circles, convex polygons, and beveled line segments, and multiple primitives can be attached to a single rigid body. Broad phase detection uses a bounding box tree with temporal coherence, or a spatial hash. Sleeping objects that have come to rest are supported to cut CPU load. Joints cover vehicles and ragdolls, and joint callbacks exist so you can implement breakable or animated joints. None of this is unusual in a 2D engine. What is unusual is that all of it arrives in one C file tree you compile yourself.

How the solver and collision pipeline actually work

The mechanism visible in the README is a three-stage pipeline. First, broad phase collision detection narrows the candidate pairs. Chipmunk2D offers two structures here: a bounding box tree that exploits temporal coherence (objects that were near each other last frame are likely near each other this frame), or a spatial hash. Second, narrow phase work resolves the actual contact geometry against the circle, polygon and segment primitives attached to each body. Third, an impulse solver computes the response, and the README credits Erin Catto's contact persistence algorithm for making that step fast.

Contact persistence is the interesting design decision. Rather than discarding contact information each frame and rebuilding it, the solver keeps it across frames, which is what allows stacks to settle instead of jittering. Chipmunk2D also maintains a contact graph of all colliding objects and exposes collision event callbacks based on user-definable object types, so gameplay code can react to a specific collision without polling.

Collision filtering is where the library becomes a gameplay tool rather than a simulator. Layers, exclusion groups, and callbacks combine, and the README notes this can produce one-way platforms or buoyancy areas, with examples included. The demo directory supports that claim: demo/OneWay.c and demo/Buoyancy.c are both present. Impulse amounts can be retrieved after a collision, which is how you drive a sound effect or a damage number from the physics result rather than guessing at it.

Queries round out the API: nearest point, segment (raycasting), shape, and bounding box queries against the collision detection system. If you have written a 2D game before, you know that raycasting for line of sight or for a hitscan weapon is usually the first thing you need and the first thing a minimal engine omits.

Building Chipmunk2D from source on macOS, Unix and Windows

There is no package manager install described in the README. You build from source, and the README gives a different path per platform. On macOS there is an included Xcode project for the static library and demo application, plus CMake files and a macstatic.command script in the xcode/ directory. On iPhone, a native Objective-C API is included, and iphonestatic.command in the same directory builds a fat library, release for the device and debug for the simulator.

On Unix the README points at CMake files contributed by a forum user. The two commands it names are run from the repository root:

cmake .
make

According to the README, this builds a dynamic library, a static library, and the demo application. The same passage warns that a number of people have had build errors on Ubuntu due to missing GLUT or libxmu. Those are demo dependencies, not library dependencies, but you will hit them if you build the default target on a bare Ubuntu install, so install them first or build only the library target.

On Windows, Visual Studio projects live in the msvc/ directory. The README is candid that the MSVC 10 project is the one kept up to date and that the MSVC 9 project may not work. Before you start, note the repository layout: include/ holds the headers, src/ holds the implementation, doc/ holds the C API documentation, and demo/ holds the examples.

For a first real use, the README recommends the demo application as the starting point, because each demo sets up a simulation space and the demo app draws graphics directly out of that space. The demo drawing routines are usable in your own project, but the README explicitly says this is not the recommended way to draw Chipmunk objects, since the routines poke around at undocumented private APIs. Read them to learn the API, then write your own renderer.

The GitHub repository is a mirror, and that is the real constraint

The README opens with a move notice, not a feature list. The project page is now on Codeberg, and the author states that support will continue on both sites for now but that the plan is to eventually drop GitHub entirely. For anyone who found Chipmunk2D through a GitHub search, that is the first thing to understand about the repository you are looking at.

The README gives a migration command for an existing checkout:

git remote set-url origin https://codeberg.org/slembcke/Chipmunk2D
git fetch origin master
git reset origin/master

It also notes that you may need to run git checkout . to clean up deleted files, and warns in the same breath that this discards local changes. That warning is easy to skim past and expensive to ignore.

The practical consequence is that a GitHub URL in your CI configuration, your submodule list, or your build scripts points at a repository the maintainer intends to abandon. Nothing is broken today. But this is the kind of thing that fails silently years later when someone clones your project and the submodule no longer resolves. If you vendor Chipmunk2D as a submodule, point it at the Codeberg remote now rather than during an incident.

There is a second limitation worth naming. The README says that if you got the source from a point release download, you might want the latest source instead, because bugs are fixed and features added regularly and big changes are tested in branches before merging. That is a maintainer telling you the tagged downloads are not the highest-quality artifact. Plan to track a branch, not a release tarball, and accept the churn that implies.

Chipmunk2D versus Box2D, and when you want neither

The obvious alternative is Box2D, and the difference in approach is mostly about language and integration surface. Box2D is C++, so it brings a class-based API, operator overloading in places, and a C++ toolchain requirement into your build. Chipmunk2D is C99, which means it links cleanly into C, C++, Objective-C, and anything else with a C FFI. If your game is written in C, or you are binding physics into a language runtime, that difference decides the choice before any benchmark does.

The README also states that many language bindings are available, listed on the project site. That is the payoff of the C core: a binding author has a flat C ABI to target rather than a C++ ABI that varies by compiler and standard library version.

Where Chipmunk2D is the wrong tool: if you need 3D physics, it does not do that, and no amount of joint configuration will change it. If you want a physics engine that arrives through a package manager with a semver contract, this is not that; the README documents building from source per platform, and the point-release downloads are described as lagging the branches. If you are working in JavaScript and want physics in the browser, Chipmunk2D is a C library you would reach only through a binding or a WebAssembly build, and the README does not document either path.

One more boundary: Chipmunk2D is not a renderer. The demo application draws with GLUT and GLFW, and the README frames the drawing code as a way to see the API in action, not as a rendering layer for your game. You supply the graphics. That separation is the point of the library, but it also means the demo is not a starting template for a shipping game.

Licence, maintenance and what an upgrade costs

Chipmunk2D is licensed under the MIT licence, which the README calls unrestrictive and OSI approved. In practice that means you can link it into a commercial, closed-source game without publishing your own source, provided you keep the copyright and permission notice with the distribution. This article is not legal advice; read LICENSE.txt in the repository root for the actual terms.

The commercial angle is worth stating plainly because the README states it: Howling Moon Software, the author's company, offers contracting to help teams use the library. That is a normal arrangement for a game library, and it also tells you where the maintenance attention goes. The repository is not archived, and the last push was on 2026-05-05, so it is not dormant, but the move notice in the README is the more informative signal about where future work lands.

Upgrade cost is hard to estimate from the README, which does not document a versioning policy or a changelog. The one concrete data point is that Chipmunk 7 is described as complete and as including ARM NEON optimizations, the autogeometry code, and the multithreaded solver. That is a large feature set arriving in a major version, and the README does not describe a migration path from earlier versions. If you are on an older release, budget for reading the programming guide rather than for a mechanical version bump.

A practical upgrade cost that is easy to overlook: the README says the demo drawing routines poke at undocumented private APIs. If you copied those routines into your project, as the README permits, a physics upgrade can break your rendering code, not just your simulation code. Vendoring the demo drawing code is a decision with a maintenance tail.

Editorial conclusion

Adopt Chipmunk2D if you are writing a 2D game in C or C++ and want a solver you can compile into your binary with no third-party dependencies, or if you are on iOS and want the included Objective-C API. Do not adopt it if you need a maintained GitHub mirror, a package manager install, or a 3D physics engine, because the README states support will eventually move to Codeberg only. Before committing, verify the Codeberg remote resolves, run the CMake build to confirm GLUT and libxmu are present on your machine, and read the C API documentation in the doc/ directory rather than relying on the demo drawing code, which the README says pokes at private APIs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. slembcke/Chipmunk2D on GitHub