clonable-planck-js

v0.1.44

Published

2 years ago

2D JavaScript physics engine for cross-platform HTML5 game development

Downloads

0High
0Medium
0Low

fasterthanlime

box2d html5 javascript game physics engine 2d mobile

Planck.jsα

Planck.js is JavaScript rewrite of Box2D physics engine for cross-platform HTML5 game development. Check out demos!

Motivations

Key motivations for the development of this project are:

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

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="https://cdn.jsdelivr.net/npm/[email protected]/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

To receive updates about changes and progress follow @piqnt on twitter.

Download

Latest builds are available on releases page.

CDN

Planck.js is available on jsDelivr.

NPM

npm install planck-js --save

Bower

bower install planck-js --save

Usage

Planck.js does not use any renderer by default. To use or integrate it 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();

  window.requestAnimationFrame(function() {
    // 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
      }
    }
  });

   world.on('remove-fixture', function(fixture) {
    // remove fixture from ui
  });
</script>

API

Planck.js public API closely follows Box2D API (see Resources), 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 made immutable and are not cloned when used to create fixtures.
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'
- 'joint-removed'
- 'fixture-removed'
- 'body-removed'

Resources

Box2D Manual and FAQ are highly recommended to get started.
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

If you know any other useful resource, please add it or submit an issue.

Testbed

Another way to use testbed and try included examples (in example directory) is running testbed with live build locally:

Install git and npm
Clone or download this repository
Install npm and bower dependencies:
```
 npm install
```
Run testbed and open it in your web browser (see command-line output for URL to open):
```
 npm run testbed
```

Architecture

Planck.js includes Box2D algorithms without modification and its internal architecture and public API are very similar to Box2D. However some changes and refactoring are made during rewrite to address differences between C++ and JavaScript.

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.

License

Planck.js is available under the zlib license.