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.

‘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.


The most straightforward thing is if you want to write your code in C++, and run that on the web. If so, then you can build your C++ code with emscripten normally and either build and link Bullet using

or you can use Bullet directly from emscripten-ports, with -s USE_BULLET=1. In both cases, you don’t need ammo.js, just plain Bullet.

If, on the other hand, you want to write code in JavaScript, you can use the autogenerated binding code in ammo.js. 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:


In order to build ammo.js yourself, you will need Emscripten and cmake.

For more information about setting up Emscripten, see the getting started guide.

To configure and build ammo into the builds directory, run the following:

  $ cmake -B builds
  $ cmake --build builds

There are also some key options that can be specified during cmake configuration, for example:

  $ cmake -B builds -DCLOSURE=1                # compile with closure
  $ cmake -B builds -DTOTAL_MEMORY=268435456   # allocate a 256MB heap
  $ cmake -B builds -DALLOW_MEMORY_GROWTH=1    # enable a resizable heap

On windows, you can build using cmake’s mingw generator:

  > cmake -B builds -G 'MinGW Makefiles'
  > cmake --build builds

Note that if you have not installed emscripten via the emsdk, you can configure its location with -DEMSCRIPTEN_ROOT.

Building using Docker

ammo.js can also be built with Docker. This offers many advantages (keeping its native environment clean, portability, etc.). To do this, you just have to install Docker and run:

  $ docker-compose build        # to create the Docker image
  $ docker-compose up           # to create the Docker container and build ammo.js
  $ docker-compose run builder  # to build again the ammojs targets after any modification

If you want to add arguments to cmake, you have to edit the docker-compose.yml file.

Reducing Build Size

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


You can run the automatic tests with npm test, which in turn will run ava against both the javascript and WebAssembly builds:

$ npm run test-js      # --> AMMO_PATH=builds/ammo.js ava
$ npm run test-wasm    # --> AMMO_PATH=builds/ammo.wasm.js ava

It’s also possible to run ava directly for more options:

$ npx ava --verbose
$ npx ava --node-arguments inspect

When no AMMO_PATH is defined, builds/ammo.js is tested by default.

Running the Examples

http-server is included as a dev dependency as an easy way to run the examples. Make sure to serve everything from the repo root so that the examples can find ammo in the builds directory:

  $ npx http-server -p 3000 .


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:

Upstream Version

Bullet 2.82 patched with raycast fix from 2.83