@driftengine/physics 3.61.0

package/dist/islandWorker.js

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { solveIslandInto } from './islandSolve.js';
+import { SolveStage } from './stage.js';
+import { CTL_ACK, CTL_CURSOR, CTL_DONE, CTL_EPOCH, CTL_ISLANDS, CTL_RELOAD, CTL_SOLVED, CTL_STOP, } from './workerPool.js';
+let control = null;
+let state = null;
+let index = 0;
+/**
+ * Take the shared buffers, say so, and park.
+ *
+ * The acknowledgement is an atomic and not a reply message because the caller is waiting on it
+ * synchronously — it has just told every worker to come out of `Atomics.wait` and cannot process a
+ * message of its own until the tick is over.
+ */
+function accept(message) {
+    if (message?.kind !== 'stage')
+        return;
+    control = new Int32Array(message.control);
+    index = message.index;
+    state = SolveStage.adopt(message.buffer, message.plan).state;
+    /*
+     * **The epoch is read before the acknowledgement, and that order is the whole correctness of a
+     * re-plan.** The caller is spinning on `CTL_ACK` and bumps the epoch the moment it completes. Read
+     * after acknowledging and this worker can capture the epoch it was meant to wake for, then wait
+     * for the one after it — sleeping through the tick, so the join never completes and the pool
+     * declares itself dead. Reading first bounds `seen` below the next bump by construction.
+     */
+    const seen = Atomics.load(control, CTL_EPOCH);
+    Atomics.add(control, CTL_ACK, 1);
+    Atomics.notify(control, CTL_ACK);
+    park(seen);
+}
+/** Claim islands until there are none, then report what was solved. */
+function work(ctl, solve) {
+    const count = Atomics.load(ctl, CTL_ISLANDS);
+    let solved = 0;
+    for (;;) {
+        const island = Atomics.add(ctl, CTL_CURSOR, 1);
+        if (island >= count)
+            break;
+        solveIslandInto(solve, island);
+        solved += 1;
+    }
+    Atomics.add(ctl, CTL_SOLVED + index, solved);
+    Atomics.add(ctl, CTL_DONE, 1);
+    Atomics.notify(ctl, CTL_DONE);
+}
+/**
+ * Sleep until the epoch moves, then either solve, stop, or go back to the event loop.
+ *
+ * Returning on `CTL_RELOAD` is the whole reason a re-plan works: a parked worker cannot receive a
+ * `postMessage`, so the caller lets it out first and the pending message is delivered the moment
+ * this function returns.
+ */
+function park(from) {
+    const ctl = control;
+    if (ctl === null)
+        return;
+    let seen = from;
+    for (;;) {
+        Atomics.wait(ctl, CTL_EPOCH, seen);
+        const epoch = Atomics.load(ctl, CTL_EPOCH);
+        if (epoch === seen)
+            continue;
+        seen = epoch;
+        if (Atomics.load(ctl, CTL_STOP) === 1)
+            return;
+        if (Atomics.load(ctl, CTL_RELOAD) === 1)
+            return;
+        if (state !== null)
+            work(ctl, state);
+    }
+}
+const scope = globalThis;
+if (typeof scope.postMessage === 'function') {
+    scope.onmessage = (event) => accept(event.data);
+}
+else {
+    /*
+     * **No top-level await here, and that is a consumer's build rather than a preference.**
+     *
+     * `workerPool.ts` builds this with `new Worker(new URL('./islandWorker.ts', import.meta.url))`,
+     * which every bundler detects statically and compiles as a worker whether or not the consumer
+     * ever starts a pool. Vite's default worker format is `iife`, and an IIFE cannot carry a
+     * top-level await: a consumer's production build answered `Module format "iife" does not support
+     * top-level await` on 2026-09-05 and could not build at all. A dev server serves module workers
+     * and never sees it, which is why `check:pool` passed over the same code.
+     *
+     * So the Node branch attaches its listener in a microtask instead. Nothing is missed: a Node
+     * `MessagePort` queues messages until `on('message')` attaches, so a `postMessage` issued before
+     * this resolves is delivered when it does.
+     *
+     * A variable specifier so a browser bundler leaves the import alone; this branch never runs in
+     * one.
+     */
+    const nodeWorkers = 'node:worker_threads';
+    void import(__rewriteRelativeImportExtension(/* @vite-ignore */ nodeWorkers)).then((mod) => {
+        const { parentPort } = mod;
+        parentPort?.on('message', accept);
+    });
+}

package/dist/joints.d.ts

