Skip to content
Direct port of the Bullet physics engine to JavaScript using Emscripten
Branch: master
Clone or download
mqp and kripken Expose btStridingMeshInterface.setScaling in IDL (#240)
To efficiently generate a btBvhTriangleMeshShape with scaling, you need to construct a btTriangleMesh and call this setScaling method on it prior to constructing the btBvhTriangleMeshShape -- if you instead call setLocalScale on the btBvhTriangleMeshShape after construction, it will have to rebuild the whole BVH.
Latest commit ac08f42 Mar 8, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
builds updated builds (#232) Jan 28, 2019
bullet Patched Bullet to include Raycast fix from 2.83 (#149) Nov 8, 2016
examples updated builds (#232) Jan 28, 2019
tests fix idl; add test for btShapeHull (#212) Sep 28, 2018
AUTHORS AUTHORS file Sep 5, 2011
bower.json finish make Apr 18, 2014
root.h updated build with btHeightfieldTerrainShape Nov 19, 2011 improve to handle more engines Oct 25, 2018





Example code to give you an idea of the API:

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.

Note: ammo.js has just been updated to a new porting approach. If you find some part of the Bullet API that is not supported that you need, please see

'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 (


builds/ammo.js contains a prebuilt version of ammo.js. This is probably what you want.

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


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

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


That is HelloWorld.cpp from Bullet, translated to JavaScript. Other examples in that directory might be useful as well. In particular see the WebGL demo code in


Bindings API

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

  • See for a description of the bindings tool we use here, which includes instructions for how to use the wrapped objects.

  • All ammo.js elements should be accessed through Ammo.*. For example, Ammo.btVector3, etc., as you can see in the example code.

  • Member variables of structs and classes can be accessed through setter and getter functions, that are prefixed with |get_| or |set_|. For example,


    will get m_rayToWorld from say a ClosestRayResultCallback. Native JavaScript getters and setters could give a slightly nicer API here, however their performance is potentially problematic.

  • 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, as only what is described in ammo.idl is wrapped. Please submit pull requests with extra stuff that you need and add.

  • There is experimental support for binding operator functions. The following might work:

    Operator Name in JS
    = op_set
    + op_add
    - op_sub
    * op_mul
    / op_div
    [] op_get
    == op_eq

Reducing Build Size

The size of the ammo.js builds can be reduced in several ways:

  • Removing uneeded interfaces from ammo.idl. Some good examples of this are btIDebugDraw and DebugDrawer, which are both only needed if visual debug rendering is desired.

  • Removing methods from the -s EXPORTED_RUNTIME_METHODS=[] argument in For example, Pointer_stringify is only needed if printable error messages are desired from DebugDrawer.


  • It's easy to forget to write |new| when creating an object, for example

    var vec = Ammo.btVector3(1,2,3); // This is wrong! Need 'new'!

    This can lead to error messages like the following:

    Cannot read property 'a' of undefined Cannot read property 'ptr' of undefined

    This is an annoying aspect of JavaScript, sadly.

Reporting Issues

If you find a bug in ammo.js and file an issue, please include a script that reproduces the problem. That way it is easier to debug, and we can then include that script in our automatic tests.

Release Process

Pushing a new build in builds/ammo.js should be done only after the following steps:

  • Build using python closure which generates the asm.js build, and python closure wasm which generates the wasm build.

  • Make sure it passes all automatic tests using python (build-name) Note that it uses SpiderMonkey by default, and SPIDERMONKEY_ENGINE is defined in ~/.emscripten, see the script contents for details.

  • Run the WebGL demo in examples/webgl_demo and make sure it looks ok, using something like firefox examples/webgl_demo/ammo.html (chrome will need a webserver as it doesn't like file:// urls)

Upstream Version

Bullet 2.82 patched with raycast fix from 2.83

You can’t perform that action at this time.