@driftengine/physics 3.61.0

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Collision shapes, the spatial hash over them, and the swept kinematic sweep.
+ *
+ * **This package imports no other engine package**, the same shape as `@driftengine/drft` and
+ * `@driftengine/entities`. What it buys is a simulation that runs with no renderer in its module
+ * graph — in Node, in a worker, or on a server — which is what a server-authoritative consumer
+ * needs and what a peer dependency on core would have priced at core's whole gzipped weight.
+ *
+ * `@driftengine/core` re-exports every name here, so a consumer that reaches for collision through
+ * the core barrel is unaffected by where the files live. **Core depends on this package rather
+ * than the other way round**, which is the opposite direction from every other optional package
+ * and is not a choice: the cameras, the contact probe and the ribbon builder all need the sweep.
+ * **What would make it wrong** is the dynamics landing here becoming reachable from
+ * `createRenderer`, which `scripts/size-gate.test.mjs` measures rather than trusts.
+ */
+export type { Aabb, Axis, Body, BodyPart } from './collide/index.ts';
+export { AXIS_X, AXIS_Y, AXIS_Z, aabbFromCenter, bodyBounds, createBodyBounds, ejectFromSolid, moveAxis, segmentHit, } from './collide/index.ts';
+export { faceCount, faceVertices } from './faces.ts';
+export type { BodyDesc, BodyType } from './bodies.ts';
+export { BODY_DYNAMIC, BODY_KINEMATIC, BODY_SLEEPING, BODY_STATIC, BodySet } from './bodies.ts';
+export { DynamicTree } from './tree.ts';
+export { MAX_BODIES, PairSet, layersInteract, pairA, pairB, pairKey } from './pairs.ts';
+export type { Manifold, ShapePose } from './manifold.ts';
+export { MAX_CONTACTS, collideShapes, createManifold } from './manifold.ts';
+export type { Parallelism, WorldOptions } from './world.ts';
+export { PhysicsWorld } from './world.ts';
+export { ContactConstraints, LINEAR_SLOP, MAX_BIAS_VELOCITY, RESTITUTION_THRESHOLD, applyRestitution, isDynamicBody, prepareContact, solveContacts, warmStart, } from './solver.ts';
+export { IslandSet } from './island.ts';
+export type { FrictionModel } from './solver.ts';
+export type { Executor, IslandOverlap, IslandSolver } from './executor.ts';
+export { DisjointExecutor, SerialExecutor, ShuffledExecutor } from './executor.ts';
+export type { IslandSolveState } from './islandSolve.ts';
+export { solveIslandInto } from './islandSolve.ts';
+export type { LanePlan, StagePlan } from './stage.ts';
+export type { PoolOutcome, PoolRequest, PoolWorker } from './workerPool.ts';
+export type { DofMode, JointDesc, JointType } from './joints.ts';
+export { DOF_COUNT, DOF_FREE, DOF_LIMITED, DOF_LOCKED, JOINT_CONE_TWIST, JOINT_DISTANCE, JOINT_FIXED, JOINT_PRISMATIC, JOINT_REVOLUTE, JOINT_SIX_DOF, JOINT_SPHERICAL, JointSet, resetJointImpulses, solveJoints, } from './joints.ts';
+export type { QueryFilter, RayHit } from './query.ts';
+export { createRayHit, isStaticBody, overlapWorld, raycastWorld, shapecastWorld } from './query.ts';
+export type { EventKind } from './events.ts';
+export { ContactEvents, EVENT_ENTER, EVENT_EXIT, EVENT_STAY } from './events.ts';
+export { BODY_SENSOR } from './bodies.ts';
+export type { ControllerInput, ControllerOptions, ControllerState, GroundProbe, } from './controller.ts';
+export { AIRBORNE, CharacterController, GROUNDED, SLIDING } from './controller.ts';
+export type { PoseTarget, Ragdoll, RagdollOptions } from './ragdoll.ts';
+export { ragdollFromBones } from './ragdoll.ts';
+export type { TyreCurve, VehicleInput, VehicleOptions, WheelOptions } from './vehicle.ts';
+export { Vehicle, defaultTyreCurve, sampleTyreCurve } from './vehicle.ts';
+export type { SweptState, SweptStepOptions, WorldOpinion } from './sweptStep.ts';
+export { SweptStep } from './sweptStep.ts';
+export type { PlanarState } from './groundMotor.ts';
+export { accelerateAlong } from './groundMotor.ts';
+export type { Buoyancy, BuoyancyOptions, BuoyantState } from './buoyancy.ts';
+export { applyBuoyancy, createBuoyancy } from './buoyancy.ts';
+export type { EscapeResult, EscapeVeto, StallEscapeOptions, StallInput } from './stallEscape.ts';
+export { ESCAPE_EASED, ESCAPE_IDLE, ESCAPE_PUSHED, ESCAPE_SEALED, StallEscape, } from './stallEscape.ts';
+export type { ClothOptions } from './cloth.ts';
+export { ClothBody, makeClothGrid } from './cloth.ts';
+export type { Collider, ColliderBytes, ColliderGroup } from './colliderSet.ts';
+export { ColliderSet, boxCollider, colliderFromShape } from './colliderSet.ts';
+export { fingerprintBodies, fingerprintColliders } from './fingerprint.ts';
+export type { MassProperties } from './mass.ts';
+export { combineMassProperties, createMassProperties, shapeMassProperties } from './mass.ts';
+export type { TriangleMesh } from './meshShape.ts';
+export { meshShape } from './meshShape.ts';
+export { heightfieldShape } from './heightfieldShape.ts';
+export type { Heightfield } from './heightfieldShape.ts';
+export type { ConvexShape } from './shape.ts';
+export { boxShape, capsuleShape, cylinderShape, hullShape, shapeBounds, sphereShape, } from './shape.ts';
+export { MAX_BODY_PARTS, MAX_PAIR_MANIFOLDS, collideCompound, partsBoundRadius, } from './compoundContact.ts';
+export type { ConvexPart, Decomposition, DecomposeFill, DecomposeOptions } from './decompose.ts';
+export { DEFAULT_MAX_HULLS, DEFAULT_RESOLUTION, MAX_RESOLUTION, SUPPORT_DIRECTIONS, decomposeConvex, } from './decompose.ts';

