@aosengine/physics-jolt

Interfaces

BodyArgs

Everything needed to create one body. Mirrors the WIT add-body command, minus the entity handle, which the host module owns.

Properties

angularDamping?

optional angularDamping?: number;

Angular velocity damping per second. Defaults to 0.05.

dims

dims: readonly number[];

Shape dimensions, in metres: box half-extents [hx, hy, hz]; sphere [radius]; capsule and cylinder [radius, halfHeight]. Ignored for mesh and convex.

flags?

optional flags?: BodyFlags;

Optional switches.

friction

friction: number;

Coulomb friction, 0..1.

geometry?

optional geometry?: Shape;

Prebuilt shape for mesh and convex bodies, from meshShapeFromGeometry or convexHullFromPoints. The world takes its own reference, so one shape can back many bodies.

id

id: number;

Guest-minted handle. Must not already exist in this world.

kind

kind: BodyKind;

Body class.

layer

layer: number;

What this body is, as a bitset.

linearDamping?

optional linearDamping?: number;

Linear velocity damping per second. Defaults to 0.05, Jolt's own default.

mask

mask: number;

What this body collides with, as a bitset of other bodies' layers.

mass

mass: number;

Kilograms. Ignored for static, kinematic and character bodies.

position

position: Vec3;

World-space position of the body origin.

restitution

restitution: number;

Bounciness, 0..1.

rotation

rotation: Quat;

World-space orientation, xyzw.

shape

shape: ShapeKind;

Shape family. mesh and convex additionally need BodyArgs.geometry.

BodyFlags

Per-body switches. Mirrors WIT body-flags.

Properties

ccd?

optional ccd?: boolean;

Use continuous collision detection (linear cast).

lockRotation?

optional lockRotation?: boolean;

Lock all rotation. The usual choice for a capsule.

noSleep?

optional noSleep?: boolean;

Never let the solver put this body to sleep.

reportContacts?

optional reportContacts?: boolean;

Emit this body's contacts from PhysicsWorld.drainContacts.

Off by default. A world of resting crates generates a manifold per touching pair per step whether or not anyone reads it, and turning those into records costs a wasm crossing each. Ask for contacts on the handful of bodies whose collisions the game reacts to — the player, projectiles, triggers — and the rest cost nothing at all.

reportStay?

optional reportStay?: boolean;

Also emit the stay phase, once per step for as long as the pair touches.

Off by default, and only meaningful together with BodyFlags.reportContacts: begin and end are edges, so a game that tracks "am I touching this" needs no more than those two. stay is the expensive one — a box resting on the floor emits it sixty times a second forever — so it is separately opt-in, for the rare system that wants a live contact point (a grinding-sparks effect, a pressure plate that weighs what is on it).

sensor?

optional sensor?: boolean;

Trigger volume: generates contacts but no collision response.

ContactRecord

One contact event. Instances are pooled by the world and by the caller's out array; copy anything you want to keep past the next drainContacts.

Properties

a

a: number;

Guest body id of the first body.

b

b: number;

Guest body id of the second body.

impulse

impulse: number;

Estimated normal impulse, newton-seconds. Jolt does not hand the solved impulse to a contact listener, so this is reduced mass * closing speed measured before the solve: right in order of magnitude, good enough to scale an impact sound, not a physical measurement.

nx

nx: number;

Contact normal pointing from a towards b, x. Zero for end.

ny

ny: number;

Contact normal, y.

nz

nz: number;

Contact normal, z.

phase

phase: ContactPhase;

Whether the contact started, continued or ended.

px

px: number;

World-space contact point, x. Zero for end.

py

py: number;

World-space contact point, y. Zero for end.

pz

pz: number;

World-space contact point, z. Zero for end.

ConvexHullOptions

Options for convexHullFromPoints.

Properties

hullTolerance?

optional hullTolerance?: number;

Distance, in metres, below which the hull builder merges coplanar faces.

maxConvexRadius?

