ammo.js Documentation

OPCODE (OPtimized COllision DEtection) is a C++ collision detection package designed for high performance and low memory footprint. It is suitable for mesh-mesh collision detection, N-body collisions, camera-vs-world collisions, picking, and rigid body simulation.

Key features include:

• Support for arbitrary meshes (convex, non-convex, or polygon soups).
• Implementation using AABB-trees, including no-leaf trees and quantized trees (decompressed on-the-fly).
• Support for both "first contact" and "all contacts" modes.
• Temporal coherence support (up to 10-20x faster in "first contact" mode).
• Various query types: Stabbing, Planes, and Volume queries (Sphere, AABB, OBB, LSS).
• Sweep-and-prune support.
• Hybrid collision models that can significantly reduce memory usage compared to standard trees.

The hkx2dae tool converts Havok HKX files into COLLADA Physics .dae files. This allows Havok tools to be used with any application that supports COLLADA Physics, such as the Bullet physics engine.

To add COLLADA Physics export capabilities to the Havok SimpleLoad serialization sample (hk550\Demo\Demos\Common\Api\Serialize\SimpleLoad), use this patch in combination with the free Havok 5.5 version.

The CDTestFramework is designed to test and compare the performance of different collision detection algorithms. It evaluates four specific implementations:

• OPCODE's "box pruning"
• Bullet's Multi SAP
• Bullet's dbvt (dynamic AABB tree)
• OPCODE's array-based SAP

Performance results vary based on the number of objects and the percentage of objects moving per frame. For example, with 8192 boxes and 10% movement, OPCODE's SAP performs similarly to Bullet's dbvt. With fewer boxes (1024 or 2048), OPCODE's SAP typically outperforms dbvt.

To use this modified CDTestFramework (which compares Bullet's dynamic AABB tree against various Sweep and Prune implementations), you must manually replace the existing directory in your Bullet installation.

1. Download Bullet 2.70.
2. Replace the contents of the following directory with the files from this repository: bullet-2.70/bullet-2.70/Extras/CDTestFramework.

You can use Docker to build ammo.js to keep your native environment clean. Use docker-compose to manage the build process:

docker-compose build        # Create the Docker image
docker-compose up           # Create container and build ammo.js
docker-compose run builder  # Re-build targets after modifications

To add arguments to cmake, edit the docker-compose.yml file.

To use GLUI in a Windows Win32 Console Application using Visual C++:

1. Include glui.h in your source files.
2. Add the GLUI library: msvc/lib/glui32.lib.
3. Add the following Microsoft OpenGL libraries to your project:
   • glui32.lib
   • glut32.lib
   • glu32.lib
   • opengl32.lib

To include GLUI in a Unix application:

1. Include glui.h in your source files.
2. Add the GLUI library to your makefile.
3. Important: Ensure the GLUI library is listed before the libglut.a library in your link order.

To build ammo.js yourself, you need Emscripten and cmake.

Standard Build

cmake -B builds
cmake --build builds

Windows (MinGW)

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

CMake Configuration Options

• -DCLOSURE=1: Compile with Closure compiler.
• -DTOTAL_MEMORY=268435456: Allocate a specific heap size (e.g., 256MB).
• -DALLOW_MEMORY_GROWTH=1: Enable a resizable heap.
• -DEMSCRIPTEN_ROOT=<path>: Specify the Emscripten location if not using emsdk.

To write physics code in JavaScript, use the autogenerated bindings provided by ammo.js. All physics elements must be accessed through the Ammo.* namespace.

Important: You must use the new keyword when creating objects. Failing to do so will result in errors like Cannot read property 'ptr' of undefined.

GLUI v2.3 introduces an object-oriented construction pattern. Instead of using the glui->add_... methods, you should now use the constructors of the specific control classes. This allows for easier creation of custom GLUI_Control subclasses.

Old Deprecated Pattern:

glui->add_button_to_panel( panel, "my button", myid, mycallback );

New Recommended Pattern:

new GLUI_Button( panel, "my button", myid, mycallback );

To add a control directly to the main GLUI instance, pass the GLUI object as the first argument to the constructor:

new GLUI_Button( glui, "my button", myid, mycallback );

To minimize the final build size, you can:

1. Remove unused interfaces from ammo.idl (e.g., btIDebugDraw and DebugDrawer if visual debug rendering is not required).
2. Remove unnecessary runtime methods from the -s EXPORTED_RUNTIME_METHODS=[] argument in make.py (e.g., removing UTF8ToString if you don't need printable error messages from the DebugDrawer).