@driftengine/physics 3.61.0

package/dist/vehicle.js

@@ -0,0 +1,343 @@
+import { createRayHit } from './query.js';
+/** A curve that rises to a peak and falls away, which is what a tyre does. */
+export function defaultTyreCurve(peak = 1) {
+    return {
+        slip: new Float32Array([0, 0.1, 0.2, 0.4, 0.8, 1.5]),
+        force: new Float32Array([0, peak * 0.75, peak, peak * 0.9, peak * 0.75, peak * 0.7]),
+    };
+}
+export class Vehicle {
+    chassis;
+    wheelCount;
+    /** Whether each wheel found ground on the last update. */
+    grounded;
+    /** How far each wheel's suspension is compressed, in metres. */
+    compression;
+    /** Where each wheel's contact is, xyz-packed. Meaningful where `grounded`. */
+    contact;
+    local;
+    radius;
+    travel;
+    stiffness;
+    damping;
+    steers;
+    driven;
+    maxSteerTangent;
+    engineForce;
+    brakeForce;
+    longitudinal;
+    lateral;
+    /**
+     * The suspension ray must ignore the car it holds up.
+     *
+     * A wheel anchor sits *inside* the chassis by construction — that is what a suspension mount is —
+     * and a ray starting inside a body reports that body at fraction zero, which is the right answer
+     * to the question a line-of-sight test asks and the wrong one here. Left unfiltered, every wheel
+     * found the chassis at zero distance, read the suspension as fully compressed, and pushed the car
+     * against itself: it sank onto its own chassis and sat there.
+     */
+    filter;
+    hit = createRayHit();
+    probe;
+    /** Scratch for the probe, claimed once: every wheel asks it every tick. */
+    probed = { y: 0, normalX: 0, normalY: 1, normalZ: 0 };
+    /**
+     * Every wheel's impulse, gathered before any is applied: `rx ry rz px py pz` per wheel.
+     *
+     * **Applying them one at a time makes the car curve.** Each wheel then sees a velocity the
+     * previous wheel has already changed, so the left front's lateral impulse biases what the right
+     * front computes, and the asymmetry accumulates into a yaw rather than cancelling. Measured on a
+     * symmetric car under straight throttle: 0.011 metres of drift after 2 metres, 0.64 after 39, and
+     * **5.49 after 155** — a curve, not a wobble. Forces at an instant are simultaneous, and gathering
+     * them is both the correct physics and the cheaper fix.
+     */
+    pending;
+    constructor(chassis, options) {
+        this.chassis = chassis;
+        this.wheelCount = options.wheels.length;
+        const n = this.wheelCount;
+        this.local = new Float32Array(n * 3);
+        this.radius = new Float32Array(n);
+        this.travel = new Float32Array(n);
+        this.stiffness = new Float32Array(n);
+        this.damping = new Float32Array(n);
+        this.steers = new Uint8Array(n);
+        this.driven = new Uint8Array(n);
+        this.grounded = new Uint8Array(n);
+        this.compression = new Float32Array(n);
+        this.contact = new Float32Array(n * 3);
+        options.wheels.forEach((w, i) => {
+            this.local[i * 3] = w.x;
+            this.local[i * 3 + 1] = w.y;
+            this.local[i * 3 + 2] = w.z;
+            this.radius[i] = w.radius ?? 0.35;
+            this.travel[i] = w.suspensionTravel ?? 0.3;
+            this.stiffness[i] = w.stiffness ?? 40000;
+            this.damping[i] = w.damping ?? 4000;
+            this.steers[i] = w.steers ? 1 : 0;
+            this.driven[i] = w.driven ? 1 : 0;
+        });
+        this.maxSteerTangent = options.maxSteerTangent ?? 0.6;
+        this.engineForce = options.engineForce ?? 6000;
+        this.brakeForce = options.brakeForce ?? 9000;
+        this.longitudinal = options.longitudinal ?? defaultTyreCurve(1.2);
+        this.lateral = options.lateral ?? defaultTyreCurve(1.4);
+        this.filter = { ...options.filter, ignore: chassis };
+        this.probe = options.ground ?? null;
+        this.pending = new Float64Array(n * 6);
+    }
+    /** Advance the vehicle one fixed tick. Call before `world.step`. */
+    update(world, dt, input) {
+        const body = this.chassis;
+        const bodies = world.bodies;
+        this.pending.fill(0);
+        let drivenCount = 0;
+        for (let i = 0; i < this.wheelCount; i++)
+            if (this.driven[i])
+                drivenCount++;
+        const perWheelDrive = drivenCount > 0 ? (input.throttle * this.engineForce) / drivenCount : 0;
+        for (let i = 0; i < this.wheelCount; i++) {
+            rotate(bodies, body, this.local, i * 3, ANCHOR);
+            const ax = (bodies.posX[body] ?? 0) + ANCHOR[0];
+            const ay = (bodies.posY[body] ?? 0) + ANCHOR[1];
+            const az = (bodies.posZ[body] ?? 0) + ANCHOR[2];
+            // The suspension looks along the chassis's own down, not world down.
+            axis(bodies, body, 0, -1, 0, DOWN);
+            const reach = (this.travel[i] ?? 0) + (this.radius[i] ?? 0);
+            if (!world.raycast(ax, ay, az, DOWN[0], DOWN[1], DOWN[2], reach, this.hit, this.filter) &&
+                !this.probeUnder(ax, ay, az, reach)) {
+                this.grounded[i] = 0;
+                this.compression[i] = 0;
+                continue;
+            }
+            this.grounded[i] = 1;
+            this.contact[i * 3] = this.hit.x;
+            this.contact[i * 3 + 1] = this.hit.y;
+            this.contact[i * 3 + 2] = this.hit.z;
+            const distance = this.hit.fraction * reach;
+            /*
+             * Compression is capped at the travel. Past that the wheel is bottomed out and the *chassis*
+             * takes the load through its own collider, which is what a bump stop is.
+             *
+             * **No test here reaches it, and that is worth saying rather than leaving somebody to look.**
+             * With wheels mounted inside the chassis — the ordinary arrangement — the chassis collider
+             * meets the ground before the suspension can bottom out, so removing this line changes a drop
+             * from six metres by a centimetre and nothing else. It stays because a vehicle with outboard
+             * mounts *can* reach it, and an uncapped spring then answers a hard landing with several
+             * times the car's weight.
+             */
+            let compression = reach - distance;
+            const bumpStop = this.travel[i] ?? 0;
+            if (compression > bumpStop)
+                compression = bumpStop;
+            this.compression[i] = compression;
+            // The anchor's velocity, which is what the damper answers to.
+            pointVelocity(bodies, body, ANCHOR, VEL);
+            const alongDown = VEL[0] * DOWN[0] + VEL[1] * DOWN[1] + VEL[2] * DOWN[2];
+            /*
+             * **The damper adds to the load while the spring is compressing.** `alongDown` is positive
+             * when the anchor is moving toward the ground, which is exactly when compression is
+             * increasing, so a damper opposing that motion pushes *up*. Subtracting it instead — which is
+             * what `k·x − c·v` reads like if `v` is taken as the wrong sign — leaves the spring undamped
+             * and clamps the load to zero on the way down: the car fell, bounced on a pure spring, and
+             * launched itself upside down.
+             */
+            let load = (this.stiffness[i] ?? 0) * compression + (this.damping[i] ?? 0) * alongDown;
+            if (load < 0)
+                load = 0;
+            // Along the surface normal rather than along the ray, so a slope pushes sideways too.
+            this.gather(i, ANCHOR, this.hit.nx * load * dt, this.hit.ny * load * dt, this.hit.nz * load * dt);
+            // The wheel's own frame: forward turned by steering, and lateral across it.
+            const steer = this.steers[i] ? input.steer * this.maxSteerTangent : 0;
+            axis(bodies, body, steer, 0, 1, FORWARD);
+            normalise(FORWARD);
+            axis(bodies, body, 1, 0, -steer, SIDE);
+            normalise(SIDE);
+            // Flattened onto the surface, so grip acts along the ground rather than into it.
+            project(FORWARD, this.hit.nx, this.hit.ny, this.hit.nz);
+            project(SIDE, this.hit.nx, this.hit.ny, this.hit.nz);
+            normalise(FORWARD);
+            normalise(SIDE);
+            pointVelocity(bodies, body, ANCHOR, VEL);
+            const vForward = VEL[0] * FORWARD[0] + VEL[1] * FORWARD[1] + VEL[2] * FORWARD[2];
+            const vSide = VEL[0] * SIDE[0] + VEL[1] * SIDE[1] + VEL[2] * SIDE[2];
+            const speed = Math.sqrt(vForward * vForward + vSide * vSide);
+            /*
+             * Slip is the sideways or braking velocity against the speed the wheel is going, which is what
+             * a tyre curve is indexed by. At a standstill the ratio is undefined, so the slip is taken as
+             * the velocity itself — a stationary car with a sideways nudge should still resist it.
+             */
+            const denom = speed > 1 ? speed : 1;
+            const lateralGrip = sampleTyreCurve(this.lateral, Math.abs(vSide) / denom) * load;
+            const sideImpulse = clampMagnitude(-vSide * massAt(bodies, body), lateralGrip * dt);
+            this.gather(i, ANCHOR, SIDE[0] * sideImpulse, SIDE[1] * sideImpulse, SIDE[2] * sideImpulse);
+            let forwardForce = this.driven[i] ? perWheelDrive : 0;
+            if (input.brake > 0) {
+                const brake = input.brake * this.brakeForce;
+                forwardForce += vForward > 0 ? -brake : brake;
+            }
+            const traction = sampleTyreCurve(this.longitudinal, Math.abs(vForward) / denom) * load;
+            const limit = traction > 0 ? traction : load;
+            const drive = clampMagnitude(forwardForce, limit);
+            this.gather(i, ANCHOR, FORWARD[0] * drive * dt, FORWARD[1] * drive * dt, FORWARD[2] * drive * dt);
+        }
+        // Now apply, all from the state every wheel was measured against.
+        for (let i = 0; i < this.wheelCount; i++) {
+            const at = i * 6;
+            ANCHOR[0] = this.pending[at];
+            ANCHOR[1] = this.pending[at + 1];
+            ANCHOR[2] = this.pending[at + 2];
+            applyImpulse(bodies, body, ANCHOR, this.pending[at + 3], this.pending[at + 4], this.pending[at + 5]);
+        }
+        world.wakeIsland(body);
+    }
+    /** Add an impulse at a wheel's anchor to what will be applied at the end of the pass. */
+    /**
+     * Rest a wheel on the analytic surface, filling `hit` as a ray against a body would have.
+     *
+     * Everything downstream — the spring, the damper, the tyre frame flattened onto the ground —
+     * reads `hit`, so filling it is the whole of the wiring and no grip code learns that a surface
+     * exists.
+     *
+     * **The column is the anchor's own and the drop is measured along the chassis's down**, which is
+     * exact while the chassis is upright and off by its tilt when it is not: the true contact sits a
+     * little to the side of the column that was sampled, and on a slope that column is a little
+     * higher or lower than the contact. At the lean angles a car spends its life at the error is
+     * millimetres, and the alternative is solving a ray against an arbitrary height function, which
+     * is an iteration this package does not allow itself. A vehicle on its roof finds no ground here
+     * at all, because there is no downward intersection to find, which is the honest answer.
+     */
+    probeUnder(ax, ay, az, reach) {
+        if (this.probe === null || DOWN[1] >= 0)
+            return false;
+        if (!this.probe.sample(ax, az, this.probed, ay))
+            return false;
+        const distance = (this.probed.y - ay) / DOWN[1];
+        if (!(distance >= 0) || distance > reach)
+            return false;
+        this.hit.body = -1;
+        this.hit.fraction = distance / reach;
+        this.hit.x = ax + DOWN[0] * distance;
+        this.hit.y = ay + DOWN[1] * distance;
+        this.hit.z = az + DOWN[2] * distance;
+        this.hit.nx = this.probed.normalX;
+        this.hit.ny = this.probed.normalY;
+        this.hit.nz = this.probed.normalZ;
+        return true;
+    }
+    gather(i, r, px, py, pz) {
+        const at = i * 6;
+        this.pending[at] = r[0];
+        this.pending[at + 1] = r[1];
+        this.pending[at + 2] = r[2];
+        this.pending[at + 3] += px;
+        this.pending[at + 4] += py;
+        this.pending[at + 5] += pz;
+    }
+}
+/** Sample a curve at `at`, holding the last value beyond its end. */
+export function sampleTyreCurve(curve, at) {
+    const n = curve.slip.length;
+    if (n === 0)
+        return 0;
+    if (at <= (curve.slip[0] ?? 0))
+        return curve.force[0] ?? 0;
+    for (let i = 1; i < n; i++) {
+        const s1 = curve.slip[i] ?? 0;
+        if (at <= s1) {
+            const s0 = curve.slip[i - 1] ?? 0;
+            const span = s1 - s0;
+            const t = span > 0 ? (at - s0) / span : 0;
+            const f0 = curve.force[i - 1] ?? 0;
+            return f0 + ((curve.force[i] ?? 0) - f0) * t;
+        }
+    }
+    return curve.force[n - 1] ?? 0;
+}
+const ANCHOR = new Float64Array(3);
+const DOWN = new Float64Array(3);
+const FORWARD = new Float64Array(3);
+const SIDE = new Float64Array(3);
+const VEL = new Float64Array(3);
+const INV_I = new Float32Array(6);
+function clampMagnitude(v, limit) {
+    if (v > limit)
+        return limit;
+    if (v < -limit)
+        return -limit;
+    return v;
+}
+/** A representative mass at the anchor, for turning a wanted velocity change into an impulse. */
+function massAt(bodies, body) {
+    const im = bodies.invMass[body] ?? 0;
+    return im > 0 ? 1 / im : 0;
+}
+function normalise(v) {
+    const len = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+    if (len === 0)
+        return;
+    v[0] /= len;
+    v[1] /= len;
+    v[2] /= len;
+}
+/** Remove the component of `v` along a normal, leaving it in the surface. */
+function project(v, nx, ny, nz) {
+    const d = v[0] * nx + v[1] * ny + v[2] * nz;
+    v[0] -= nx * d;
+    v[1] -= ny * d;
+    v[2] -= nz * d;
+}
+function rotate(bodies, i, src, at, out) {
+    const x = src[at] ?? 0;
+    const y = src[at + 1] ?? 0;
+    const z = src[at + 2] ?? 0;
+    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 tx = 2 * (qy * z - qz * y);
+    const ty = 2 * (qz * x - qx * z);
+    const tz = 2 * (qx * y - qy * x);
+    out[0] = x + qw * tx + (qy * tz - qz * ty);
+    out[1] = y + qw * ty + (qz * tx - qx * tz);
+    out[2] = z + qw * tz + (qx * ty - qy * tx);
+}
+/** A direction in the body's frame, rotated into world. */
+function axis(bodies, i, x, y, z, out) {
+    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 tx = 2 * (qy * z - qz * y);
+    const ty = 2 * (qz * x - qx * z);
+    const tz = 2 * (qx * y - qy * x);
+    out[0] = x + qw * tx + (qy * tz - qz * ty);
+    out[1] = y + qw * ty + (qz * tx - qx * tz);
+    out[2] = z + qw * tz + (qx * ty - qy * tx);
+}
+function pointVelocity(bodies, i, r, out) {
+    const wx = bodies.angX[i] ?? 0;
+    const wy = bodies.angY[i] ?? 0;
+    const wz = bodies.angZ[i] ?? 0;
+    out[0] = (bodies.velX[i] ?? 0) + (wy * r[2] - wz * r[1]);
+    out[1] = (bodies.velY[i] ?? 0) + (wz * r[0] - wx * r[2]);
+    out[2] = (bodies.velZ[i] ?? 0) + (wx * r[1] - wy * r[0]);
+}
+function applyImpulse(bodies, i, r, px, py, pz) {
+    const im = bodies.invMass[i] ?? 0;
+    if (im === 0)
+        return;
+    bodies.velX[i] = (bodies.velX[i] ?? 0) + px * im;
+    bodies.velY[i] = (bodies.velY[i] ?? 0) + py * im;
+    bodies.velZ[i] = (bodies.velZ[i] ?? 0) + pz * im;
+    bodies.worldInverseInertia(i, INV_I);
+    const tx = r[1] * pz - r[2] * py;
+    const ty = r[2] * px - r[0] * pz;
+    const tz = r[0] * py - r[1] * px;
+    bodies.angX[i] =
+        (bodies.angX[i] ?? 0) + (INV_I[0] ?? 0) * tx + (INV_I[3] ?? 0) * ty + (INV_I[4] ?? 0) * tz;
+    bodies.angY[i] =
+        (bodies.angY[i] ?? 0) + (INV_I[3] ?? 0) * tx + (INV_I[1] ?? 0) * ty + (INV_I[5] ?? 0) * tz;
+    bodies.angZ[i] =
+        (bodies.angZ[i] ?? 0) + (INV_I[4] ?? 0) * tx + (INV_I[5] ?? 0) * ty + (INV_I[2] ?? 0) * tz;
+}