@@ -0,0 +1,180 @@
+import type { BodySet } from './bodies.ts';
+/**
+ * Joints: seven types, each solved with its own rows unrolled.
+ *
+ * **This file refused a configurable 6-DOF joint until 2026-08-27, and the refusal was narrower
+ * than it read.** What it argued against was replacing the six unrolled types with *one* joint
+ * whose constraint set is decided at runtime — a branch per row in the hottest loop in the engine,
+ * and a megamorphic call site at the top of it. That argument still stands and nothing here has
+ * changed: the six keep their own arms, their own rows and their own numbers, and none of them
+ * gained a branch.
+ *
+ * What arrived instead is a **seventh type**, which is exactly what that refusal named as its own
+ * cost — "the package has to grow a type" — so the branch a six-DOF joint pays for is paid by
+ * six-DOF joints and by nothing else. The stated reversal condition was three consumers wanting
+ * three different exotic joints; growing three more unrolled types is the outcome this answers
+ * more cheaply than it answers the question of whether three have asked.
+ *
+ * **`JOINT_SIX_DOF` solves six independent scalar rows, not two coupled 3x3 blocks**, because a
+ * coupled solve has no meaning when a caller has made only some of the rows exist. *Cost:* an
+ * all-locked six-DOF joint is measurably softer than `JOINT_FIXED` at the same substep count, so
+ * reach for `JOINT_FIXED` when all six are locked. *What would make this wrong:* a caller wanting
+ * an all-locked six-DOF joint to be as stiff as a fixed one, and the honest answer there is to use
+ * the fixed one.
+ *
+ * **No angle appears anywhere.** A swing limit compares a dot product against a stored cosine; a
+ * twist limit compares a quaternion component against the half-angle's sine. `Math.acos` and
+ * `Math.atan2` are both on the banned list, and writing the limits this way from the start is
+ * cheaper than repairing them — the comparison is what the solver wanted anyway, since it clamps
+ * rather than measures.
+ *
+ * **A point-to-point constraint solves its full 3×3 effective mass** rather than three sequential
+ * scalars. The matrix inverts in closed form, so one exact solve replaces three approximate ones
+ * that would each disturb the others. *What it costs* is an inversion per joint per iteration.
+ *
+ * Joints are solved **before** contacts in each iteration, because a joint is a hard structural
+ * relationship and a contact is a transient one: letting contacts win produces a limb that pulls
+ * out of its socket when something lands on it.
+ */
+export declare const JOINT_DISTANCE = 0;
+export declare const JOINT_SPHERICAL = 1;
+export declare const JOINT_REVOLUTE = 2;
+export declare const JOINT_PRISMATIC = 3;
+export declare const JOINT_FIXED = 4;
+export declare const JOINT_CONE_TWIST = 5;
+export declare const JOINT_SIX_DOF = 6;
+export type JointType = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * What one degree of freedom does, for `JOINT_SIX_DOF`.
+ *
+ * **Locked is zero so that a zero-filled array is a rigid joint.** A joint somebody forgot to
+ * describe holds its bodies together rather than letting them fly apart, which is the safe
+ * direction for a default nobody chose.
+ *
+ * **Explicit rather than inferred from the bounds.** The widespread convention is that
+ * `lower > upper` means free and `lower === upper` means locked, which needs no extra field and
+ * turns a caller who swapped their two numbers into a joint that silently does nothing. A mode is
+ * one byte and it cannot be mistyped into the wrong meaning.
+ */
+export declare const DOF_LOCKED = 0;
+export declare const DOF_LIMITED = 1;
+export declare const DOF_FREE = 2;
+export type DofMode = 0 | 1 | 2;
+/** Six degrees: linear x, y, z, then angular x, y, z — all in body A's local frame. */
+export declare const DOF_COUNT = 6;
+export interface JointDesc {
+    readonly type: JointType;
+    readonly bodyA: number;
+    readonly bodyB: number;
+    /** Anchor in each body's local frame. */
+    readonly anchorAX?: number;
+    readonly anchorAY?: number;
+    readonly anchorAZ?: number;
+    readonly anchorBX?: number;
+    readonly anchorBY?: number;
+    readonly anchorBZ?: number;
+    /** The free axis, in A's local frame: a hinge turns about it, a slider travels along it. */
+    readonly axisX?: number;
+    readonly axisY?: number;
+    readonly axisZ?: number;
+    /** Distance joints: the length held. Others: unused. */
+    readonly length?: number;
+    /** Limits, as a cosine for a cone and as metres or a sine of a half-angle otherwise. */
+    readonly lower?: number;
+    readonly upper?: number;
+    /** A cone half-angle's cosine, and a twist half-angle's sine. Cone-twist only. */
+    readonly swingCos?: number;
+    readonly twistSin?: number;
+    readonly motorSpeed?: number;
+    readonly motorMaxForce?: number;
+    /** Accumulated impulse above which the joint gives way. `Infinity` never breaks. */
+    readonly breakImpulse?: number;
+    /**
+     * Six-DOF only: what each degree of freedom does.
+     *
+     * **The order is linear x, y, z then angular x, y, z, all in body A's local frame** — not in a
+     * frame of the joint's own. *Cost:* a caller wanting axes that are not A's own has to orient A,
+     * or place the anchors so that A's frame is the one it means. *What would reverse it:* a
+     * consumer whose parent body cannot be oriented, and the answer then is four more floats per
+     * joint holding a frame quaternion.
+     *
+     * Shorter than six, or absent, and the rest are locked.
+     */
+    readonly dof?: readonly DofMode[];
+    /**
+     * Lower bounds, one per degree, read only where the mode is `DOF_LIMITED`.
+     *
+     * **Linear bounds are metres of offset from the anchor; angular bounds are sines of half
+     * angles.** The second is this package's own convention rather than a shortcut — a swing limit
+     * compares a dot product against a stored cosine and a twist limit a quaternion component against
+     * a half-angle's sine, because `Math.acos` and `Math.atan2` are both on the banned list and the
+     * comparison is what the solver wanted anyway. A quarter turn is `Math.sin(Math.PI / 4)`.
+     */
+    readonly dofLower?: readonly number[];
+    /** Upper bounds, in the same units and the same order. */
+    readonly dofUpper?: readonly number[];
+}
+export declare class JointSet {
+    count: number;
+    type: Uint8Array;
+    bodyA: Int32Array;
+    bodyB: Int32Array;
+    localA: Float32Array;
+    localB: Float32Array;
+    axis: Float32Array;
+    /** The relative rotation held at rest, captured when the joint is made. */
+    restRel: Float32Array;
+    length: Float32Array;
+    lower: Float32Array;
+    upper: Float32Array;
+    swingCos: Float32Array;
+    twistSin: Float32Array;
+    motorSpeed: Float32Array;
+    motorMaxForce: Float32Array;
+    breakImpulse: Float32Array;
+    broken: Uint8Array;
+    /** Six accumulated impulses per joint: three linear, three angular or scalar rows. */
+    impulse: Float32Array;
+    motorImpulse: Float32Array;
+    /** Six-DOF only: a mode per degree, and the bounds the limited ones are held between. */
+    dofMode: Uint8Array;
+    dofLower: Float32Array;
+    dofUpper: Float32Array;
+    private cap;
+    constructor(capacity?: number);
+    add(bodies: BodySet, d: JointDesc): number;
+    private grow;
+}
+/**
+ * Clear every joint's accumulated impulse, once per tick, before the substeps.
+ *
+ * **The soft-constraint relaxation term makes a joint a spring whose sag is proportional to what it
+ * is carrying**, through `−impulseScale · accumulated`. Contacts reset that accumulator every tick
+ * when `prepareContact` reloads them from the warm-start store; joints had nothing doing the same,
+ * so it grew without bound — measured, a distance joint's went from −17.7 on the first tick to
+ * −5,278 by the three hundredth, and the body it held sagged 83 millimetres and was still sinking.
+ *
+ * **What this gives up** is warm starting for joints: a heavily loaded one starts each tick from
+ * zero and needs the substeps to find its impulse again. **What would make it wrong** is a rig
+ * whose joints visibly soften under load at four substeps, and the answer then is to carry the
+ * impulse as a warm start and reset the accumulator, rather than to leave it running.
+ */
+export declare function resetJointImpulses(joints: JointSet): void;
+/**
+ * Solve every joint in a range, one iteration.
+ *
+ * `useBias` is false on the relax pass, exactly as it is for contacts, so the positional push a
+ * joint applies is taken back rather than left as energy.
+ */
+export declare function solveJoints(bodies: BodySet, joints: JointSet, order: Int32Array, from: number, to: number, h: number, 
+/**
+ * The whole tick, which is what a motor's force budget is measured over.
+ *
+ * `maxForce` means a force, and a force acting for a tick is `maxForce · dt` of impulse. Bounding
+ * the accumulator by `maxForce · h` instead gives the entire tick one substep's worth, so raising
+ * the substep count silently weakens every motor — measured, a hinge told to reach 4 rad/s got to
+ * 0.13 in a tick where it should have reached 0.5.
+ */
+dt: number, useBias: boolean, hertz: number, damping: number): void;
+/** `conj(qA) · qB`, into `out`, as xyzw. */
+export declare function relativeRotation(bodies: BodySet, a: number, b: number, out: Float32Array | Float64Array, at: number): void;