optional maxConvexRadius?: number;

Maximum convex radius used to round the hull off.

LayerOptions

Tuning for the object-layer slot table.

Properties

maxObjectLayers?

optional maxObjectLayers?: number;

How many distinct Jolt object layers the world may hand out. Half of them back static bodies and half back moving bodies, so the default of 64 allows 32 distinct (layer, mask) pairs on each side.

LoadJoltOptions

Options for loadJolt.

Extended by

PhysicsOptions

Properties

wasmUrl?

optional wasmUrl?: string;

Where jolt-physics.wasm.wasm is served from.

Omit it and the loader asks the host for jolt-physics/jolt-physics.wasm.wasm via import.meta.resolve, which is correct under node and under any bundler that keeps an import map. In a plain browser build, pass the URL your bundler minted for the asset:

import wasmUrl from 'jolt-physics/jolt-physics.wasm.wasm?url';

MeshShapeOptions

Options shared by the geometry shape builders.

Properties

maxTrianglesPerLeaf?

optional maxTrianglesPerLeaf?: number;

Triangles per BVH leaf. Higher builds faster and uses less memory, lower queries faster. Jolt's own default is 8.

PhysicsOptions

Options for physics.

Extends

PhysicsWorldOptions.LoadJoltOptions

Properties

gravity?

optional gravity?: Vec3;

Gravity in metres per second squared. Defaults to [0, -9.81, 0].

Inherited from

PhysicsWorldOptions.gravity

layers?

optional layers?: LayerOptions;

Object-layer slot tuning. See LayerOptions.

Inherited from

PhysicsWorldOptions.layers

maxBodies?

optional maxBodies?: number;

Hard ceiling on simultaneous bodies. Defaults to 4096.

Inherited from

PhysicsWorldOptions.maxBodies

maxBodyPairs?

optional maxBodyPairs?: number;

Maximum body pairs the broad phase tracks. Defaults to maxBodies * 2.

Inherited from

PhysicsWorldOptions.maxBodyPairs

maxContactConstraints?

optional maxContactConstraints?: number;

Maximum contact constraints per step. Defaults to maxBodies.

Inherited from

PhysicsWorldOptions.maxContactConstraints

maxContactsPerStep?

optional maxContactsPerStep?: number;

Contact records the world keeps for one step. Defaults to 256.

The pool is allocated up front and never grows, because growing it would allocate inside Jolt's own Step(). A step that produces more reportable contacts than this drops the surplus and warns once — raise the ceiling if the game really does want that many in a single step.

Inherited from

PhysicsWorldOptions.maxContactsPerStep

substeps?

optional substeps?: number;

Collision steps per fixed step. One is right for a 60 Hz simulation; raise it only if fast bodies tunnel and flags.ccd was not enough.

wasmUrl?

optional wasmUrl?: string;

Where jolt-physics.wasm.wasm is served from.

import wasmUrl from 'jolt-physics/jolt-physics.wasm.wasm?url';

Inherited from

LoadJoltOptions.wasmUrl

PhysicsService

The physics service, published by the engine under the id physics.

It is the PhysicsWorld plus the debug view, so engine.get('physics').raycast(...) works directly.

Extends

PhysicsWorld

Properties

bodyCount

readonly bodyCount: number;

Number of bodies currently in the world.

Inherited from

PhysicsWorld.bodyCount

movingBodyCount

readonly movingBodyCount: number;

Rows PhysicsWorld.readBodies would write: the non-static, enabled bodies. Size the destination from this and readBodies never has to be called twice.

Inherited from

PhysicsWorld.movingBodyCount

revision

readonly revision: number;

Bumped whenever the set of bodies changes: add, remove or enable/disable. Debug views rebuild their geometry when this moves and not otherwise.

Inherited from

PhysicsWorld.revision

Methods

addBody()

addBody(args): void;

Create a body. See BodyArgs.

Parameters

Parameter	Type
`args`	`BodyArgs`

