ammo.js
Install for Cocos Creator 3D
Install module via npm for cocos creator 3d:
usage : npm install github:cocos-creator/ammo.js#cocos-master --save
。
Compile pipeline
./build.sh
- replace code of
builds/node/ammo.js.fix
npm run uglifyjs
Demos
Overview
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
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:
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