package/dist/index.js

@@ -0,0 +1,47 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+export { AXIS_X, AXIS_Y, AXIS_Z, aabbFromCenter, bodyBounds, createBodyBounds, ejectFromSolid, moveAxis, segmentHit, } from './collide/index.js';
+export { faceCount, faceVertices } from './faces.js';
+export { BODY_DYNAMIC, BODY_KINEMATIC, BODY_SLEEPING, BODY_STATIC, BodySet } from './bodies.js';
+export { DynamicTree } from './tree.js';
+export { MAX_BODIES, PairSet, layersInteract, pairA, pairB, pairKey } from './pairs.js';
+export { MAX_CONTACTS, collideShapes, createManifold } from './manifold.js';
+export { PhysicsWorld } from './world.js';
+export { ContactConstraints, LINEAR_SLOP, MAX_BIAS_VELOCITY, RESTITUTION_THRESHOLD, applyRestitution, isDynamicBody, prepareContact, solveContacts, warmStart, } from './solver.js';
+export { IslandSet } from './island.js';
+export { DisjointExecutor, SerialExecutor, ShuffledExecutor } from './executor.js';
+export { solveIslandInto } from './islandSolve.js';
+export { DOF_COUNT, DOF_FREE, DOF_LIMITED, DOF_LOCKED, JOINT_CONE_TWIST, JOINT_DISTANCE, JOINT_FIXED, JOINT_PRISMATIC, JOINT_REVOLUTE, JOINT_SIX_DOF, JOINT_SPHERICAL, JointSet, resetJointImpulses, solveJoints, } from './joints.js';
+export { createRayHit, isStaticBody, overlapWorld, raycastWorld, shapecastWorld } from './query.js';
+export { ContactEvents, EVENT_ENTER, EVENT_EXIT, EVENT_STAY } from './events.js';
+export { BODY_SENSOR } from './bodies.js';
+export { AIRBORNE, CharacterController, GROUNDED, SLIDING } from './controller.js';
+export { ragdollFromBones } from './ragdoll.js';
+export { Vehicle, defaultTyreCurve, sampleTyreCurve } from './vehicle.js';
+export { SweptStep } from './sweptStep.js';
+export { accelerateAlong } from './groundMotor.js';
+export { applyBuoyancy, createBuoyancy } from './buoyancy.js';
+export { ESCAPE_EASED, ESCAPE_IDLE, ESCAPE_PUSHED, ESCAPE_SEALED, StallEscape, } from './stallEscape.js';
+export { ClothBody, makeClothGrid } from './cloth.js';
+export { ColliderSet, boxCollider, colliderFromShape } from './colliderSet.js';
+export { fingerprintBodies, fingerprintColliders } from './fingerprint.js';
+export { combineMassProperties, createMassProperties, shapeMassProperties } from './mass.js';
+export { meshShape } from './meshShape.js';
+/*
+ * A heightfield as a collider: the samples, and every triangle generated from them.
+ *
+ * `Heightfield` is deliberately shaped so that a `Terrain` from `@driftengine/terrain` *is* one —
+ * same names, same meanings — which is how a package that imports no other engine package still
+ * takes one. See `heightfieldShape.ts`.
+ */
+export { heightfieldShape } from './heightfieldShape.js';
+export { boxShape, capsuleShape, cylinderShape, hullShape, shapeBounds, sphereShape, } from './shape.js';
+/*
+ * Convex decomposition: offline, and the only thing in this package that is not meant for a frame.
+ *
+ * Exported from the barrel because it produces `ConvexShape` point sets and belongs beside
+ * `hullShape`. A consumer who never names it never bundles it — the package is `sideEffects: false`
+ * and `physics-only` measures the consequence.
+ */
+/* A body made of several shapes: the half of convex decomposition that lives in the tick. */
+export { MAX_BODY_PARTS, MAX_PAIR_MANIFOLDS, collideCompound, partsBoundRadius, } from './compoundContact.js';
+export { DEFAULT_MAX_HULLS, DEFAULT_RESOLUTION, MAX_RESOLUTION, SUPPORT_DIRECTIONS, decomposeConvex, } from './decompose.js';