Returns

void

Inherited from

PhysicsWorld.addBody

applyImpulse()

applyImpulse(
   id, 
   impulse, 
   point?
): void;

Apply an impulse, at the centre of mass unless point says otherwise.

Parameters

Parameter	Type
`id`	`number`
`impulse`	`Vec3`
`point?`	`Vec3`

Returns

void

Inherited from

PhysicsWorld.applyImpulse

bodyIds()

bodyIds(): readonly number[];

Snapshot of the live body ids, cheap and non-allocating to iterate.

Returns

readonly number[]

Inherited from

PhysicsWorld.bodyIds

debugWireframe()

debugWireframe(scene): void;

Attach or detach a wireframe debug view.

Pass a scene to attach, null to detach and free the geometry. The line buffer is rebuilt only when the set of bodies changes; the per-frame cost is a transform of the cached corners in update, with no allocation.

Parameters

Parameter	Type	Description
`scene`	`Scene`<`Object3DEventMap`> \| `null`	The scene to draw into, or null to remove the view.

Returns

void

dispose()

dispose(): void;

Free every Jolt object this world owns.

Returns

void

Inherited from

PhysicsWorld.dispose

drainContacts()

drainContacts(out): number;

Move queued contacts into out.

Parameters

Parameter	Type
`out`	`ContactRecord`[]

Returns

number

Inherited from

PhysicsWorld.drainContacts

groundState()

groundState(id): GroundState;

What a character body is standing on, as of the last step.

Parameters

Parameter	Type
`id`	`number`

Returns

GroundState

Inherited from

PhysicsWorld.groundState

moveCharacter()

moveCharacter(id, desiredVelocity): void;

Set the desired world-space velocity of a character body for the next step.

Parameters

Parameter	Type
`id`	`number`
`desiredVelocity`	`Vec3`

Returns

void

Inherited from

PhysicsWorld.moveCharacter

overlapSphere()

overlapSphere(
   center, 
   radius, 
   mask
): number[];

Guest body ids overlapping a sphere, nearest first.

Parameters

Parameter	Type
`center`	`Vec3`
`radius`	`number`
`mask`	`number`

Returns

number[]

Inherited from

PhysicsWorld.overlapSphere

overlapSphereInto()

overlapSphereInto(
   center, 
   radius, 
   mask, 
   out
): number;

Zero-allocation form of PhysicsWorld.overlapSphere.

Parameters

Parameter	Type
`center`	`Vec3`
`radius`	`number`
`mask`	`number`
`out`	`Uint32Array`

Returns

number

Inherited from

PhysicsWorld.overlapSphereInto

raycast()

raycast(
   origin, 
   direction, 
   maxDistance, 
   mask
): RayHit | null;

Closest hit along a ray, or null. The returned object is reused.

Parameters

Parameter	Type
`origin`	`Vec3`
`direction`	`Vec3`
`maxDistance`	`number`
`mask`	`number`

Returns

RayHit | null

Inherited from

PhysicsWorld.raycast

raycastBatch()

raycastBatch(
   rays, 
   mask, 
   out
): number;

Many rays, one call.

Parameters

Parameter	Type
`rays`	`Float32Array`
`mask`	`number`
`out`	`Float32Array`

Returns

number

Inherited from

PhysicsWorld.raycastBatch

readBodies()

readBodies(out): number;

Write stride-15 body rows into out. See PhysicsWorld.readBodies.

Parameters

Parameter	Type
`out`	`Float32Array`

Returns

number

Inherited from

PhysicsWorld.readBodies

readBodyBounds()

readBodyBounds(
   id, 
   out, 
   offset
): boolean;

Local-space bounds and world transform of a body, for debug drawing.

Parameters

Parameter	Type
`id`	`number`
`out`	`Float32Array`
`offset`	`number`

Returns

boolean

Inherited from

PhysicsWorld.readBodyBounds

readBodyPose()

readBodyPose(
   id, 
   out, 
   offset
): boolean;

