Idiomatic and cross-platform Clojure version of the Box2D physics engine API. Wraps jBox2D (Clojure) and Planck.js (ClojureScript).

Box2D is just a physics engine, you most likely want to combine it with a graphics library to show something on the screen. We bundle some helpers to get you started on Quil or Clojure2D, see the namespaces lambdaisland.cljbox2d.quil or lambdaisland.cljbox2d.clojure2d respectively, or browse the examples under lambdaisland.cljbox2d.demo.*

The Box2D API is highly imperative, to create a body or a fixture you first create a BodyDef or FixtureDef object, call a bunch of setters to set the right parameters, then use that to construct the actual object. Yuck.

For us it's all just data. For comparison

;; create bodyDef
b2BodyDef groundBodyDef;
groundBodyDef.position.Set(0.0f, -10.0f);

;; use it to create a body
b2Body* groundBody = world.CreateBody(&groundBodyDef);

;; Add a fixture 
b2PolygonShape groundBox;
groundBox.SetAsBox(50.0f, 10.0f);
groundBody->CreateFixture(&groundBox, 0.0f);

With cljbox2d:

(b/populate world [{:position [0 -10]
                    :fixtures [{:shape [:rect 50 10]}]}])

Run these commands to see cljbox2d in action:

clojure -Sdeps '{:deps {com.lambdaisland/cljbox2d {:mvn/version "0.8.46"} quil/quil {:mvn/version "4.0.0-SNAPSHOT"}}}' -M -m lambdaisland.cljbox2d.demo.simple-shapes
clojure -Sdeps '{:deps {com.lambdaisland/cljbox2d {:mvn/version "0.8.46"} quil/quil {:mvn/version "4.0.0-SNAPSHOT"}}}' -M -m lambdaisland.cljbox2d.demo.pyramid
clojure -Sdeps '{:deps {com.lambdaisland/cljbox2d {:mvn/version "0.8.46"} quil/quil {:mvn/version "4.0.0-SNAPSHOT"}}}' -M -m lambdaisland.cljbox2d.demo.platformer

Or if you already have a REPL open then simply open any of the lambdaisland.cljbox2d.demo.* namespaces, evaluate them, and then run the (-main) function.

(require 'lambdaisland.cljbox2d.demo.pyramid)
(lambdaisland.cljbox2d.demo.pyramid/-main)

To start your own project you can copy lambdaisland.cljbox2d.demo.template (for Quil) or lambdaisland.cljbox2d.demo.clojure2d.template (for Clojure2D) over to your own project and take it from there.

To use the latest release, add the following to your deps.edn (Clojure CLI)

com.lambdaisland/cljbox2d {:mvn/version "0.8.46"}

or add the following to your project.clj (Leiningen)

[com.lambdaisland/cljbox2d "0.8.46"]

You will also need a library to deal with graphics and user interaction. If unsure you can start with Quil.

There's a template file that you can use to set up your first project with cljbox2d and Quil.

You'll want to learn about the main Box2D concepts: bodies, shapes, fixtures, and joints. The clearest explanation I've come across is in these iForce2D tutorials: bodies, fixtures & shapes. There are also the official Box2D docs. Until we get more comprehensive documentation of our own together you'll have to make due with these, and the convert to cljbox2d.

The demos contain a number of examples you can study, from trivial (template, simple-shapes, pyramid), to more full-fledged (platformer).

The following jBox2D features are not supported by planck.js

• ConstantVolumeJoin
• Particles (and thus particle raycast)

cljbox2d is part of a growing collection of quality Clojure libraries created and maintained by the fine folks at Gaiwan.

Pay it forward by becoming a backer on our Open Collective, so that we may continue to enjoy a thriving Clojure ecosystem.

You can find an overview of our projects at lambdaisland/open-source.

Everyone has a right to submit patches to cljbox2d, and thus become a contributor.

Contributors MUST

• adhere to the LambdaIsland Clojure Style Guide
• write patches that solve a problem. Start by stating the problem, then supply a minimal solution. *
• agree to license their contributions as MPL 2.0.
• not break the contract with downstream consumers. **
• not break the tests.

Contributors SHOULD

• update the CHANGELOG and README.
• add tests for new functionality.

If you submit a pull request that adheres to these rules, then it will almost certainly be merged immediately. However some things may require more consideration. If you add new dependencies, or significantly increase the API surface, then we need to decide if these changes are in line with the project's goals. In this case you can start by writing a pitch, and collecting feedback on it.

* This goes for features too, a feature needs to solve a problem. State the problem it solves, then supply a minimal solution.

** As long as this project has not seen a public release (i.e. is not on Clojars) we may still consider making breaking changes, if there is consensus that the changes are justified.

Copyright © 2021-2022 Arne Brasseur and Contributors

Licensed under the term of the Mozilla Public License 2.0, see LICENSE.