package/dist/island.d.ts

@@ -0,0 +1,55 @@
+import type { BodySet } from './bodies.ts';
+import type { JointSet } from './joints.ts';
+import type { ContactConstraints } from './solver.ts';
+/**
+ * Connected components of the contact graph, and the sleeping that rides on them.
+ *
+ * **Only dynamic bodies join islands.** A static floor touches everything standing on it, so
+ * letting it merge would make one island of the whole world and nothing would ever sleep. That is
+ * not an optimisation: it is what an island *means*, and it is why two towers on one floor are two.
+ *
+ * **A body with no contacts is a singleton island**, so every dynamic body belongs to exactly one
+ * and the executor can own the whole substep loop for it rather than integration being a separate
+ * global pass. That is the shape a worker pool needs.
+ *
+ * **Islands are ordered by their lowest body index, and bodies within one by index.** That comes
+ * from the *ascending scan* below, which numbers an island the first time it meets a member — not
+ * from union-find's root choice, which is why swapping the root to the larger index changes no
+ * result and no test catches it. Keeping the smaller one is convention and shortens paths a little;
+ * nothing depends on it. Nothing here iterates a `Map` or a `Set`.
+ */
+export declare class IslandSet {
+    /** How many islands the last build found. */
+    count: number;
+    /** Constraint indices grouped by island. */
+    constraintOrder: Int32Array;
+    /** Offsets into `constraintOrder`, length `count + 1`. */
+    constraintStart: Int32Array;
+    /** Dynamic body indices grouped by island. */
+    bodyOrder: Int32Array;
+    /** Offsets into `bodyOrder`, length `count + 1`. */
+    bodyStart: Int32Array;
+    /** Which island a body is in, or −1 for a body that is not dynamic. */
+    islandOf: Int32Array;
+    private parent;
+    private islandIndex;
+    constructor(capacity?: number);
+    /** Joint indices grouped by island. */
+    jointOrder: Int32Array;
+    /** Offsets into `jointOrder`, length `count + 1`. */
+    jointStart: Int32Array;
+    build(bodies: BodySet, c: ContactConstraints, joints: JointSet): number;
+    private islandOfJoint;
+    private islandOfConstraint;
+    /**
+     * The smaller index wins, which shortens paths slightly and is otherwise arbitrary.
+     *
+     * **It is not what orders islands** — the ascending scan in `build` is. Said here because the
+     * version of this comment that claimed otherwise sent a reader looking for a property the code
+     * does not have and does not need.
+     */
+    private union;
+    private find;
+    private ensureBodies;
+    private ensureConstraints;
+}

package/dist/island.js