World transform of a body alone, when its bounds are already known.

Parameters

Parameter	Type
`id`	`number`
`out`	`Float32Array`
`offset`	`number`

Returns

boolean

Inherited from

PhysicsWorld.readBodyPose

removeBody()

removeBody(id): void;

Destroy a body and release its shape reference. Unknown ids are ignored.

Parameters

Parameter	Type
`id`	`number`

Returns

void

Inherited from

PhysicsWorld.removeBody

setEnabled()

setEnabled(id, enabled): void;

Take a body out of the simulation without destroying it, or put it back.

Parameters

Parameter	Type
`id`	`number`
`enabled`	`boolean`

Returns

void

Inherited from

PhysicsWorld.setEnabled

setTransform()

setTransform(
   id, 
   position, 
   rotation, 
   teleport?
): void;

Teleport a body. Velocities are left alone unless teleport says otherwise.

Parameters

Parameter	Type	Description
`id`	`number`	Guest body handle.
`position`	`Vec3`	New world-space position.
`rotation`	`Quat`	New world-space orientation, xyzw.
`teleport?`	`boolean`	True for a hard cut: the body's linear and angular velocities are zeroed too, and a character forgets the velocity it was asked for. False (the default) moves the body and lets it keep moving.

Returns

void

Inherited from

PhysicsWorld.setTransform

setVelocity()

setVelocity(
   id, 
   linear, 
   angular
): void;

Set linear and angular velocity.

Parameters

Parameter	Type
`id`	`number`
`linear`	`Vec3`
`angular`	`Vec3`

Returns

void

Inherited from

PhysicsWorld.setVelocity

step()

step(dt, substeps?): number;

Advance the simulation.

Parameters

Parameter	Type
`dt`	`number`
`substeps?`	`number`

Returns

number

Inherited from

PhysicsWorld.step

PhysicsSteppedEvent

What physics:stepped carries.

The object is reused, so a listener must read it and not retain it — the event fires inside fixedUpdate and allocating one of these per step is the thing the whole phase is about.

Example

import type { PhysicsSteppedEvent } from '@aosengine/physics-jolt';

let rows = 0;
engine.events.on('physics:stepped', (e: PhysicsSteppedEvent) => {
  rows = e.movingBodyCount; // read it now; the object is rewritten next step
});

Properties

contacts

contacts: number;

Contact events this step queued for drainContacts.

dt

dt: number;

Length of the step that just ran, in seconds.

movingBodyCount

movingBodyCount: number;

Rows the next PhysicsService.readBodies will fill.

PhysicsWorld

A live Jolt simulation. Everything the engine's physics command stream and synchronous query imports need, and nothing else.

Extended by

PhysicsService

Properties

bodyCount

readonly bodyCount: number;

Number of bodies currently in the world.

movingBodyCount

readonly movingBodyCount: number;

Rows PhysicsWorld.readBodies would write: the non-static, enabled bodies. Size the destination from this and readBodies never has to be called twice.

revision

readonly revision: number;

Bumped whenever the set of bodies changes: add, remove or enable/disable. Debug views rebuild their geometry when this moves and not otherwise.

Methods

addBody()

addBody(args): void;

Create a body. See BodyArgs.

Parameters

Parameter	Type
`args`	`BodyArgs`

Returns

void

applyImpulse()

applyImpulse(
   id, 
   impulse, 
   point?
): void;

Apply an impulse, at the centre of mass unless point says otherwise.

Parameters

Parameter	Type
`id`	`number`
`impulse`	`Vec3`
`point?`	`Vec3`

Returns

void

bodyIds()

bodyIds(): readonly number[];

Snapshot of the live body ids, cheap and non-allocating to iterate.

Returns

readonly number[]

dispose()

dispose(): void;

Free every Jolt object this world owns.

Returns

void

drainContacts()

drainContacts(out): number;

Move queued contacts into out.

Parameters

