DOCSEARCHbyAlgolia
Submit Docs

JoltPhysics.js

repository·main·Indexed 19 days ago

https://github.com/jrouwe/joltphysics.js

A WebAssembly port of JoltPhysics, a rigid body physics and collision detection library for games and VR applications. It provides high-performance physics simulations in web environments via WASM and asm.js, offering multiple distribution flavours for embedding, debugging, and multi-threading. Version 1.1.0 requires manual memory management for WASM-allocated objects.

Tokens
1.4K
Snippets
5
Records
6
Agent score
19%

What's inside jolt-physics

  1. How to manage memory and prevent leaks in JoltPhysics.js

    main

    Because this is a WASM port, memory management is manual. JavaScript's garbage collector does not clean up WASM-allocated memory.

    Manual Destruction

    Every object created with new Jolt.XXX must be explicitly destroyed using Jolt.destroy(object).

    Special Case: The Body class must be destroyed via the BodyInterface: BodyInterface.DestroyBody(body.GetID()).

    Reference Counting

    Many classes inherit from RefTarget and use reference counting. If you want to maintain ownership, call object.AddRef(). To release ownership, call object.Release(). When the count reaches 0, the object is destroyed.

    Common reference-counted classes include:

    • ShapeSettings, Shape
    • ConstraintSettings, Constraint
    • PhysicsMaterial
    • PhysicsScene
    • Ragdoll, RagdollSettings
    • CharacterBase, CharacterBaseSettings
    • Skeleton, SkeletonAnimation, SkeletonMapper
    • SoftBodySharedSettings
    • VehicleCollisionTester, VehicleControllerSettings, WheelSettings

    Note: If you pass a reference-counted object to another Jolt object (e.g., passing ShapeSettings to CompoundShapeSettings), the receiving object automatically increments the reference count. In these cases, you do not need to call AddRef() yourself.

  3. Build JoltPhysics.js from source

    main

    Building requires a Linux environment, Emscripten, and cmake.

    Run ./build.sh to build both Debug and Distribution builds, or ./build.sh Debug for only the Debug build.

    Build Options

    • -DENABLE_MEMORY_PROFILER=ON: Enables memory tracking to detect leaks.
    • -DDOUBLE_PRECISION=ON: Enables double precision mode (for worlds > 2km).
    • -DENABLE_SIMD=ON: Enables SIMD instructions (supported in Safari 16.4+; enabled by default in multithreaded builds).
    • -DBUILD_WASM_COMPAT_ONLY=ON: Speeds up build by only compiling the WASM compat version.
    • -DCROSS_PLATFORM_DETERMINISTIC=ON: Ensures results match the native C++ version.
    ./build.sh

  4. Import JoltPhysics.js via unpkg

    main

    You can import ESM bundles directly in the browser using 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>

  5. Choose a JoltPhysics.js flavour

    main

    The library is distributed in 7 different flavours depending on your requirements for WASM embedding, debugging, or multi-threading:

    • jolt-physics: WASM embedded in the bundle (wasm-compat).
    • jolt-physics/debug-wasm-compat: WASM embedded in the bundle with debug checking enabled (outputs errors to console and enables debug renderer).
    • jolt-physics/wasm: Separate WASM file (not embedded).
    • jolt-physics/asm: JavaScript version using asm.js.
    • jolt-physics/wasm-compat-multithread: WASM embedded in the bundle with multi-threading enabled.
    • jolt-physics/debug-wasm-compat-multithread: WASM embedded in the bundle, multi-threading enabled, and debug checking enabled.
    • jolt-physics/wasm-multithread: Separate WASM file with multi-threading enabled.
    // WASM embedded in the bundle
import Jolt from 'jolt-physics';
// or
import Jolt from 'jolt-physics/wasm-compat';

// WASM embedded in the bundle, debug checking enabled
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
import Jolt from 'jolt-physics/debug-wasm-compat-multithread';

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

  6. Configure the WASM file location for the 'wasm' flavour

    main

    When using the jolt-physics/wasm flavour, you must provide the location of the .wasm file. You can do this by passing a locateFile function to the default export. This is useful when using bundlers like Vite that treat WASM as an asset URL.

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

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