@@ -0,0 +1,227 @@
+import { BODY_DYNAMIC } from './bodies.js';
+/**
+ * Connected components of the contact graph, and the sleeping that rides on them.
+ *
+ * **Only dynamic bodies join islands.** A static floor touches everything standing on it, so
+ * letting it merge would make one island of the whole world and nothing would ever sleep. That is
+ * not an optimisation: it is what an island *means*, and it is why two towers on one floor are two.
+ *
+ * **A body with no contacts is a singleton island**, so every dynamic body belongs to exactly one
+ * and the executor can own the whole substep loop for it rather than integration being a separate
+ * global pass. That is the shape a worker pool needs.
+ *
+ * **Islands are ordered by their lowest body index, and bodies within one by index.** That comes
+ * from the *ascending scan* below, which numbers an island the first time it meets a member — not
+ * from union-find's root choice, which is why swapping the root to the larger index changes no
+ * result and no test catches it. Keeping the smaller one is convention and shortens paths a little;
+ * nothing depends on it. Nothing here iterates a `Map` or a `Set`.
+ */
+export class IslandSet {
+    /** How many islands the last build found. */
+    count = 0;
+    /** Constraint indices grouped by island. */
+    constraintOrder;
+    /** Offsets into `constraintOrder`, length `count + 1`. */
+    constraintStart;
+    /** Dynamic body indices grouped by island. */
+    bodyOrder;
+    /** Offsets into `bodyOrder`, length `count + 1`. */
+    bodyStart;
+    /** Which island a body is in, or −1 for a body that is not dynamic. */
+    islandOf;
+    parent;
+    islandIndex;
+    constructor(capacity = 64) {
+        this.constraintOrder = new Int32Array(capacity);
+        this.constraintStart = new Int32Array(capacity + 1);
+        this.bodyOrder = new Int32Array(capacity);
+        this.bodyStart = new Int32Array(capacity + 1);
+        this.islandOf = new Int32Array(capacity);
+        this.parent = new Int32Array(capacity);
+        this.islandIndex = new Int32Array(capacity);
+    }
+    /** Joint indices grouped by island. */
+    jointOrder = new Int32Array(32);
+    /** Offsets into `jointOrder`, length `count + 1`. */
+    jointStart = new Int32Array(33);
+    build(bodies, c, joints) {
+        const n = bodies.count;
+        this.ensureBodies(n);
+        this.ensureConstraints(c.count);
+        for (let i = 0; i < n; i++)
+            this.parent[i] = i;
+        for (let k = 0; k < c.count; k++) {
+            const a = c.bodyA[k] ?? 0;
+            const b = c.bodyB[k] ?? 0;
+            if (bodies.type[a] !== BODY_DYNAMIC || bodies.type[b] !== BODY_DYNAMIC)
+                continue;
+            this.union(a, b);
+        }
+        /*
+         * A joint is an edge in the same graph a contact is. Two bodies held together would otherwise
+         * sleep independently and be woken independently, and a jointed pair whose halves disagree
+         * about being asleep pulls apart.
+         */
+        for (let k = 0; k < joints.count; k++) {
+            if (joints.broken[k])
+                continue;
+            const a = joints.bodyA[k] ?? 0;
+            const b = joints.bodyB[k] ?? 0;
+            if (bodies.type[a] !== BODY_DYNAMIC || bodies.type[b] !== BODY_DYNAMIC)
+                continue;
+            this.union(a, b);
+        }
+        // Roots in ascending order become islands 0, 1, 2 …, so ordering follows body index.
+        let islands = 0;
+        for (let i = 0; i < n; i++) {
+            this.islandOf[i] = -1;
+            this.islandIndex[i] = -1;
+        }
+        for (let i = 0; i < n; i++) {
+            if (bodies.type[i] !== BODY_DYNAMIC)
+                continue;
+            const root = this.find(i);
+            if (this.islandIndex[root] < 0)
+                this.islandIndex[root] = islands++;
+            this.islandOf[i] = this.islandIndex[root] ?? -1;
+        }
+        this.count = islands;
+        if (islands + 1 > this.bodyStart.length) {
+            this.bodyStart = new Int32Array(islands + 1);
+            this.constraintStart = new Int32Array(islands + 1);
+        }
+        // Counting sort of bodies into islands: count, prefix, place.
+        this.bodyStart.fill(0);
+        for (let i = 0; i < n; i++) {
+            const island = this.islandOf[i] ?? -1;
+            if (island >= 0)
+                this.bodyStart[island + 1]++;
+        }
+        for (let i = 0; i < islands; i++) {
+            this.bodyStart[i + 1] = (this.bodyStart[i + 1] ?? 0) + (this.bodyStart[i] ?? 0);
+        }
+        const bodyAt = new Int32Array(islands);
+        for (let i = 0; i < n; i++) {
+            const island = this.islandOf[i] ?? -1;
+            if (island < 0)
+                continue;
+            this.bodyOrder[(this.bodyStart[island] ?? 0) + (bodyAt[island] ?? 0)] = i;
+            bodyAt[island]++;
+        }
+        // And of constraints, by whichever of their bodies is dynamic.
+        this.constraintStart.fill(0);
+        for (let k = 0; k < c.count; k++) {
+            const island = this.islandOfConstraint(bodies, c, k);
+            if (island >= 0)
+                this.constraintStart[island + 1]++;
+        }
+        for (let i = 0; i < islands; i++) {
+            this.constraintStart[i + 1] =
+                (this.constraintStart[i + 1] ?? 0) + (this.constraintStart[i] ?? 0);
+        }
+        const conAt = new Int32Array(islands);
+        for (let k = 0; k < c.count; k++) {
+            const island = this.islandOfConstraint(bodies, c, k);
+            if (island < 0)
+                continue;
+            this.constraintOrder[(this.constraintStart[island] ?? 0) + (conAt[island] ?? 0)] = k;
+            conAt[island]++;
+        }
+        // And of joints, the same way.
+        if (islands + 1 > this.jointStart.length)
+            this.jointStart = new Int32Array(islands + 1);
+        if (joints.count > this.jointOrder.length) {
+            let size = this.jointOrder.length || 1;
+            while (size < joints.count)
+                size *= 2;
+            this.jointOrder = new Int32Array(size);
+        }
+        this.jointStart.fill(0);
+        for (let k = 0; k < joints.count; k++) {
+            const island = this.islandOfJoint(bodies, joints, k);
+            if (island >= 0)
+                this.jointStart[island + 1]++;
+        }
+        for (let i = 0; i < islands; i++) {
+            this.jointStart[i + 1] = (this.jointStart[i + 1] ?? 0) + (this.jointStart[i] ?? 0);
+        }
+        const jointAt = new Int32Array(islands);
+        for (let k = 0; k < joints.count; k++) {
+            const island = this.islandOfJoint(bodies, joints, k);
+            if (island < 0)
+                continue;
+            this.jointOrder[(this.jointStart[island] ?? 0) + (jointAt[island] ?? 0)] = k;
+            jointAt[island]++;
+        }
+        return islands;
+    }
+    islandOfJoint(bodies, joints, k) {
+        if (joints.broken[k])
+            return -1;
+        const a = joints.bodyA[k] ?? 0;
+        const b = joints.bodyB[k] ?? 0;
+        if (bodies.type[a] === BODY_DYNAMIC)
+            return this.islandOf[a] ?? -1;
+        if (bodies.type[b] === BODY_DYNAMIC)
+            return this.islandOf[b] ?? -1;
+        return -1;
+    }
+    islandOfConstraint(bodies, c, k) {
+        const a = c.bodyA[k] ?? 0;
+        const b = c.bodyB[k] ?? 0;
+        if (bodies.type[a] === BODY_DYNAMIC)
+            return this.islandOf[a] ?? -1;
+        if (bodies.type[b] === BODY_DYNAMIC)
+            return this.islandOf[b] ?? -1;
+        return -1;
+    }
+    /**
+     * The smaller index wins, which shortens paths slightly and is otherwise arbitrary.
+     *
+     * **It is not what orders islands** — the ascending scan in `build` is. Said here because the
+     * version of this comment that claimed otherwise sent a reader looking for a property the code
+     * does not have and does not need.
+     */
+    union(a, b) {
+        const ra = this.find(a);
+        const rb = this.find(b);
+        if (ra === rb)
+            return;
+        if (ra < rb)
+            this.parent[rb] = ra;
+        else
+            this.parent[ra] = rb;
+    }
+    find(i) {
+        let root = i;
+        while ((this.parent[root] ?? root) !== root)
+            root = this.parent[root] ?? root;
+        // Path compression, so a long chain is walked once.
+        let at = i;
+        while ((this.parent[at] ?? at) !== at) {
+            const next = this.parent[at] ?? at;
+            this.parent[at] = root;
+            at = next;
+        }
+        return root;
+    }
+    ensureBodies(n) {
+        if (n <= this.parent.length)
+            return;
+        let size = this.parent.length || 1;
+        while (size < n)
+            size *= 2;
+        this.parent = new Int32Array(size);
+        this.islandOf = new Int32Array(size);
+        this.islandIndex = new Int32Array(size);
+        this.bodyOrder = new Int32Array(size);
+    }
+    ensureConstraints(n) {
+        if (n <= this.constraintOrder.length)
+            return;
+        let size = this.constraintOrder.length || 1;
+        while (size < n)
+            size *= 2;
+        this.constraintOrder = new Int32Array(size);
+    }
+}