Parameter	Type
`out`	`ContactRecord`[]

Returns

number

groundState()

groundState(id): GroundState;

What a character body is standing on, as of the last step.

Parameters

Parameter	Type
`id`	`number`

Returns

GroundState

moveCharacter()

moveCharacter(id, desiredVelocity): void;

Set the desired world-space velocity of a character body for the next step.

Parameters

Parameter	Type
`id`	`number`
`desiredVelocity`	`Vec3`

Returns

void

overlapSphere()

overlapSphere(
   center, 
   radius, 
   mask
): number[];

Guest body ids overlapping a sphere, nearest first.

Parameters

Parameter	Type
`center`	`Vec3`
`radius`	`number`
`mask`	`number`

Returns

number[]

overlapSphereInto()

overlapSphereInto(
   center, 
   radius, 
   mask, 
   out
): number;

Zero-allocation form of PhysicsWorld.overlapSphere.

Parameters

Parameter	Type
`center`	`Vec3`
`radius`	`number`
`mask`	`number`
`out`	`Uint32Array`

Returns

number

raycast()

raycast(
   origin, 
   direction, 
   maxDistance, 
   mask
): RayHit | null;

Closest hit along a ray, or null. The returned object is reused.

Parameters

Parameter	Type
`origin`	`Vec3`
`direction`	`Vec3`
`maxDistance`	`number`
`mask`	`number`

Returns

RayHit | null

raycastBatch()

raycastBatch(
   rays, 
   mask, 
   out
): number;

Many rays, one call.

Parameters

Parameter	Type
`rays`	`Float32Array`
`mask`	`number`
`out`	`Float32Array`

Returns

number

readBodies()

readBodies(out): number;

Write stride-15 body rows into out. See PhysicsWorld.readBodies.

Parameters

Parameter	Type
`out`	`Float32Array`

Returns

number

readBodyBounds()

readBodyBounds(
   id, 
   out, 
   offset
): boolean;

Local-space bounds and world transform of a body, for debug drawing.

Parameters

Parameter	Type
`id`	`number`
`out`	`Float32Array`
`offset`	`number`

Returns

boolean

readBodyPose()

readBodyPose(
   id, 
   out, 
   offset
): boolean;

World transform of a body alone, when its bounds are already known.

Parameters

Parameter	Type
`id`	`number`
`out`	`Float32Array`
`offset`	`number`

Returns

boolean

removeBody()

removeBody(id): void;

Destroy a body and release its shape reference. Unknown ids are ignored.

Parameters

Parameter	Type
`id`	`number`

Returns

void

setEnabled()

setEnabled(id, enabled): void;

Take a body out of the simulation without destroying it, or put it back.

Parameters

Parameter	Type
`id`	`number`
`enabled`	`boolean`

Returns

void

setTransform()

setTransform(
   id, 
   position, 
   rotation, 
   teleport?
): void;

Teleport a body. Velocities are left alone unless teleport says otherwise.

Parameters

Parameter	Type	Description
`id`	`number`	Guest body handle.
`position`	`Vec3`	New world-space position.
`rotation`	`Quat`	New world-space orientation, xyzw.
`teleport?`	`boolean`	True for a hard cut: the body's linear and angular velocities are zeroed too, and a character forgets the velocity it was asked for. False (the default) moves the body and lets it keep moving.

Returns

void

setVelocity()

setVelocity(
   id, 
   linear, 
   angular
): void;

Set linear and angular velocity.

Parameters

Parameter	Type
`id`	`number`
`linear`	`Vec3`
`angular`	`Vec3`

Returns

void

step()

step(dt, substeps?): number;

Advance the simulation.

Parameters

Parameter	Type
`dt`	`number`
`substeps?`	`number`

Returns

number

PhysicsWorldOptions

Options for createPhysicsWorld.

Extended by

PhysicsOptions

Properties

gravity?

optional gravity?: Vec3;

Gravity in metres per second squared. Defaults to [0, -9.81, 0].

