Library / SDK
slembcke/Chipmunk2D avatar
slembcke/Chipmunk2D

Chipmunk2D: a physics library whose readme is a migration notice

A fast and lightweight 2D game physics library.

2,414 stars365 forksCMIT

At a glance

What is it?
A 2D rigid body physics engine written in C99 with no dependencies outside the standard library, and a readme whose first section tells you the project has moved to a different host. The migration instructions are three git commands, and the warning about what they destroy comes after them.
Who is it for?
The engine is mature, small, and has the feature set you would expect from something that has been used in shipping games for two decades, so the question is not whether it works. It is where to get it.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Activity is slowing. The repository last received commits 6 months ago.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • slembcke/Chipmunk2D2,414 ★ · +4
Star history
Repository2026-09-302026-11-15
slembcke/Chipmunk2D2.4k2.4k

4 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The first thing the readme says is that the project has moved

The document opens with a heading saying the project has moved, and a link to the new location on a different forges service.

The second paragraph gives the plan: support both sites for now, and eventually drop the current one entirely. The word eventually appears twice in that sentence.

After the migration block, the readme returns to describing the library as if none of that had happened. There is a section on what is new in the current major, a feature list of fifteen items, a contracting pitch, four paragraphs of build instructions per platform, a section telling people to discard their release download, and a getting-started section.

The result is a document with two jobs. It is a manual for a mature engine, and it is a change notice for the project's own infrastructure, with the change notice first and the manual following it. A reader who arrives from a search result and skims past the top section finds a perfectly good readme; a reader who stops at the top learns nothing about the library at all.

The migration is also not finished. Both sites are live, neither is deprecated, and the plan is to drop one without a date. Anyone building a dependency on this is making a bet about which forge will still be there in two years.

The migration commands discard local work, and the warning comes after them

The migration instructions are three commands, and they are the right three. They repoint the remote at the new location, fetch the branch, and hard-reset the local copy onto what was fetched:

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

Here is the problem. A hard reset onto a fetched remote branch discards every uncommitted change and every local commit that is not on that branch. The readme then says you may additionally need a fourth command to clean up the files that the reset removed, and the warning about discarding work is attached to that fourth command rather than to the reset.

So the sentence that would matter most, the one about your local changes being thrown away, is printed after the command that throws them away. Anyone following the instructions top to bottom in a terminal has already lost the work by the time they read it.

There is an honest defence of the order. You cannot know whether the new host has a branch you need until you fetch it, so resetting is the last step, not the first. But the readme could equally have said to fetch first, look, then reset, and it does not.

One detail in the fetch is worth noting for anyone automating this. It names a single branch, so a checkout with other local branches keeps them and only the current one is realigned.

The build system most people will run was contributed by a forum member

There are five platform directories in the repository: an Android one, a Code::Blocks project directory, a Microsoft Visual Studio directory, an Objective-C directory, and an Xcode directory.

The readme's build section covers four platforms, and the macOS instructions are the ones the author maintains: an included project file for a static library and a demo, or one of two shell scripts in the same directory that build a static library and package the headers.

The Unix instructions are phrased differently. They say a forum user was kind enough to make a set of CMake files, that this requires CMake to be installed, and that you run two commands in a directory. The same two commands build a dynamic library, a static library, and the demo.

So the build path a Linux developer is most likely to take is a contributed one, and the readme describes it in the passive voice, as something that was done for them. That is generous and accurate, and it also means there is no single maintained build definition across platforms. The two maintained paths are macOS-only.

The readme also flags the known failure mode for that contributed path, naming two missing system packages as the cause of build errors people have hit on Ubuntu. A project that advertises no external dependencies is talking about the library, not about what it takes to compile the demo, and the build section is where the difference becomes real.

One platform's project is unmaintained by the author's own admission

The Windows section is three sentences and the last one is a request for help.

Visual Studio project files are included in a directory in the repository. The author says they try to keep the newer one up to date but do not have the older compiler installed, so that project is not updated regularly, and then: it may not work, and a hand fixing it would be appreciated.

That is an unusually candid disclosure, and it tells you something specific. There are at least two Visual Studio project files, targeting two different compiler generations of a toolchain that is now several versions behind current. The newer one is maintained as a best effort by someone without the compiler installed, which in practice means it is updated when a contributor reports a problem rather than when the toolchain changes.

The iOS section is in better shape and describes an actual workflow: a native Objective-C API is included, the project file can build a static library with the right settings, or a shell script builds a fat library compiled as a release build for the device and a debug build for the simulator, after which you drop a directory into your project. That is a well-trodden path, and it is the one platform where the readme tells you exactly what you end up with.

Comparing the three is instructive. macOS and iOS get maintained projects and scripts. Windows gets a best effort and an apology. Unix gets a donation.

The demo drawing code is offered for reuse and disclaimed in the same sentence

The getting-started section recommends looking at the demo application, and explains that each demo sets up a simulation space and draws directly from it, which makes the library's behaviour visible without graphics code getting in the way.

Then it says you are free to use the demo drawing routines in your own projects, and in the same sentence says it is certainly not the recommended way of drawing the library's objects, because it pokes around at the undocumented and private interfaces.

