easonzhuyi/planck.js

2D JavaScript Physics Engine

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

Documentation

• Documentations Wiki - This is the best place to start, and find other resources
• Examples - Online examples with editable code

Community

• Discord - Community discussions and Q/A
• Twitter @Piqnt - Updates and news
• GitHub - Source code and issues

Updates

v0.4.0

• Migrated to ESM and Rollup
• package.json main now points to UMD build output under /dist
• planck.internal namespace is deprecated and merged with planck (except planck.internal.stats)

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 closely follows Box2D API, with the following differences:

• b2 prefix is dropped from class names, for example b2World is now available as planck.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.
• Contact filtering can be customized by overriding shouldCollide method of Fixture.
• Listener classes are replaced with simple functions.
• World#on(eventName, listenerFn) and World#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'

Install

CDN

Planck.js is available on jsDelivr.

NPM

Install:

npm install planck-js --save

Core library:

const planck = require('planck-js');

With testbed:

const planck = require('planck-js/dist/planck-with-testbed');

planck.testbed(function() {
  ...
});

Projects

Games

• Astray 2 (source) by Rye Terrell
• I have to flap by Elias Ku
• Hoverator by Jonathon Vogel
• Totem Destroyer by Emanuele Feronato
• Pancake Tower by Aloysius Kieth
• Acolyte Fight
• Comeback by Romain Clément
• Nitro Clash
• Space Rage 2 by Hendrik Mans
• Air Hockey (source) by Steve Meredith
• Coined (source)
• Zzzone! (source) by Jan Engehausen
• Star Fly by Kal Torak

Dynamic Visualization

• Fall / Fill by Jez Swanson
• 1000 Unique Postcards by Andreas Gysin
• Flag in the Wind by Nick Matantsev
• Dynamic Convex Hull by Bo Zheng
• Chaotic Water Wheel by John Hearn

Science and AI

• Handle by Ichiro Maruta
• Q-Learning Ragdoll by Mikko Kämäräinen
• Walking EA by Mats Krüger Svensson
• Neuroevolution Bots by Mishig Davaadorj
• Bubble Treemaps
• Walking Robot Source

Game Development

• Space
• Modd.io

Install

CDN

Planck.js is available on jsDelivr.

NPM

npm install planck-js --save

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 MIT license.