layers?

optional layers?: LayerOptions;

Object-layer slot tuning. See LayerOptions.

maxBodies?

optional maxBodies?: number;

Hard ceiling on simultaneous bodies. Defaults to 4096.

maxBodyPairs?

optional maxBodyPairs?: number;

Maximum body pairs the broad phase tracks. Defaults to maxBodies * 2.

maxContactConstraints?

optional maxContactConstraints?: number;

Maximum contact constraints per step. Defaults to maxBodies.

maxContactsPerStep?

optional maxContactsPerStep?: number;

Contact records the world keeps for one step. Defaults to 256.

RayHit

One raycast result. The instance returned by raycast is reused.

Properties

body

body: number;

Guest body id that was hit.

distance

distance: number;

Distance from the ray origin, metres.

nx

nx: number;

Surface normal at the hit, x.

ny

ny: number;

Surface normal, y.

nz

nz: number;

Surface normal, z.

px

px: number;

Hit point, x.

py

py: number;

Hit point, y.

pz

pz: number;

Hit point, z.

Type Aliases

BodyKind

type BodyKind = "static" | "dynamic" | "kinematic" | "character";

Body class. Mirrors WIT body-kind, except that WIT spells static as fixed because static is a WIT keyword.

ContactPhase

type ContactPhase = "begin" | "stay" | "end";

Which side of a contact this record describes. Mirrors WIT contact-phase.

GroundState

type GroundState = "on-ground" | "on-steep-ground" | "not-supported" | "in-air";

What a character controller is standing on.

JoltInstance

type JoltInstance<K> = JoltModule[K] extends (...args) => infer R ? R : never;

Instance type of a Jolt class, e.g. JoltInstance<'Vec3'>.

Type Parameters

Type Parameter
`K` extends keyof `JoltModule`

JoltModule

type JoltModule = Awaited<ReturnType<typeof initJolt>>;

The initialised Jolt wasm module: every Jolt class, enum constant and helper (destroy, wrapPointer, ...) hangs off this object.

It mirrors the Jolt C++ API one to one, so the C++ reference is the documentation.

JoltShape

type JoltShape = JoltInstance<"Shape">;

A reference-counted Jolt collision shape.

Quat

type Quat = readonly [number, number, number, number];

A unit quaternion in xyzw order, matching three.js and Jolt.

ShapeKind

type ShapeKind = "box" | "sphere" | "capsule" | "cylinder" | "mesh" | "convex";

Collision shape family. Mirrors WIT shape-kind.

Vec3

type Vec3 = readonly [number, number, number];

A position or direction, in metres.

Variables

BODY_STRIDE

const BODY_STRIDE: 15 = 15;

Floats per row in the buffer PhysicsWorld.readBodies fills.

PACKAGE

const PACKAGE: "@aosengine/physics-jolt";

Package identity marker for @aosengine/physics-jolt.

Example

import { PACKAGE } from '@aosengine/physics-jolt';

console.log(PACKAGE); // '@aosengine/physics-jolt'

RAY_HIT_STRIDE

const RAY_HIT_STRIDE: 9 = 9;

Floats per row of the output buffer PhysicsWorld.raycastBatch fills.

RAY_STRIDE

const RAY_STRIDE: 7 = 7;

Floats per row of the input buffer PhysicsWorld.raycastBatch reads.

Functions

convexHullFromPoints()

function convexHullFromPoints(
   jolt, 
   points, 
   options?
): Shape;

Wrap a point cloud in its convex hull.

Unlike a mesh shape a convex hull can back a dynamic body, so this is the right shape for props lifted out of a splat scene: feed it the point cloud of the region you want solid and Jolt builds the tightest convex volume around it.

The returned shape carries one reference owned by you; see meshShapeFromGeometry.

Parameters

Parameter	Type	Description
`jolt`	typeof `Jolt`	The initialised Jolt module.
`points`	`Float32Array`	Point positions, stride 3 (x, y, z), in metres.
`options`	`ConvexHullOptions`	Hull build tuning.

