Planck.js
Planck.js is JavaScript rewrite of Box2D physics engine for cross-platform HTML5 game development.
Motivations
- Taking advantage of Box2D's efforts and achievements
- Developing readable and maintainable JavaScript code
- Optimizing the library for web and mobile platforms
- Providing a JavaScript-friendly API
Projects
See here for project examples.
Games
- Astray 2 (source) by Rye Terrell
- I have to flap by Elias Ku
- Hoverator by Jonathon Vogel
- Acolyte Fight
- Nitro Clash
- Space Rage 2 by Hendrik Mans
- Air Hockey (source) by Steve Meredith
- Coined (source)
- Zzzone! (source) by Jan Engehausen
Game Development
Other Projects
- Fall / Fill by Jez Swanson
- 1000 Unique Postcards by Andreas Gysin
- Flag in the Wind by Nick Matantsev
- Handle by Ichiro Maruta
- Q-Learning Ragdoll by Mikko Kämäräinen
- Dynamic Convex Hull by Bo Zheng
- Chaotic Water Wheel by John Hearn
- Walking EA by Mats Krüger Svensson
- Neuroevolution Bots by Mishig Davaadorj
Articles and Tutorials
- Phaser 3 with Planck.js by Emanuele Feronato
Integration
- notchris/phaser3-planck Phaser 3 Planck.js Plugin by Chris McGrane
- RealPeha/planck-renderer
Community
Updates and news: Twitter @Piqnt
Source code and issues: GitHub
Community discussions: Discord
Try it
To try Planck.js, simply add planck-with-testbed.js script to your HTML code and call planck.testbed(callback) with your code in callback. For example:
<html><body>
<script src="//cdn.jsdelivr.net/npm/planck-js@latest/dist/planck-with-testbed.js"></script>
<script>
planck.testbed(function(testbed) {
var world = planck.World();
// rest of your code
return world; // make sure you return the world
});
</script>
</body></html>Check out Car example on JS Bin to try it in practice.
Also see example directory for more testbed usage examples.
Install
CDN
Planck.js is available on jsDelivr.
NPM
npm install planck-js --save
API and Architecture
Planck.js includes Box2D algorithms without modification and its architecture is very similar to Box2D. However some internal changes and refactoring are made during rewrite to address differences between C++ and JavaScript.
Planck.js public API (see API Doc) closely follows Box2D API (see Resources), with the following differences:
b2prefix is dropped from class names, for exampleb2Worldis now available asplanck.World.- Method names are converted from UpperCamelCase to lowerCamelCase.
- Definition classes/objects (BodyDef, FixtureDef, etc.) are replaced by inline JavaScript objects (
{}). - Shapes are considered immutable and are not cloned when used to create fixtures.
- Listener classes are replaced with simple functions.
World#on(eventName, listenerFn)andWorld#off(eventName, listenerFn)are added to add and remove event listeners. Currently supported events are:'begin-contact''end-contact''pre-solve''post-solve''remove-joint''remove-fixture''remove-body'
Resources and References
- Plankc.js API Doc
- Box2D Manual and FAQ are highly recommended to learn how the library works.
- iforce2d website includes a collection of helpful tutorials and resources to learn Box2D.
Following resources are recommended if you are interested in learning about Box2D/Planck.js's internal details.
- Continuous Collision by Erin Catto (slides)
- Solving Rigid Body Contacts by Richard Tonge (slides)
- dyn4j Blog Posts by William Bittle
Rendering and Integration
Planck.js core library does not include any graphics by default, which means you have several options:
- Use Testbed, see Try it section to run release files in a web browser (or Development to debug testbed locally).
- Use an existing renderer, see Integration examples.
- Develop a renderer or integrate with a rendering library.
To create a renderer or integrate with a rendering library all you need to do
is call world.step(timeStep) in each frame, and then iterate over world entities to draw or update them.
You may also want to listen to world events to remove objects which are removed from the world. For example:
<script src="./path/to/planck.min.js"></script>
<script>
var world = planck.World();
// rendering loop
(function loop() {
// in each frame call world.step(timeStep) with fixed timeStep
world.step(1 / 60);
// iterate over bodies and fixtures
for (var body = world.getBodyList(); body; body = body.getNext()) {
for (var fixture = body.getFixtureList(); fixture; fixture = fixture.getNext()) {
// draw or update fixture
}
}
// request a new frame
window.requestAnimationFrame(loop);
})();
world.on('remove-fixture', function(fixture) {
// remove fixture from ui
});
</script>Development
For development, you can run testbed locally with a live build and try examples in example directory.
-
Install
gitandnpm -
Clone or download this repository
-
Install npm dependencies:
npm install -
Run testbed and open it in your web browser (see command-line output for URL to open):
npm run testbed
Credits
Box2D is a popular C++ 2D rigid-body physics engine created by Erin Catto. Box2D is used in several popular games, such as Angry Birds, Limbo and Crayon Physics, as well as game development tools and libraries such as Apple's SpriteKit.
Planck.js is developed and maintained by Ali Shakiba.
TypeScript definitions for planck.js are developed by Oliver Zell.
License
Planck.js is available under the zlib license.