package/dist/islandSolve.d.ts

@@ -0,0 +1,70 @@
+/**
+ * One island's substep loop, as a function over flat state, so a worker can run the same one.
+ *
+ * **This exists because `PhysicsWorld` cannot cross a realm boundary and an island's solve can.**
+ * The world holds `ConvexShape` objects, a `DynamicTree` and a `Map` of warm impulses, none of which
+ * a `SharedArrayBuffer` can carry. What the solve actually reads is four sets of typed arrays and
+ * eleven numbers, and that much is portable.
+ *
+ * **One implementation, two callers.** `PhysicsWorld.solveIsland` delegates here and so does
+ * `islandWorker.ts`; there is no second copy of the substep order anywhere. The rule against two
+ * implementations of one decision is what makes that non-negotiable, and `splatSortWorker.ts` is the
+ * precedent for satisfying it across a worker boundary — there by stringifying one function, here by
+ * both sides importing one module. **What would make this wrong** is a substep loop appearing inside
+ * the worker.
+ *
+ * The dials are a `Float64Array` and not an object because the worker reads them out of shared
+ * memory, and a shape both sides agree on without a per-tick message is the cheapest way to let a
+ * consumer change gravity between ticks and have the pool see it.
+ */
+import type { BodySet } from './bodies.ts';
+import type { IslandSet } from './island.ts';
+import type { JointSet } from './joints.ts';
+import type { ContactConstraints, FrictionModel } from './solver.ts';
+export declare const DIAL_SUBSTEPS = 0;
+export declare const DIAL_ITERATIONS = 1;
+export declare const DIAL_DT = 2;
+export declare const DIAL_GRAVITY_X = 3;
+export declare const DIAL_GRAVITY_Y = 4;
+export declare const DIAL_GRAVITY_Z = 5;
+export declare const DIAL_LINEAR_DAMPING = 6;
+export declare const DIAL_ANGULAR_DAMPING = 7;
+export declare const DIAL_CONTACT_HERTZ = 8;
+export declare const DIAL_CONTACT_DAMPING = 9;
+export declare const DIAL_JOINT_HERTZ = 10;
+export declare const DIAL_JOINT_DAMPING = 11;
+export declare const DIAL_ALLOW_SLEEP = 12;
+export declare const DIAL_FRICTION_MODEL = 13;
+/** How many slots a dial block has. */
+export declare const DIAL_COUNT = 14;
+/**
+ * `FrictionModel` crosses as a number, and the mapping is written once here.
+ *
+ * A string would cross a `postMessage` perfectly well; it would not survive being read out of a
+ * `Float64Array`, which is where the dials live so that no message is needed at all.
+ */
+export declare const FRICTION_BOX = 0;
+export declare const FRICTION_ELLIPTICAL = 1;
+export declare function frictionDial(model: FrictionModel): number;
+export declare function frictionModelOf(dial: number): FrictionModel;
+/** Ticks below the sleep thresholds before a body is willing to sleep. */
+export declare const SLEEP_TICKS = 60;
+/** Everything one island's solve reaches, and nothing else the world holds. */
+export interface IslandSolveState {
+    bodies: BodySet;
+    constraints: ContactConstraints;
+    joints: JointSet;
+    islands: IslandSet;
+    dials: Float64Array<ArrayBufferLike>;
+}
+/** Whether a body has been still long enough to stop being solved. */
+export declare function bodyAsleep(bodies: BodySet, allowSleep: boolean, i: number): boolean;
+/** Whether every body in an island is asleep, which is what lets the island be skipped whole. */
+export declare function islandAsleep(state: IslandSolveState, island: number): boolean;
+/**
+ * Advance one island through every substep.
+ *
+ * Integration is over this island's bodies only, which is what makes the call independent of every
+ * other island rather than merely ordered against them.
+ */
+export declare function solveIslandInto(state: IslandSolveState, island: number): void;