package/dist/workerPool.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Islands solved on other threads, and every way that can decline to happen.
+ *
+ * **The handshake was never the problem.** `executor.ts` measured a fork-join over a
+ * `SharedArrayBuffer` at 11.8 microseconds for four workers against 2.6 milliseconds of solve. What
+ * stops a pool is that `SharedArrayBuffer` does not exist on a page that is not cross-origin
+ * isolated, and that is a header on the consumer's site rather than anything the engine can arrange.
+ * So this module's real subject is the four ways it can fail to start and the one way it must never
+ * fail: quietly.
+ *
+ * **Islands are claimed with `Atomics.add` on a cursor, which balances load and costs nothing.**
+ * Handing work out in arrival order is normally a determinism hazard. It is not one here, because
+ * two islands never write the same body — the property `DisjointExecutor` asserts — so the result
+ * does not depend on who solved what or when. A pool of eight and a pool of one produce the same
+ * bits, and so does the serial runner.
+ *
+ * **The caller solves its own share.** That is what keeps the join short on a browser's main thread,
+ * where `Atomics.wait` throws and the wait has to be a spin: by the time the caller runs out of
+ * islands to claim, the only thing left to wait for is the imbalance.
+ */
+import { SolveStage, StagedExecutor } from './stage.ts';
+import type { Executor } from './executor.ts';
+/**
+ * The part of a worker this pool uses.
+ *
+ * A browser `Worker` satisfies it and so does `node:worker_threads`, which is what lets the gate run
+ * the real entry point in Node instead of a stand-in that would prove nothing about threads.
+ */
+export interface PoolWorker {
+    postMessage(value: unknown): void;
+    terminate(): void | Promise<number>;
+}
+export declare const CTL_EPOCH = 0;
+export declare const CTL_CURSOR = 1;
+export declare const CTL_ISLANDS = 2;
+export declare const CTL_DONE = 3;
+export declare const CTL_ACK = 4;
+export declare const CTL_RELOAD = 5;
+export declare const CTL_STOP = 6;
+/** One slot per worker from here, counting the islands it has solved. */
+export declare const CTL_SOLVED = 7;
+/** What a consumer asked for. */
+export interface PoolRequest {
+    workers: number;
+    spawn?: () => PoolWorker;
+}
+/** What they got, and why, in a sentence fit to put on a debug overlay. */
+export interface PoolOutcome {
+    executor: Executor | null;
+    running: number;
+    reason: string;
+}
+/**
+ * Start a pool, or say why there is none.
+ *
+ * Never throws. Every path out sets a reason, because a consumer who asked for four workers and got
+ * none is owed the difference between "your browser will not let me" and "your bundler could not
+ * find the worker". A silent fallback here is a frame rate nobody can attribute, which is the exact
+ * complaint `capabilityClamp` exists to answer elsewhere in this engine.
+ */
+export declare function createIslandPool(request: PoolRequest): PoolOutcome;
+/**
+ * The pool itself: `StagedExecutor` with the serial solve replaced by a fork and a join.
+ *
+ * Everything about mirroring the state is inherited, which is what lets `stage.test.ts` hold the
+ * mirror to bit-identical physics with no threads in the picture and leaves this class responsible
+ * for one question only.
+ */
+export declare class WorkerPoolExecutor extends StagedExecutor implements Executor {
+    readonly name = "workers";
+    /** Set when the pool has given up. Read by `PhysicsWorld` so `parallelism` stops claiming workers. */
+    failure: string | null;
+    private readonly control;
+    private readonly blocking;
+    private posted;
+    private started;
+    private readonly workers;
+    constructor(workers: PoolWorker[]);
+    /** How many islands each worker has solved since the pool started. The engagement evidence. */
+    get solvedPerWorker(): number[];
+    /** Stop every worker. Idempotent, because a consumer may dispose a world twice. */
+    dispose(): void;
+    /**
+     * Fork, take a share, join. Returns false when the pool failed, which sends the tick back to the
+     * live state and a serial solve.
+     */
+    protected solve(count: number, stage: SolveStage): boolean;
+    /**
+     * Wait for every worker to finish this epoch, and give up rather than freeze.
+     *
+     * **A worker that dies mid-island is the failure this deadline exists for.** Without it the join
+     * spins until the tab is closed, which is a frozen game and the worst outcome available. With it
+     * the tick is re-solved from the live state, which is untouched until `pull`, and the pool is
+     * marked dead so every later tick is serial with a reason attached.
+     */
+    private join;
+    /**
+     * Hand the workers a new staging buffer and wait for them to adopt it.
+     *
+     * A worker parked in `Atomics.wait` cannot process a message, so it has to be let out first:
+     * `CTL_RELOAD` is set, the epoch is bumped, and a woken worker returns to its event loop instead
+     * of solving. It adopts the buffer in its message handler, acknowledges through `CTL_ACK`, and
+     * parks again. Rare by construction — a re-plan happens when a set doubles, which is about
+     * `log2(n)` times in a world's life and never inside a tick.
+     */
+    private reload;
+}

