# ammo.js

**Repository Path**: mirrors_cocos-creator/ammo.js

## Basic Information

- **Project Name**: ammo.js
- **Description**: Direct port of the Bullet physics engine to JavaScript using Emscripten
- **Primary Language**: Unknown
- **License**: Zlib
- **Default Branch**: cocos-master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 2
- **Created**: 2020-09-24
- **Last Updated**: 2025-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

ammo.js
=======

# Install for Cocos Creator

Install module via npm for Cocos Creator:
usage : `npm install github:cocos/cocos-ammo.js#cocos-master --save`。

# Compile pipeline

1. `./build.sh`
2. replace code of `builds/node/ammo.js.fix`
3. `npm run uglifyjs`

# Demos

 * [Cubes](http://kripken.github.com/ammo.js/examples/webgl_demo/ammo.html)
 * [Cubes (WebAssembly)](http://kripken.github.com/ammo.js/examples/webgl_demo/ammo.wasm.html)
 * [SoftBody-Rope](http://kripken.github.com/ammo.js/examples/webgl_demo_softbody_rope/index.html)
 * [SoftBody-Cloth](http://kripken.github.com/ammo.js/examples/webgl_demo_softbody_cloth/index.html)
 * [SoftBody-Volume](http://kripken.github.com/ammo.js/examples/webgl_demo_softbody_volume/index.html)
 * [Heightmap](http://kripken.github.com/ammo.js/examples/webgl_demo_terrain/index.html)
 * [Vehicle](http://kripken.github.io/ammo.js/examples/webgl_demo_vehicle/index.html)

# Overview

**Example code to give you an idea of the API**:

 * https://github.com/kripken/ammo.js/blob/master/examples/webgl_demo/worker.js#L6 which interacts with https://github.com/kripken/ammo.js/blob/master/examples/webgl_demo/ammo.html#L14

ammo.js is a direct port of the [Bullet physics
engine](http://bulletphysics.org/) 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
https://github.com/kripken/ammo.js/issues/60**

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

Instructions
------------

`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:

 * Get Emscripten

      http://emscripten.org

   and set it up. See

      http://kripken.github.io/emscripten-site/docs/getting_started/

 * Run the build script,

      `python make.py`

   which should generate builds/ammo.js.

 * Optionally, run the automatic tests,

      `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 you can build your C++ code with emscripten
normally and either build and link Bullet using

https://emscripten.org/docs/compiling/Building-Projects.html

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

  `examples/hello_world.js`

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

  `examples/webgl_demo/ammo.html`


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 https://github.com/kripken/emscripten/wiki/WebIDL-Binder
    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,

      `rayCallback.get_m_rayToWorld()`

    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 make.py. For example, `UTF8ToString` is only needed if printable error messages are desired from `DebugDrawer`.


Troubleshooting
===============

  * 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 make.py closure       which generates the asm.js
    build, and   python make.py closure wasm  which generates the wasm
    build.

  * Make sure it passes all automatic tests using
    python test.py (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](https://github.com/bulletphysics/bullet3/commit/7151865c16ba996996206e1fd7869cbb1e7edd8d)