Chipmunk Physics Lua binding demo

A whole lot of life slowed me way down, along with being inexpert in nearly every aspect of what I was doing, but I've cobbled together a little proof of concept/toybox to feel out how to do minimal usable Lua bindings for the Chipmunk2D engine, and what feels good and performs adequately on-device. I have a couple simple physics game ideas and this was useful for prototyping.

By default it just throws some random discs and boxes on the display and controls them with the accelerometer. Options menu contains an editor for adding/removing/changing properties of objects, as well as some crank-control modes and an optional surface + viscous drag model that is nice but a bit slow.


  • Chipmunk performance is very good as long as you don't have too many stacked physics objects. "Too many" is like more than 10, which isn't too impressive, but still has plenty of potential for games.

  • The Lua bindings (all in chipdx/luaglue.c) are extremely basic and do no input validation. Since Chipmunk throws errors that the Playdate isn't catching when you, say, set mass to negative or use a dot instead of a colon, and there's very little static checking that you can do in Lua, this leads to an annoyingly high number of device crashes during development. One could write better glue than I did.

  • I'd really love to know if it'd be worth creating custom constraints in C to improve my surface-drag implementation's performance. Neither the communication between Lua and C nor the way constraint values are getting updated seem particularly runtime-efficient. I am not fluent enough in C to feel tremendously motivated to prioritize this work.

  • Still fond of the little variable framerate fixed-update loop I mentioned earlier. It's tiny and very flexible with performance hits.

  • I have not tuned the default values for crank-control very well, and you really need to turn up edge friction and drop elasticity for it to feel good.

  • I am unreasonably proud of the table of labels and functions in Inspector.lua. It's really, really quick to add new rows to the inspector window.

  • For this to be actually usable for games the Lua glue code needs some collision hooks. Probably this wouldn't be trying to access Chipmunk's collision callback design from Lua, but just maintaining a list of current collisions that you can see from the Lua side.

Source code: GitHub - jalexchapman/playdate-chipmunk-lib (236.0 KB)

tilt input with and without surface drag

torque-based crank input



That's absolutely delightful. Massive congratulations on surmounting hurdles to get to those points.

I downloaded the source and tried to compile it in LUA and it fails, giving this error:
Update error: world.lua:15: attempt to index a nil value (global 'chipmunk')
stack traceback:
world.lua:15: in method 'setup'
main.lua:77: in function 'setup'
main.lua:172: in function main.lua:170

I'm on a windows machine if it matters, I figured the demo would compile just fine. I didn't edit or change anything.

Any ideas?

Ooh, Windows matters very much.

How are you building? Pdc alone won’t do; you have to build the C parts (where chipmunk is defined and implemented). It took me a long time to successfully build Playdate C from scratch on Windows with Cmake/nmake (the only documented way I know to build Playdate C on Win) and I gave up shortly after the first good build, because I also have a Mac and the C build process is simpler there. If there’s still a CMakeLists.txt in the repo, that’s in error.

If you’d like to help me get my cmake build working properly on Windows I’d be in your debt. There is something about cmake (and its documentation) that my brain totally rejects, even though in another life I spent years being paid in part to be a build expert. Otherwise you might actually have better luck installing Windows Subsystem for Linux and doing the Linux build, because Linux is a lot closer to Mac than Windows is. On Mac you just type 'make' and you're done.

I got the full chipmunk physics engine to compile on Windows for the Simulator in C for a game I built, but I haven't figured out how to make it compile for the device. I've been working on it for two weeks. So I thought maybe going back to Lua and using the bindings to work would work.....but it seems there is still some playing around to do. I'll mess with it and see what I can find out.

Yeah, I dimly recall some degree of aggravation switching between simulator and device build targets, while the default sdk makefile on the Mac side (for make, not cmake) just builds binaries for both. I have already gone the Windows Subsystem for Linux route in the past for some Gameboy stuff (rgbds is on Windows native but docs foreground the WSL option), and it's remarkably painless. Once you do that, you can pop open a Linux terminal and just use the linux build and your distro's package manager of choice. The virtualization stuff in Windows is extremely mature and one of the better aspects of the platform. There's also some very snazzy WSL integration built into Visual Studio Code.

I'm just now remembering that I tried WSL for Playdate C builds for a minute or two, and there was a bit of a hitch getting the Linux Playdate simulator to behave inside the WSL XWindows host, and of course the Windows simulator wouldn't run the Linux-produced game binary. It's probably a very solvable problem, but I didn't try for very long since I had this Macbook Air lying around. Would you believe it, but with Panic being a Mac-focused company, everything's quite seamless there.

I do have a shameful wish that the simulator was actually an emulator and we only ever built and ran Playdate binaries, but I'm guessing there's a good reason we do it this way. Platforms are hard.

Did you see my reply to your earlier thread? I think it's a relatively simple fix. I'd be happy to help you fix it, but I don't know if my suggestion worked or not.

Sorry, had dropped and promptly forgotten everything about the windows build environment. I’m sure it’s simple, Cmake just makes me very itchy. I’ll check it out when I have a chance — might as well have a functional cross platform build now I’ve published the thing.

I meant that towards @robamcclellan (I hit the reply button on their message), but I may be able to take a look at your repo in a little bit :slightly_smiling_face:. You should be able to just modify the cmakelists inside the hello world example, but I understand being uncomfortable with cmake in any case.