@barclah/jolt-physics

JoltPhysics.js

This project enables using Jolt Physics in JavaScript.

Demos

Go to the demos page to see the project in action.

Using

This library comes in 3 flavours:

• wasm-compat - A WASM version with the WASM file (encoded in base64) embedded in the bundle
• wasm - A WASM version with a separate WASM file
• asm - A JavaScript version that uses asm.js

See falling_shapes.html for a example on how to use the library.

Documentation

The interface of the library is the same as the C++ interface of JoltPhysics, this means that you can use the C++ documentation as reference.

Almost all of the Jolt interface has been exposed. Check JoltJS.idl if a particular interface has been exposed. If not, edit JoltJS.idl and JoltJS.h and send a pull request, or open an issue.

Installation

This library is distributed as ECMAScript modules on npm:

npm install jolt-physics

The different flavours are available via entrypoints on the npm package:

// WASM embedded in the bundle
import Jolt from 'jolt-physics';
import Jolt from 'jolt-physics/wasm-compat';

// WASM
import Jolt from 'jolt-physics/wasm';

// asm.js
import Jolt from 'jolt-physics/asm';

You can also import esm bundles with unpkg:

<script type="module">
    // import latest
    import Jolt from 'https://www.unpkg.com/jolt-physics/dist/jolt-physics.wasm-compat.js';

    // or import a specific version
    import Jolt from 'https://www.unpkg.com/jolt-physics@x.y.z/dist/jolt-physics.wasm-compat.js';
</script>

Where x.y.z is the version of the library you want to use.

Using the WASM flavour

To use the wasm flavour, you must either serve the WASM file jolt-physics.wasm.wasm alongside jolt-physics.wasm.js, or use a bundler that supports importing an asset as a url, and tell Jolt where to find the WASM file.

To specify where to retrieve the WASM file from, you can pass a locateFile function to the default export of jolt-physics/wasm. For example, using vite this would look like:

import initJolt from "jolt-physics";
import joltWasmUrl from "jolt-physics/jolt-physics.wasm.wasm?url";

const Jolt = await initJolt({
  locateFile: () => joltWasmUrl,
});

For more information on the locateFile function, see the Emscripten documentation.

Building

This project has only been compiled under Linux.

• Install emscripten and ensure that its environment variables have been setup
• Install cmake
• Run ./build.sh Distribution for the optimized build, ./build.sh Debug for the debug build.

Additional options that can be provided to build.sh:

• -DENABLE_MEMORY_PROFILER=ON will enable memory tracking to detect leaks.
• -DDOUBLE_PRECISION=ON will enable the double precision mode. This allows worlds larger than a couple of km.
• -DENABLE_SIMD=ON will enable SIMD instructions. Safari 16.4 was the last major browser to support this (in March 2023).
• -DENABLE_MULTI_THREADING=ON will enable multi threading. Note that due to a bug in Safari this currently doesn't work in that brower. It is also incompatible with any JavaScript callback function that are triggered from web workers. See this ticket.
• -DBUILD_WASM_COMPAT_ONLY=ON speeds up the build by only compiling the WASM compat version which the examples use.

Running

By default the examples use the WASM version of Jolt. This requires serving the html file using a web server rather than opening the html file directly.

Go open a terminal in this folder and run the following commands:

cd serveexamples
npm install
npm run serve

If you need to debug the C++ code take a look at WASM debugging.

Memory Management

The samples are very bad at cleaning up after themselves (basically they don't). When using emscripten to port a library to WASM, nothing is cleaned up automatically, so everything you newed with new Jolt.XXX needs to be destroyed by Jolt.destroy(...).

On top of this, Jolt uses reference counting for a number of its classes (everything that inherits from RefTarget). The most important classes are:

• ShapeSettings
• Shape
• ConstraintSettings
• Constraint
• PhysicsMaterial
• GroupFilter
• SoftBodySharedSettings
• VehicleCollisionTester
• VehicleController
• WheelSettings
• CharacterBaseSettings
• CharacterBase

Reference counting objects start with a reference count of 0. If you want to keep ownership over the object, you need to call object.AddRef(), this will increment the reference count. If you want to release ownership you call object.Release(), this will decrement the reference count and if the reference count reaches 0 the object will be destroyed. If, after newing, you pass a reference counted object on to another object (e.g. a ShapeSettings to a CompoundShapeSettings or a Shape to a Body) then that other object will take a reference, in that case it is not needed take a reference yourself beforehand so you can skip the calls to AddRef/Release. Note that it is also possible to do new Jolt.XXX followed by Jolt.destroy(...) for a reference counted object if no one took a reference.

The Body class is also a special case, it is destroyed through BodyInterface.DestroyBody(body.GetID()) (which internally destroys the Body).

Almost everything else can be destroyed straight after it has been passed to Jolt. An example that shows how to properly clean up using Jolt is here.

Projects using JoltPhysics.js

• Babylon.js plugin - A plugin that replaces the default physics engine with Jolt.
• react-three-jolt - Wraps Jolt to make it easy to use in react-three-fiber.
• r3f-jolt - Another wrapper for react-three-fiber.

License

The project is distributed under the MIT license.