ammo.js

ammo.js is a direct port of the Bullet physics engine to JavaScript, using Emscripten. The source code is translated directly to JavaScript, without human rewriting, so functionality should be identical to the original Bullet.

'ammo' stands for "Avoided Making My Own js physics engine by compiling bullet from C++" ;)

ammo.js is zlib licensed, just like Bullet.

Discussion takes place on IRC at #emscripten on Mozilla's server (irc.mozilla.org)

Status

ammo.js works, see an online demo at

http://syntensity.com/static/bullet.html

Instructions

builds/ contains prebuilt versions of ammo.js:

ammo.js: Optimized and minified build. This is probably what you want. ammo.slow.js: A very slow debug version. This includes many runtime checks and safety measures.

You can also build ammo.js yourself, as follows:

• Get Emscripten

  http://emscripten.org

  and set it up. See

  https://github.com/kripken/emscripten/wiki/Getting-started

• Run the build script,

  ./build.py

  which should generate builds/ammo.new.js. Note that this is by default an unoptimized build which will run very slowly. See build.py for optimizations.

• Run the test,

  python test.py

Usage

The most straightforward thing is if you want to write your code in C++, and run that on the web. If so, then compile your code into LLVM, link it with bullet, and compile that to JavaScript using emscripten. (The easiest way to link it is to add your .bc file to the llvm-link command in build.py.)

If, on the other hand, you want to write code in JavaScript, you can use the autogenerated binding code. A complete example appears in

examples/hello_world.js

That is HelloWorld.cpp from Bullet, translated to JavaScript. Other examples in that directory might be useful as well.

API Differences

ammo.js autogenerates its API from the Bullet source code, so it should be basically identical. There are however some differences:

• Functions returning or getting float& or btScalar& are converted to float. The reason is that float& is basically float* with nicer syntax in C++, but from JavaScript you would need to write to the heap every time you call such a function, making usage very ugly. With this change, you can do |new btVector3(5, 6, 7)| and it will work as expected. If you find a case where you need the float& method, please file an issue.

• Not all classes are exposed, for various reasons. Please file an issue if you find that something you need is missing.

• Each call to |new X()| will leak. We have not integrated C++ memory management with the JavaScript GC yet.

• Functions that return an entire object, like |btQuaternion someFunc()|, will return a reference to a static object held inside the binding function. That means that you cannot call the binding function multiple times and still use the values - you must copy them.

Reporting Issues

If you find a bug in ammo.js and file an issue, please test your code with the slow unoptimized build in builds/ammo.slow.js too, and mention in the issue how that works (the optimized build applies a few speculative speedups that can, in theory, break things; the slow build is safer).