Returns

Shape

A shape with a reference count of one.

Throws

When there are fewer than four points or Jolt cannot build a hull.

Example

import { convexHullFromPoints, loadJolt } from '@aosengine/physics-jolt';

const jolt = await loadJolt();
const cube = new Float32Array([
  -1, -1, -1, 1, -1, -1, -1, 1, -1, 1, 1, -1,
  -1, -1, 1, 1, -1, 1, -1, 1, 1, 1, 1, 1,
]);
const hull = convexHullFromPoints(jolt, cube);
hull.Release();

createContactRecord()

function createContactRecord(): ContactRecord;

Allocate one pooled ContactRecord.

Returns

ContactRecord

A zeroed record.

Example

import { createContactRecord, type ContactRecord } from '@aosengine/physics-jolt';

const pool: ContactRecord[] = [createContactRecord(), createContactRecord()];

createPhysicsWorld()

function createPhysicsWorld(jolt, options?): PhysicsWorld;

Create a Jolt simulation.

Parameters

Parameter	Type	Description
`jolt`	typeof `Jolt`	The module from loadJolt.
`options`	`PhysicsWorldOptions`	Gravity, capacity and layer tuning.

Returns

PhysicsWorld

A live world. Call PhysicsWorld.dispose when done.

Example

import { createPhysicsWorld, loadJolt } from '@aosengine/physics-jolt';

const world = createPhysicsWorld(await loadJolt(), { gravity: [0, -9.81, 0] });
world.addBody({
  id: 1,
  shape: 'box',
  dims: [10, 0.5, 10],
  position: [0, -0.5, 0],
  rotation: [0, 0, 0, 1],
  mass: 0,
  kind: 'static',
  layer: 0b10,
  mask: 0xffff,
  friction: 0.6,
  restitution: 0,
});
world.step(1 / 60);
world.dispose();

isJoltLoaded()

function isJoltLoaded(): boolean;

Whether loadJolt has been called in this process.

Returns

boolean

True once the singleton exists, in flight or resolved.

Example

import { isJoltLoaded, loadJolt } from '@aosengine/physics-jolt';

if (!isJoltLoaded()) await loadJolt();

loadJolt()

function loadJolt(options?): Promise<typeof Jolt>;

Instantiate the Jolt wasm module, once per page.

The module is a process-wide singleton: every call returns the same promise, so registering two physics worlds costs one wasm instantiation. Passing a different wasmUrl after the singleton exists is a bug and throws rather than silently loading a second copy of the engine.

Parameters

Parameter	Type	Description
`options`	`LoadJoltOptions`	Where to fetch the wasm binary from.

Returns

Promise<typeof Jolt>

The initialised Jolt module.

Throws

When called again with a different wasmUrl.

Example

import { loadJolt } from '@aosengine/physics-jolt';

const jolt = await loadJolt();
const up = new jolt.Vec3(0, 1, 0);
jolt.destroy(up); // Jolt never frees anything for you.

meshShapeFromGeometry()

function meshShapeFromGeometry(
   jolt, 
   positions, 
   indices, 
   options?
): Shape;

Turn indexed triangle geometry into a Jolt MeshShape.

A MeshShape is a triangle soup with a BVH over it: it can only back a static body, which is exactly what splat-environment colliders and baked level geometry are. Building one is expensive (it constructs a tree), so build it once at load time and share it across every body that needs it.

The returned shape carries one reference owned by you. addBody takes its own reference, so the shape survives bodies being removed; call shape.Release() when the geometry itself is gone.

Parameters

Parameter	Type	Description
`jolt`	typeof `Jolt`	The initialised Jolt module.
`positions`	`Float32Array`	Vertex positions, stride 3 (x, y, z), in metres.
`indices`	`Uint32Array`	Triangle indices, three per triangle, into `positions`.
`options`	`MeshShapeOptions`	Build tuning.

