2020-01-03 17:46:31 -08:00
# Planck.js
2016-03-23 22:59:54 -04:00
2021-04-10 17:38:41 -07:00
Planck.js is JavaScript (TypeScript) rewrite of Box2D physics engine for cross-platform HTML5 game development.
2019-07-28 13:57:58 -07:00
2020-07-25 20:43:25 -07:00
#### Motivations
2017-03-22 20:04:57 -04:00
2017-01-23 20:48:22 -05:00
- Taking advantage of Box2D's efforts and achievements
- Developing readable and maintainable JavaScript code
- Optimizing the library for web and mobile platforms
2017-03-22 10:50:23 -04:00
- Providing a JavaScript-friendly API
2017-01-23 20:48:22 -05:00
2019-07-28 12:13:15 -07:00
2021-01-11 20:37:42 -08:00
## Documentation
2021-04-17 11:09:11 -07:00
- [Documentation Wiki ](https://github.com/shakiba/planck.js/wiki/ ) - This is the best place to start, and find other resources
2021-01-30 16:03:34 -08:00
- [Examples ](https://piqnt.com/planck.js/ ) - Online examples with editable code
2021-01-28 21:46:12 -08:00
## Community
- [Discord ](https://discord.gg/znjh6J7 ) - Community discussions and Q/A
- [Twitter @Piqnt ](https://twitter.com/piqnt ) - Updates and news
- [GitHub ](https://github.com/shakiba/planck.js/ ) - Source code and issues
2021-01-28 22:02:15 -08:00
## 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'`
2021-05-07 16:44:05 -07:00
## Updates
#### v1.0-alpha
- Source code is migrated to TypeScript, to improves library usability, documentation and maintenance.
- Package name for v1.0+ is changed to `planck` . Package name for releases *before v1.0* is `planck-js` .
- `planck.internal` namespace is deprecated and everything is directly available under main namesapce (except `planck.internal.stats` ).
- Source files are moved to `/src` directory (from `/lib` ) and directory layout is updated to match Box2D.
- Rollup is used to build the project.
2021-03-21 14:27:20 -07:00
## Install
2021-05-07 16:44:05 -07:00
### v0.3 (stable release)
To install `planck-js@0.3` (stable release) see [v0.3 branch ](https://github.com/shakiba/planck.js/tree/v0.3#install ).
### v1.0 (alpha)
Staring from v1.0 package name is changed to `planck` .
Releases and updates before v1.0 will remain available under `planck-js` .
##### CDN
Planck.js is available on [jsDelivr ](https://www.jsdelivr.com/package/npm/planck ).
##### NPM
Install npm package.
```sh
npm install planck
```
Import it in your code.
```js
import * as planck from 'planck';
```
##### Testbed
Use CDN in a web page.
```html
< html > < body >
< script src = "//cdn.jsdelivr.net/npm/planck @latest/dist/planck -with-testbed.min.js" ></ script >
< script >
planck.testbed(function(testbed) {
// Your testbed code
});
< / script >
< / body > < / html >
```
Use NPM package in Node.
```js
const planck = require('planck/dist/planck-with-testbed');
2021-03-21 14:27:20 -07:00
2021-05-07 16:44:05 -07:00
planck.testbed(function() {
// ...
});
```
2021-03-21 14:27:20 -07:00
2021-01-11 20:37:42 -08:00
## Projects
2020-09-25 22:01:36 -07:00
2019-07-12 16:29:10 -07:00
#### Games
2019-08-06 21:35:48 -07:00
- [Astray 2 ](https://wwwtyro.github.io/astray-2/ ) ([source ](https://github.com/wwwtyro/astray-2 )) by Rye Terrell
2021-05-27 20:02:55 -07:00
- [Rope ](https://one.fserb.com/rope/ ) ([source ](https://github.com/fserb/one/blob/master/src/rope.js )) by Fernando Serboncini
2020-06-30 03:12:36 -07:00
- [I have to flap ](https://ihavetoflap.web.app/ ) by Elias Ku
2020-06-23 20:03:49 -07:00
- [Hoverator ](https://vgel.me/hoverator/ ) by Jonathon Vogel
2021-03-15 20:57:52 -07:00
- [Totem Destroyer ](https://www.emanueleferonato.com/2021/03/13/build-a-html5-game-like-old-flash-glory-totem-destroyer-using-phaser-and-planck-js-physics-engine/ ) by Emanuele Feronato
- [Pancake Tower ](https://pancake-tower.netlify.app/ ) by Aloysius Kieth
2019-07-12 16:29:10 -07:00
- [Acolyte Fight ](https://acolytefight.io/ )
2021-01-06 00:07:27 -08:00
- [Comeback ](http://romainclement.eu/Comeback/ ) by Romain Clément
2019-07-12 16:29:10 -07:00
- [Nitro Clash ](http://nitroclash.io/ )
2020-06-24 22:53:52 -07:00
- [Space Rage 2 ](https://space-rage-2-bad-prospects-dev.netlify.app/ ) by Hendrik Mans
2019-08-01 16:53:12 -07:00
- Air Hockey ([source ](https://github.com/Steveeeie/webgl-air-hockey-server )) by Steve Meredith
2019-08-01 19:54:08 -07:00
- [Coined ](https://coined--parameterized.repl.co/ ) ([source ](https://repl.it/talk/challenge/Coined/13314 ))
2020-04-10 19:50:43 +02:00
- [Zzzone! ](https://www.engehausen.de/jan/zzz.html ) ([source ](https://github.com/smurf667/zzzone )) by Jan Engehausen
2021-03-15 20:57:52 -07:00
- [Star Fly ](https://fxplayground.herokuapp.com/ ) by Kal Torak
2019-07-12 16:29:10 -07:00
2021-03-15 20:57:52 -07:00
#### Dynamic Visualization
2020-05-31 20:21:22 -07:00
- [Fall / Fill ](https://twitter.com/jezzamonn/status/1246212104593403905 ) by Jez Swanson
2019-08-01 08:53:15 -07:00
- [1000 Unique Postcards ](https://twitter.com/andreasgysin/status/956131218386509824 ) by Andreas Gysin
- [Flag in the Wind ](https://codepen.io/unframework/pen/OrOMBg ) by Nick Matantsev
2020-05-31 20:21:22 -07:00
- [Dynamic Convex Hull ](https://codepen.io/bozheng-stokes/pen/abormNX ) by Bo Zheng
- [Chaotic Water Wheel ](https://john-hearn.info/articles/simulate-chaotic-water-wheel-with-planck ) by John Hearn
2021-03-15 20:57:52 -07:00
#### Science and AI
- [Handle ](https://twitter.com/marurur/status/1240141036606947329 ) by Ichiro Maruta
- [Q-Learning Ragdoll ](https://codepen.io/mikkokam/pen/EGEjYe ) by Mikko Kämäräinen
2020-05-31 20:21:22 -07:00
- [Walking EA ](https://matsemann.github.io/walkingea/ ) by Mats Krüger Svensson
- [Neuroevolution Bots ](https://twitter.com/mishig25/status/1077672181503590400 ) by Mishig Davaadorj
2021-03-15 20:57:52 -07:00
- [Bubble Treemaps ](https://github.com/grtlr/bubble-treemaps )
- [Walking Robot ](https://neuro-ts.vercel.app/walk ) [Source ](https://github.com/suhdonghwi/neuro-ts/ )
2019-07-28 00:50:14 -07:00
2021-01-28 22:02:15 -08:00
#### Game Development
- [Space ](https://piqnt.com/space/ )
- [Modd.io ](https://www.modd.io/ )
2019-07-28 12:13:15 -07:00
2017-03-22 12:56:49 -04:00
## Credits
2017-01-25 15:02:53 -05:00
2020-06-30 03:12:06 -07:00
[Box2D ](https://github.com/erincatto/box2d ) is a popular C++ 2D rigid-body physics engine created by [Erin Catto ](https://twitter.com/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.
2017-01-25 15:02:53 -05:00
2018-08-15 20:53:57 -07:00
[Planck.js ](https://github.com/shakiba/planck.js ) is developed and maintained by [Ali Shakiba ](https://github.com/shakiba/ ).
2017-01-25 15:02:53 -05:00
2018-08-15 20:53:11 -07:00
TypeScript definitions for planck.js are developed by [Oliver Zell ](https://github.com/zOadT ).
2019-07-31 21:55:29 -07:00
2017-02-04 22:30:53 -05:00
## License
2017-01-25 15:02:53 -05:00
2021-01-25 22:41:21 -08:00
Planck.js is [available under the MIT license ](./LICENSE.txt ).