package/dist/workerPool.js

@@ -0,0 +1,239 @@
+/**
+ * Islands solved on other threads, and every way that can decline to happen.
+ *
+ * **The handshake was never the problem.** `executor.ts` measured a fork-join over a
+ * `SharedArrayBuffer` at 11.8 microseconds for four workers against 2.6 milliseconds of solve. What
+ * stops a pool is that `SharedArrayBuffer` does not exist on a page that is not cross-origin
+ * isolated, and that is a header on the consumer's site rather than anything the engine can arrange.
+ * So this module's real subject is the four ways it can fail to start and the one way it must never
+ * fail: quietly.
+ *
+ * **Islands are claimed with `Atomics.add` on a cursor, which balances load and costs nothing.**
+ * Handing work out in arrival order is normally a determinism hazard. It is not one here, because
+ * two islands never write the same body — the property `DisjointExecutor` asserts — so the result
+ * does not depend on who solved what or when. A pool of eight and a pool of one produce the same
+ * bits, and so does the serial runner.
+ *
+ * **The caller solves its own share.** That is what keeps the join short on a browser's main thread,
+ * where `Atomics.wait` throws and the wait has to be a spin: by the time the caller runs out of
+ * islands to claim, the only thing left to wait for is the imbalance.
+ */
+import { solveIslandInto } from './islandSolve.js';
+import { SolveStage, StagedExecutor } from './stage.js';
+/* Slots in the control block, which is its own buffer and outlives every re-plan of the stage. */
+export const CTL_EPOCH = 0;
+export const CTL_CURSOR = 1;
+export const CTL_ISLANDS = 2;
+export const CTL_DONE = 3;
+export const CTL_ACK = 4;
+export const CTL_RELOAD = 5;
+export const CTL_STOP = 6;
+/** One slot per worker from here, counting the islands it has solved. */
+export const CTL_SOLVED = 7;
+/** How long a join waits before it gives up on a worker and solves the tick itself. */
+const JOIN_DEADLINE_MS = 250;
+function sharedAlloc(bytes) {
+    return new SharedArrayBuffer(bytes);
+}
+/**
+ * Whether this thread may block.
+ *
+ * `Atomics.wait` is refused on a browser's main thread and permitted everywhere else, including a
+ * worker and Node. Asked by trying it, because the alternative is sniffing for `window` and being
+ * wrong in every runtime nobody thought of. The probe waits zero milliseconds on a value that does
+ * not match, so it returns `not-equal` immediately and blocks nothing.
+ */
+function canBlock() {
+    try {
+        const probe = new Int32Array(new SharedArrayBuffer(4));
+        Atomics.wait(probe, 0, 1, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Start a pool, or say why there is none.
+ *
+ * Never throws. Every path out sets a reason, because a consumer who asked for four workers and got
+ * none is owed the difference between "your browser will not let me" and "your bundler could not
+ * find the worker". A silent fallback here is a frame rate nobody can attribute, which is the exact
+ * complaint `capabilityClamp` exists to answer elsewhere in this engine.
+ */
+export function createIslandPool(request) {
+    const wanted = Math.max(0, Math.floor(request.workers));
+    if (wanted === 0)
+        return { executor: null, running: 0, reason: '' };
+    if (typeof SharedArrayBuffer === 'undefined') {
+        return {
+            executor: null,
+            running: 0,
+            reason: 'this page is not cross-origin isolated, so SharedArrayBuffer is undefined. Serve it with ' +
+                'Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp ' +
+                '(or credentialless) to enable the pool.',
+        };
+    }
+    const spawn = request.spawn ?? defaultSpawn;
+    if (spawn === null) {
+        return {
+            executor: null,
+            running: 0,
+            reason: 'this runtime has no Worker, and no spawn was given.',
+        };
+    }
+    const workers = [];
+    try {
+        for (let i = 0; i < wanted; i++)
+            workers.push(spawn());
+    }
+    catch (error) {
+        for (const worker of workers)
+            worker.terminate();
+        const message = String(error?.message ?? error);
+        return {
+            executor: null,
+            running: 0,
+            reason: `the worker entry failed to load: ${message}. Pass a spawn option building the worker ` +
+                'with your own bundler if it does not understand a worker entry point.',
+        };
+    }
+    return { executor: new WorkerPoolExecutor(workers), running: workers.length, reason: '' };
+}
+/**
+ * The worker this package ships, built the way a bundler understands.
+ *
+ * Vite, webpack 5 and Parcel all resolve `new URL('./x.ts', import.meta.url)` inside a `new Worker`.
+ * A build that does not throws, which becomes a reason and serial physics — and `spawn` is the way
+ * out, which is why this is a default and not the only path. Null where there is no `Worker` at all.
+ */
+const defaultSpawn = typeof Worker === 'undefined'
+    ? null
+    : () => new Worker(new URL('./islandWorker.ts', import.meta.url), { type: 'module' });
+/**
+ * The pool itself: `StagedExecutor` with the serial solve replaced by a fork and a join.
+ *
+ * Everything about mirroring the state is inherited, which is what lets `stage.test.ts` hold the
+ * mirror to bit-identical physics with no threads in the picture and leaves this class responsible
+ * for one question only.
+ */
+export class WorkerPoolExecutor extends StagedExecutor {
+    name = 'workers';
+    /** Set when the pool has given up. Read by `PhysicsWorld` so `parallelism` stops claiming workers. */
+    failure = null;
+    control;
+    blocking = canBlock();
+    posted = -1;
+    started = false;
+    workers;
+    constructor(workers) {
+        super(sharedAlloc);
+        this.workers = workers;
+        this.control = new Int32Array(new SharedArrayBuffer((CTL_SOLVED + workers.length) * 4));
+    }
+    /** How many islands each worker has solved since the pool started. The engagement evidence. */
+    get solvedPerWorker() {
+        return this.workers.map((_, i) => Atomics.load(this.control, CTL_SOLVED + i));
+    }
+    /** Stop every worker. Idempotent, because a consumer may dispose a world twice. */
+    dispose() {
+        if (this.workers.length === 0)
+            return;
+        Atomics.store(this.control, CTL_STOP, 1);
+        Atomics.add(this.control, CTL_EPOCH, 1);
+        Atomics.notify(this.control, CTL_EPOCH);
+        for (const worker of this.workers)
+            worker.terminate();
+        this.workers.length = 0;
+    }
+    /**
+     * Fork, take a share, join. Returns false when the pool failed, which sends the tick back to the
+     * live state and a serial solve.
+     */
+    solve(count, stage) {
+        if (this.failure !== null || this.workers.length === 0)
+            return false;
+        const ctl = this.control;
+        if (!this.started || stage.generation !== this.posted) {
+            if (!this.reload(stage))
+                return false;
+        }
+        Atomics.store(ctl, CTL_CURSOR, 0);
+        Atomics.store(ctl, CTL_ISLANDS, count);
+        Atomics.store(ctl, CTL_DONE, 0);
+        Atomics.add(ctl, CTL_EPOCH, 1);
+        Atomics.notify(ctl, CTL_EPOCH);
+        /* The caller's own share, from the same cursor, so what is left to wait for is the imbalance
+           and not the solve. */
+        for (;;) {
+            const island = Atomics.add(ctl, CTL_CURSOR, 1);
+            if (island >= count)
+                break;
+            solveIslandInto(stage.state, island);
+        }
+        return this.join();
+    }
+    /**
+     * Wait for every worker to finish this epoch, and give up rather than freeze.
+     *
+     * **A worker that dies mid-island is the failure this deadline exists for.** Without it the join
+     * spins until the tab is closed, which is a frozen game and the worst outcome available. With it
+     * the tick is re-solved from the live state, which is untouched until `pull`, and the pool is
+     * marked dead so every later tick is serial with a reason attached.
+     */
+    join() {
+        const ctl = this.control;
+        const wanted = this.workers.length;
+        const deadline = Date.now() + JOIN_DEADLINE_MS;
+        for (;;) {
+            const done = Atomics.load(ctl, CTL_DONE);
+            if (done >= wanted)
+                return true;
+            if (Date.now() > deadline) {
+                this.failure =
+                    'a worker stopped answering, so island solving went back to this thread. The world is ' +
+                        'correct and serial from here.';
+                return false;
+            }
+            if (this.blocking)
+                Atomics.wait(ctl, CTL_DONE, done, 50);
+        }
+    }
+    /**
+     * Hand the workers a new staging buffer and wait for them to adopt it.
+     *
+     * A worker parked in `Atomics.wait` cannot process a message, so it has to be let out first:
+     * `CTL_RELOAD` is set, the epoch is bumped, and a woken worker returns to its event loop instead
+     * of solving. It adopts the buffer in its message handler, acknowledges through `CTL_ACK`, and
+     * parks again. Rare by construction — a re-plan happens when a set doubles, which is about
+     * `log2(n)` times in a world's life and never inside a tick.
+     */
+    reload(stage) {
+        const ctl = this.control;
+        Atomics.store(ctl, CTL_ACK, 0);
+        Atomics.store(ctl, CTL_RELOAD, 1);
+        Atomics.add(ctl, CTL_EPOCH, 1);
+        Atomics.notify(ctl, CTL_EPOCH);
+        for (let i = 0; i < this.workers.length; i++) {
+            this.workers[i].postMessage({
+                kind: 'stage',
+                index: i,
+                control: ctl.buffer,
+                buffer: stage.buffer,
+                plan: stage.plan,
+            });
+        }
+        const deadline = Date.now() + JOIN_DEADLINE_MS;
+        while (Atomics.load(ctl, CTL_ACK) < this.workers.length) {
+            if (Date.now() > deadline) {
+                this.failure =
+                    'the workers did not take the shared buffer, so island solving stayed on this thread.';
+                return false;
+            }
+        }
+        Atomics.store(ctl, CTL_RELOAD, 0);
+        this.posted = stage.generation;
+        this.started = true;
+        return true;
+    }
+}