That is a permission and a stability warning delivered together, and it is more useful than either alone. The routines exist, they work today, and they will break on any change to internals because they are not part of the published interface.

The warning extends to the demos' design. The readme explicitly recommends the demos as the way to understand how the library's interface behaves, and explicitly warns against reusing how they draw. The same files are simultaneously the best documentation and a known liability, which is a distinction the readme draws in one clause and most projects would not draw at all.

The demo directory in the tree is large, with more than twenty example programs covering joints, buoyancy, contacts, convex shapes, raycasting, one-way platforms, chains, and a benchmark.

There are no releases, so the version is a file and the advice is to track the tip

The repository has no published releases, and its version number lives in a text file at the root.

That alone is workable for a library with a long stable history. What makes it awkward here is the section telling people to get up to date. It says that if you got the source from a point release download you should consider getting the latest source instead, because bugs are fixed and features are added regularly, and that big changes are done in branches and tested before merging. It concludes that it is rare for a point release download to be better or less buggy than the latest code.

So the project's own guidance is: do not use a release, use the tip. Combined with the migration notice, that instruction resolves to tracking the tip of a repository whose remote is being changed, on a forge it may be leaving.

There is also a version gap in the readme's own structure. The current major is announced as complete, with three headline features. There is no list of what changed in it, no upgrade notes, and no indication of what breaks between the current major and the one before. For a physics library where behaviour changes are subtle, a migration note between majors is the document you most want and it is not here.

The two other root files are worth noting as a shape. There is a citation file, which is unusual for a game physics library and suggests academic use, and a plain-text to-do list, which is checked into the root rather than an issue tracker.

Bindings and ports are the adoption path, and half the search traffic is looking for them

One of the fifteen feature bullets says many language bindings are available and links to a separate page listing them. The library itself is C, and the language in the repository is C.

The search traffic shows what that means in practice. Queries for the library plus Android, plus Go, plus C++, plus a download link, plus a comparison against another engine, plus a forum. Almost none of it is for the C library. It is for the library as used from another language, or as used on a platform the C build does not cover directly.

The repository helps with two of those. There is an Android directory and an Objective-C directory, so the two mobile platforms have native glue in-tree. Everything else is in the bindings list, which lives on the project's website rather than here, and that website is the one still hosted where the project says it is leaving.

Two search terms are also about other engines entirely, including a 3D engine and a couple of alternatives. That is the comparison question, and the readme does not answer it. It makes a claim instead, in the about section, that the aim is to give 2D developers access to the same quality of physics found in newer 3D games.

That is the whole competitive argument, and it is fourteen words long.

There is also a contracting paragraph in the middle of the feature list, offering the author's company for work on making the physics stand out in a commercial game, linked to a company site. A single-maintainer library with a support offer attached is a common and reasonable arrangement; having it between the feature list and the build instructions is an unusual place for it.

Editorial conclusion

The engine is mature, small, and has the feature set you would expect from something that has been used in shipping games for two decades, so the question is not whether it works. It is where to get it. The answer the readme gives is to track the tip of a project that is midway through moving between two hosts, which is a fragile instruction to follow: the tip is on a moving remote, the previous major is not tagged, and the version number lives in a text file rather than a release. Plan to vendor a specific commit instead. And if you use the debug drawing code from the demo, the author has already told you it reaches into private internals and will not be stable across versions.

Frequently asked questions

What is slembcke/Chipmunk2D?

A 2D rigid body physics library written in C99, MIT licensed, described as simple, lightweight, fast and portable. It provides circle, convex polygon and bevelled segment collision primitives, a bounding-box-tree or spatial-hash broad phase, sleeping bodies, collision filtering by layer and exclusion group, raycasting and shape queries, and a wide range of joint types.

Has Chipmunk2D moved away from GitHub?

Yes. The readme's first section says the project has moved and links to a new location on a different forge. It states that both sites will be supported for now and that the plan is to eventually drop the current one, with a separate document explaining why.

What do the Chipmunk2D migration commands do to my local changes?

The three commands repoint the remote, fetch the branch, and hard-reset the working copy onto it, which discards uncommitted changes and any local commits not on that branch. A fourth command to clean up removed files is mentioned afterwards, and the warning about discarding local work is attached to that fourth command rather than to the reset.

Does Chipmunk2D have any dependencies?

The library claims none outside the standard C library. Building the demo application is a different matter: the readme notes that people have had build errors on Ubuntu from missing graphics and input library packages, and the demo directory contains configuration files for an extension loader and a windowing toolkit.

Can I use the Chipmunk2D demo drawing code in my own project?

The readme says you are free to, and in the same sentence says it is not the recommended way to draw the library's objects, because the routines reach into undocumented and private interfaces. They work today and should be expected to break on internal changes.

Official sources

  1. Issues
  2. License: MIT
  3. Project website
  4. README
  5. slembcke/Chipmunk2D on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/slembcke-chipmunk2d.svg)](https://hysenlabs.com/projects/slembcke-chipmunk2d)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/slembcke-chipmunk2d.svg)](https://hysenlabs.com/projects/slembcke-chipmunk2d)

Was this useful?