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 7 flavours:
- wasm-compat - A WASM version with the WASM file (encoded in base64) embedded in the bundle
- debug-wasm-compat - Same as wasm-compat but with debug checking enabled (outputs errors to the console and enables the debug renderer).
- wasm - A WASM version with a separate WASM file
- asm - A JavaScript version that uses asm.js
- wasm-compat-multithread - Same as wasm-compat but with multi threading enabled.
- debug-wasm-compat-multithread - Same as wasm-compat-multithread but with debug checking enabled (outputs errors to the console and enables the debug renderer).
- wasm-multithread - Same as wasm but with multi threading enabled.

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

$3

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 the entire 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.

$3

This library is distributed as ECMAScript modules on npm:

``sh
npm install jolt-physics
`

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

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

// WASM embedded in the bundle, debug checking enabled (outputs errors to the console and enables the debug renderer)
import Jolt from 'jolt-physics/debug-wasm-compat';

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

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

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

// WASM embedded in the bundle, multithread enabled, debug checking enabled (outputs errors to the console and enables the debug renderer)
import Jolt from 'jolt-physics/debug-wasm-compat-multithread';

// WASM, multithread enabled
import Jolt from 'jolt-physics/wasm-multithread';
`

You can also import esm bundles with unpkg:

`html

`

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

$3

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:

`js
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` to build both the Debug and Distribution build, `./build.sh Debug` for only 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). The multithreaded builds have this on by default.
* `-DBUILD_WASM_COMPAT_ONLY=ON` speeds up the build by only compiling the WASM compat version which the examples use.
* `-DCROSS_PLATFORM_DETERMINISTIC=ON` builds the library so that it produces the same results as the native version of the library. For more info click here.

Running

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

Open a terminal in this folder and run the following commands:

`
npm install
npm run examples
`

Then navigate to: http://localhost:3000/

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
* PathConstraintPath
* PhysicsMaterial
* GroupFilter
* SoftBodySharedSettings
* VehicleCollisionTester
* VehicleControllerSettings
* WheelSettings
* CharacterBaseSettings
* CharacterBase
* Skeleton
* SkeletonAnimation
* SkeletonMapper
* PhysicsScene
* RagdollSettings
* Ragdoll

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.
* GDevelop - An Open-source, cross-platform 2D/3D/multiplayer game engine. See announcement.
* react-three-jolt - Wraps Jolt to make it easy to use in react-three-fiber.
* r3f-jolt - Another wrapper for react-three-fiber.
* Synthesis - A Robotics Simulator for Autodesk Fusion CAD Designs

License

The project is distributed under the MIT license.