Returns

Shape

A shape with a reference count of one.

Throws

When the arrays are malformed or Jolt rejects the mesh.

Example

import { loadJolt, meshShapeFromGeometry } from '@aosengine/physics-jolt';

const jolt = await loadJolt();
const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 0, 1]);
const indices = new Uint32Array([0, 1, 2]);
const shape = meshShapeFromGeometry(jolt, positions, indices);
shape.Release();

physics()

function physics(options?): EngineModule;

The Jolt physics EngineModule.

Registered in the engine's module list, it loads the Jolt wasm module in init, publishes the world as the physics service, and steps the simulation once per fixed step — never in update, because reading body state there gives you an interpolated pose, not a simulated one.

Parameters

Parameter	Type	Description
`options`	`PhysicsOptions`	Gravity, capacity, layer tuning and the wasm location.

Returns

EngineModule

A module to hand to createEngine({ modules: [...] }).

Example

import { createEngine } from '@aosengine/core';
import { physics } from '@aosengine/physics-jolt';

const engine = await createEngine({
  canvas,
  manifest,
  modules: [physics({ gravity: [0, -9.81, 0] })],
});
const hit = engine.get('physics').raycast([0, 2, 0], [0, -1, 0], 10, 0xffff);

@aosengine/physics-jolt ​

Interfaces ​

BodyArgs ​

Properties ​

angularDamping? ​

dims ​

flags? ​

friction ​

geometry? ​

id ​

kind ​

layer ​

linearDamping? ​

mask ​

mass ​

position ​

restitution ​

rotation ​

shape ​

BodyFlags ​

Properties ​

ccd? ​

lockRotation? ​

noSleep? ​

reportContacts? ​

reportStay? ​

sensor? ​

ContactRecord ​

Properties ​

a ​

b ​

impulse ​

nx ​

ny ​

nz ​

phase ​

px ​

py ​

pz ​

ConvexHullOptions ​

Properties ​

hullTolerance? ​

maxConvexRadius? ​

LayerOptions ​

Properties ​

maxObjectLayers? ​

LoadJoltOptions ​

Extended by ​

Properties ​

wasmUrl? ​

MeshShapeOptions ​

Properties ​

maxTrianglesPerLeaf? ​

PhysicsOptions ​

Extends ​

Properties ​

gravity? ​

Inherited from ​

layers? ​

Inherited from ​

maxBodies? ​

Inherited from ​

maxBodyPairs? ​

Inherited from ​

maxContactConstraints? ​

Inherited from ​

maxContactsPerStep? ​

Inherited from ​

substeps? ​

wasmUrl? ​

Inherited from ​

PhysicsService ​

Extends ​

Properties ​

bodyCount ​

Inherited from ​

movingBodyCount ​

Inherited from ​

revision ​

Inherited from ​

@aosengine/physics-jolt

Interfaces

BodyArgs

Properties

angularDamping?

dims

flags?

friction

geometry?

id

kind

layer

linearDamping?

mask

mass

position

restitution

rotation

shape

BodyFlags

Properties

ccd?

lockRotation?

noSleep?

reportContacts?

reportStay?

sensor?

ContactRecord

Properties

a

b

impulse

nx

ny

nz

phase

px

py

pz

ConvexHullOptions

Properties

hullTolerance?

maxConvexRadius?

LayerOptions

Properties

maxObjectLayers?

LoadJoltOptions

Extended by

Properties

wasmUrl?

MeshShapeOptions

Properties

maxTrianglesPerLeaf?

PhysicsOptions

Extends

Properties

gravity?

Inherited from

layers?

Inherited from

maxBodies?

Inherited from

maxBodyPairs?

Inherited from

maxContactConstraints?

Inherited from

maxContactsPerStep?

Inherited from

substeps?

wasmUrl?

Inherited from

PhysicsService

Extends

Properties

bodyCount

Inherited from

movingBodyCount

Inherited from

revision

Inherited from