package/dist/islandSolve.js

@@ -0,0 +1,171 @@
+/**
+ * One island's substep loop, as a function over flat state, so a worker can run the same one.
+ *
+ * **This exists because `PhysicsWorld` cannot cross a realm boundary and an island's solve can.**
+ * The world holds `ConvexShape` objects, a `DynamicTree` and a `Map` of warm impulses, none of which
+ * a `SharedArrayBuffer` can carry. What the solve actually reads is four sets of typed arrays and
+ * eleven numbers, and that much is portable.
+ *
+ * **One implementation, two callers.** `PhysicsWorld.solveIsland` delegates here and so does
+ * `islandWorker.ts`; there is no second copy of the substep order anywhere. The rule against two
+ * implementations of one decision is what makes that non-negotiable, and `splatSortWorker.ts` is the
+ * precedent for satisfying it across a worker boundary — there by stringifying one function, here by
+ * both sides importing one module. **What would make this wrong** is a substep loop appearing inside
+ * the worker.
+ *
+ * The dials are a `Float64Array` and not an object because the worker reads them out of shared
+ * memory, and a shape both sides agree on without a per-tick message is the cheapest way to let a
+ * consumer change gravity between ticks and have the pool see it.
+ */
+import { BODY_DYNAMIC, BODY_STATIC } from './bodies.js';
+import { solveJoints } from './joints.js';
+import { applyRestitution, solveContacts, warmStart } from './solver.js';
+/* Slots in the dial block. Named because a worker reads them from shared memory by index. */
+export const DIAL_SUBSTEPS = 0;
+export const DIAL_ITERATIONS = 1;
+export const DIAL_DT = 2;
+export const DIAL_GRAVITY_X = 3;
+export const DIAL_GRAVITY_Y = 4;
+export const DIAL_GRAVITY_Z = 5;
+export const DIAL_LINEAR_DAMPING = 6;
+export const DIAL_ANGULAR_DAMPING = 7;
+export const DIAL_CONTACT_HERTZ = 8;
+export const DIAL_CONTACT_DAMPING = 9;
+export const DIAL_JOINT_HERTZ = 10;
+export const DIAL_JOINT_DAMPING = 11;
+export const DIAL_ALLOW_SLEEP = 12;
+export const DIAL_FRICTION_MODEL = 13;
+/** How many slots a dial block has. */
+export const DIAL_COUNT = 14;
+/**
+ * `FrictionModel` crosses as a number, and the mapping is written once here.
+ *
+ * A string would cross a `postMessage` perfectly well; it would not survive being read out of a
+ * `Float64Array`, which is where the dials live so that no message is needed at all.
+ */
+export const FRICTION_BOX = 0;
+export const FRICTION_ELLIPTICAL = 1;
+export function frictionDial(model) {
+    return model === 'elliptical' ? FRICTION_ELLIPTICAL : FRICTION_BOX;
+}
+export function frictionModelOf(dial) {
+    return dial === FRICTION_ELLIPTICAL ? 'elliptical' : 'box';
+}
+/** Ticks below the sleep thresholds before a body is willing to sleep. */
+export const SLEEP_TICKS = 60;
+/** Whether a body has been still long enough to stop being solved. */
+export function bodyAsleep(bodies, allowSleep, i) {
+    return allowSleep && (bodies.sleepTicks[i] ?? 0) >= SLEEP_TICKS;
+}
+/** Whether every body in an island is asleep, which is what lets the island be skipped whole. */
+export function islandAsleep(state, island) {
+    const allowSleep = (state.dials[DIAL_ALLOW_SLEEP] ?? 0) !== 0;
+    const from = state.islands.bodyStart[island] ?? 0;
+    const to = state.islands.bodyStart[island + 1] ?? from;
+    for (let at = from; at < to; at++) {
+        if (!bodyAsleep(state.bodies, allowSleep, state.islands.bodyOrder[at] ?? 0))
+            return false;
+    }
+    return to > from;
+}
+function integrateVelocities(state, h, from, to) {
+    const bodies = state.bodies;
+    const d = state.dials;
+    const allowSleep = (d[DIAL_ALLOW_SLEEP] ?? 0) !== 0;
+    const gx = d[DIAL_GRAVITY_X] ?? 0;
+    const gy = d[DIAL_GRAVITY_Y] ?? 0;
+    const gz = d[DIAL_GRAVITY_Z] ?? 0;
+    const ld = 1 / (1 + h * (d[DIAL_LINEAR_DAMPING] ?? 0));
+    const ad = 1 / (1 + h * (d[DIAL_ANGULAR_DAMPING] ?? 0));
+    for (let at = from; at < to; at++) {
+        const i = state.islands.bodyOrder[at] ?? 0;
+        if (bodies.type[i] !== BODY_DYNAMIC || bodyAsleep(bodies, allowSleep, i))
+            continue;
+        bodies.velX[i] = ((bodies.velX[i] ?? 0) + h * gx) * ld;
+        bodies.velY[i] = ((bodies.velY[i] ?? 0) + h * gy) * ld;
+        bodies.velZ[i] = ((bodies.velZ[i] ?? 0) + h * gz) * ld;
+        bodies.angX[i] = (bodies.angX[i] ?? 0) * ad;
+        bodies.angY[i] = (bodies.angY[i] ?? 0) * ad;
+        bodies.angZ[i] = (bodies.angZ[i] ?? 0) * ad;
+    }
+}
+function integratePositions(state, h, from, to) {
+    const bodies = state.bodies;
+    const allowSleep = (state.dials[DIAL_ALLOW_SLEEP] ?? 0) !== 0;
+    for (let at = from; at < to; at++) {
+        const i = state.islands.bodyOrder[at] ?? 0;
+        if (bodies.type[i] === BODY_STATIC || bodyAsleep(bodies, allowSleep, i))
+            continue;
+        bodies.posX[i] = (bodies.posX[i] ?? 0) + h * (bodies.velX[i] ?? 0);
+        bodies.posY[i] = (bodies.posY[i] ?? 0) + h * (bodies.velY[i] ?? 0);
+        bodies.posZ[i] = (bodies.posZ[i] ?? 0) + h * (bodies.velZ[i] ?? 0);
+        // First-order exponential map, then renormalise. No sin, no cos.
+        const qx = bodies.rotX[i] ?? 0;
+        const qy = bodies.rotY[i] ?? 0;
+        const qz = bodies.rotZ[i] ?? 0;
+        const qw = bodies.rotW[i] ?? 1;
+        const wx = bodies.angX[i] ?? 0;
+        const wy = bodies.angY[i] ?? 0;
+        const wz = bodies.angZ[i] ?? 0;
+        const half = 0.5 * h;
+        let nx = qx + half * (wx * qw + wy * qz - wz * qy);
+        let ny = qy + half * (wy * qw + wz * qx - wx * qz);
+        let nz = qz + half * (wz * qw + wx * qy - wy * qx);
+        let nw = qw - half * (wx * qx + wy * qy + wz * qz);
+        const len = Math.sqrt(nx * nx + ny * ny + nz * nz + nw * nw) || 1;
+        nx /= len;
+        ny /= len;
+        nz /= len;
+        nw /= len;
+        bodies.rotX[i] = nx;
+        bodies.rotY[i] = ny;
+        bodies.rotZ[i] = nz;
+        bodies.rotW[i] = nw;
+    }
+}
+/**
+ * Advance one island through every substep.
+ *
+ * Integration is over this island's bodies only, which is what makes the call independent of every
+ * other island rather than merely ordered against them.
+ */
+export function solveIslandInto(state, island) {
+    if (islandAsleep(state, island))
+        return;
+    const d = state.dials;
+    const substeps = d[DIAL_SUBSTEPS] ?? 1;
+    const iterations = d[DIAL_ITERATIONS] ?? 1;
+    const dt = d[DIAL_DT] ?? 0;
+    const contactHertz = d[DIAL_CONTACT_HERTZ] ?? 0;
+    const contactDamping = d[DIAL_CONTACT_DAMPING] ?? 0;
+    const jointHertz = d[DIAL_JOINT_HERTZ] ?? 0;
+    const jointDamping = d[DIAL_JOINT_DAMPING] ?? 0;
+    const friction = frictionModelOf(d[DIAL_FRICTION_MODEL] ?? 0);
+    const h = dt / substeps;
+    const bodies = state.bodies;
+    const joints = state.joints;
+    const c = state.constraints;
+    const order = state.islands.constraintOrder;
+    const from = state.islands.constraintStart[island] ?? 0;
+    const to = state.islands.constraintStart[island + 1] ?? from;
+    const bodyFrom = state.islands.bodyStart[island] ?? 0;
+    const bodyTo = state.islands.bodyStart[island + 1] ?? bodyFrom;
+    const jointOrder = state.islands.jointOrder;
+    const jointFrom = state.islands.jointStart[island] ?? 0;
+    const jointTo = state.islands.jointStart[island + 1] ?? jointFrom;
+    for (let s = 0; s < substeps; s++) {
+        integrateVelocities(state, h, bodyFrom, bodyTo);
+        warmStart(bodies, c, order, from, to);
+        for (let it = 0; it < iterations; it++) {
+            // Joints before contacts: a joint is structural and a contact is transient, so letting a
+            // contact win produces a limb that pulls out of its socket when something lands on it.
+            solveJoints(bodies, joints, jointOrder, jointFrom, jointTo, h, dt, true, jointHertz, jointDamping);
+            solveContacts(bodies, c, order, from, to, h, true, contactHertz, contactDamping, friction);
+        }
+        integratePositions(state, h, bodyFrom, bodyTo);
+        // The relax pass, with the bias off, giving back the energy the bias added.
+        solveJoints(bodies, joints, jointOrder, jointFrom, jointTo, h, dt, false, jointHertz, jointDamping);
+        solveContacts(bodies, c, order, from, to, h, false, contactHertz, contactDamping, friction);
+    }
+    applyRestitution(bodies, c, order, from, to);
+}

package/dist/islandWorker.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The worker end of the island pool.
+ *
+ * **It contains no physics.** It adopts views over the staging buffer, claims islands from a shared
+ * cursor, and calls `solveIslandInto` — the same function `PhysicsWorld.solveIsland` calls. A
+ * substep loop appearing in this file would be the defect the whole arrangement is shaped to
+ * prevent, because a second copy of the solve order drifts from the first the first time either is
+ * touched and nothing fails until a consumer's replay does.
+ *
+ * **It parks rather than polls.** `Atomics.wait` is permitted off a browser's main thread, so an
+ * idle worker costs nothing between ticks and wakes on an epoch bump with no message sent.
+ *
+ * **Two hosts, one file.** A browser module worker delivers messages through `self.onmessage`;
+ * `node:worker_threads` delivers them through `parentPort`. The difference is eight lines at the
+ * bottom, and paying them is what lets the gate spawn this exact entry point in Node instead of a
+ * stand-in that would prove nothing about threads.
+ */
+export {};