@driftengine/physics 3.61.0

package/dist/workers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The island worker pool, behind its own specifier.
+ *
+ * **Because a bundler emits the worker before it decides the pool is unreachable.** `workerPool.ts`
+ * builds its worker with `new Worker(new URL('./islandWorker.ts', import.meta.url))`, and Vite's
+ * `vite:worker-import-meta-url` rewrites that at *transform* time, which happens before
+ * tree-shaking. So a barrel that merely re-exported `createIslandPool` put the worker in the module
+ * graph, and the chunk was written to disk whether or not anything could ever fetch it.
+ *
+ * Reported by a consumer on 2026-09-05 and reproduced on a second the same day: **37,913 bytes raw
+ * and 12,259 gzipped**, in a build where `WorkerPoolExecutor`, `StagedExecutor`, `createIslandPool`
+ * and `SolveStage` were all absent from every other chunk and nothing under `dist/` named the
+ * worker. Tree-shaking had done its half and the asset was already on disk.
+ *
+ * **This is the same decision 3.54.0 made and half of it was missed.** That release moved the pool
+ * factory to the call site rather than have `PhysicsWorld` reach it, to avoid *"2,629 bytes gzipped
+ * into every consumer's bundle, including everyone who never asks for a worker"*. The measured
+ * weight of the half that was missed is 4.7 times the one that was caught, landing on exactly the
+ * consumer that reasoning was written to protect.
+ *
+ * A caller already had to name the factory for that reason, so the cost of the fix is the specifier
+ * and nothing else:
+ *
+ * ```ts
+ * import { PhysicsWorld } from '@driftengine/physics';
+ * import { createIslandPool } from '@driftengine/physics/src/workers.ts';
+ *
+ * const world = new PhysicsWorld({ workers: 4, pool: createIslandPool });
+ * ```
+ *
+ * `scripts/worker-entry.test.mjs` bundles the barrel and asserts it names no worker, because every
+ * gate in this repository passed while the chunk was shipping.
+ */
+export type { PoolOutcome, PoolRequest, PoolWorker } from './workerPool.ts';
+export { WorkerPoolExecutor, createIslandPool } from './workerPool.ts';
+export type { LanePlan, StagePlan } from './stage.ts';
+export { SolveStage, StagedExecutor } from './stage.ts';

package/dist/workers.js

@@ -0,0 +1,35 @@
+/**
+ * The island worker pool, behind its own specifier.
+ *
+ * **Because a bundler emits the worker before it decides the pool is unreachable.** `workerPool.ts`
+ * builds its worker with `new Worker(new URL('./islandWorker.ts', import.meta.url))`, and Vite's
+ * `vite:worker-import-meta-url` rewrites that at *transform* time, which happens before
+ * tree-shaking. So a barrel that merely re-exported `createIslandPool` put the worker in the module
+ * graph, and the chunk was written to disk whether or not anything could ever fetch it.
+ *
+ * Reported by a consumer on 2026-09-05 and reproduced on a second the same day: **37,913 bytes raw
+ * and 12,259 gzipped**, in a build where `WorkerPoolExecutor`, `StagedExecutor`, `createIslandPool`
+ * and `SolveStage` were all absent from every other chunk and nothing under `dist/` named the
+ * worker. Tree-shaking had done its half and the asset was already on disk.
+ *
+ * **This is the same decision 3.54.0 made and half of it was missed.** That release moved the pool
+ * factory to the call site rather than have `PhysicsWorld` reach it, to avoid *"2,629 bytes gzipped
+ * into every consumer's bundle, including everyone who never asks for a worker"*. The measured
+ * weight of the half that was missed is 4.7 times the one that was caught, landing on exactly the
+ * consumer that reasoning was written to protect.
+ *
+ * A caller already had to name the factory for that reason, so the cost of the fix is the specifier
+ * and nothing else:
+ *
+ * ```ts
+ * import { PhysicsWorld } from '@driftengine/physics';
+ * import { createIslandPool } from '@driftengine/physics/src/workers.ts';
+ *
+ * const world = new PhysicsWorld({ workers: 4, pool: createIslandPool });
+ * ```
+ *
+ * `scripts/worker-entry.test.mjs` bundles the barrel and asserts it names no worker, because every
+ * gate in this repository passed while the chunk was shipping.
+ */
+export { WorkerPoolExecutor, createIslandPool } from './workerPool.js';
+export { SolveStage, StagedExecutor } from './stage.js';

package/dist/world.d.ts

@@ -0,0 +1,298 @@
+import { BodySet } from './bodies.ts';
+import type { BodyDesc } from './bodies.ts';
+import type { ShapePose } from './manifold.ts';
+import type { FrictionModel } from './solver.ts';
+import type { QueryFilter, RayHit } from './query.ts';
+import type { ConvexShape } from './shape.ts';
+import { ContactEvents } from './events.ts';
+import { JointSet } from './joints.ts';
+import type { JointDesc } from './joints.ts';
+import type { Executor, IslandSolver } from './executor.ts';
+import type { IslandSolveState } from './islandSolve.ts';
+import type { PoolOutcome, PoolRequest, PoolWorker } from './workerPool.ts';
+/**
+ * A rigid body world, stepped on a fixed clock.
+ *
+ * **The tick order is the design, and every stage exists to keep the next one honest**: refresh the
+ * broadphase, collect pairs *sorted by body index* so nothing carries tree shape forward, build
+ * manifolds, then run N substeps of integrate-and-solve, one relax pass, and restitution once.
+ *
+ * **Substeps move a body inside a tick.** Only the state at the end of a tick is what a renderer's
+ * `alpha` interpolates against; anything sampling mid-tick sees substep state, which is why contact
+ * events are drained after the tick rather than raised during it.
+ */
+/** Options a consumer sets once. Every one of them is a quality or feel dial, not a contract. */
+export interface WorldOptions {
+    /** How many integrate-and-solve passes per tick. A quality dial: raising it changes nothing. */
+    substeps?: number;
+    /** Iterations per substep. */
+    iterations?: number;
+    gravityX?: number;
+    gravityY?: number;
+    gravityZ?: number;
+    /** Contact stiffness as a frequency, which is what makes `substeps` a dial. */
+    contactHertz?: number;
+    contactDamping?: number;
+    /** Joint stiffness, higher than a contact's because a joint is a structural relationship. */
+    jointHertz?: number;
+    jointDamping?: number;
+    linearDamping?: number;
+    angularDamping?: number;
+    /** How far apart two shapes may be and still get a constraint. */
+    speculativeMargin?: number;
+    /** Whether settled islands stop being solved. On by default; off for a test isolating something. */
+    allowSleep?: boolean;
+    /**
+     * How the two friction axes are bounded against each other. `box` by default. See `solver.ts`.
+     *
+     * **`elliptical` is the correct one and is not the default**, because every stacking result moves
+     * under it — `fingerprintBodies`, both baselines, and any golden fingerprint or stored replay a
+     * consumer has kept. A production engine does not silently invalidate those. What a
+     * consumer gets by asking for it is friction that is the same in every direction, which is what
+     * friction physically is; what a box gives instead is up to `sqrt(2)` more grip along the
+     * diagonal of a tangent basis built from the contact normal, which is an artefact rather than a
+     * fact about the world.
+     */
+    frictionModel?: FrictionModel;
+    /**
+     * How many workers solve islands. 0, the default, is the serial runner and changes nothing.
+     *
+     * **It needs a cross-origin isolated page.** Without one `SharedArrayBuffer` is undefined and the
+     * pool cannot start; physics stays correct and serial and `parallelism.reason` says so. See
+     * `workerPool.ts` for what the headers cost a consumer, which is why this is a switch and not a
+     * default. Clamped to `hardwareConcurrency - 1` where the runtime reports one.
+     */
+    workers?: number;
+    /**
+     * Build one worker yourself.
+     *
+     * The default is `new Worker(new URL('./islandWorker.ts', import.meta.url), { type: 'module' })`,
+     * which Vite, webpack 5 and Parcel resolve. Supply this when your build does not, or to point at
+     * an entry of your own that imports `@driftengine/physics/src/islandWorker.ts`.
+     */
+    spawn?: () => PoolWorker;
+    /**
+     * What builds the pool. `createIslandPool` is the one this package ships.
+     *
+     * **Passed in rather than imported here, and the reason is a measurement made twice.** A
+     * `PhysicsWorld` that reaches the pool on its own puts it in every consumer's bundle: 2,629 bytes
+     * gzipped charged to everyone who never asks for a worker, in a package whose promise is that you
+     * pay only for what you import.
+     *
+     * **That was half the problem and the other half cost 4.7 times as much.** Naming the factory at
+     * the call site let tree-shaking drop the pool, and a bundler had already emitted the *worker* —
+     * `new Worker(new URL(...))` is rewritten at transform time, before anything decides what is
+     * reachable. Measured on two consumers on 2026-09-05: 12,259 bytes gzipped of worker chunk that
+     * nothing in either bundle could fetch. So the factory left the barrel too; see `workers.ts`.
+     *
+     * ```ts
+     * import { PhysicsWorld } from '@driftengine/physics';
+     * import { createIslandPool } from '@driftengine/physics/src/workers.ts';
+     *
+     * const world = new PhysicsWorld({ workers: 4, pool: createIslandPool });
+     * ```
+     *
+     * Asking for workers without it is not silent: `parallelism.reason` says exactly this.
+     */
+    pool?: (request: PoolRequest) => PoolOutcome;
+}
+/** What a world's island solving is actually doing, and why. */
+export interface Parallelism {
+    /** Workers the consumer asked for. */
+    requested: number;
+    /** Workers running. Zero with a non-empty `reason` is a working fallback, not a failure. */
+    running: number;
+    /** Empty when `running` matches `requested`. A whole sentence otherwise. */
+    reason: string;
+}
+export declare class PhysicsWorld implements IslandSolver {
+    readonly bodies: BodySet;
+    readonly joints: JointSet;
+    /** What touched what during the last tick, ordered by pair key. Drain it after `step`. */
+    readonly events: ContactEvents;
+    /**
+     * Pairs that never collide, whatever their layers say.
+     *
+     * **The mask says what a body is; this says who two bodies are to each other.** See `pairKey`
+     * for why the two are not the same question and why a ragdoll can only be expressed by the
+     * second one.
+     *
+     * Kept as a set of packed keys and consulted only when it holds something, so a world that
+     * never calls `ignorePair` pays one integer compare per candidate pair.
+     */
+    private readonly ignoredPairs;
+    readonly substeps: number;
+    readonly iterations: number;
+    gravityX: number;
+    gravityY: number;
+    gravityZ: number;
+    contactHertz: number;
+    contactDamping: number;
+    jointHertz: number;
+    jointDamping: number;
+    linearDamping: number;
+    angularDamping: number;
+    speculativeMargin: number;
+    allowSleep: boolean;
+    /** Read at every substep, so a consumer may switch it between ticks. See `WorldOptions`. */
+    frictionModel: FrictionModel;
+    /** Who runs the islands. Swappable, and a gate asserts two characters agree. */
+    executor: Executor;
+    /**
+     * What the island solving is actually doing.
+     *
+     * **Read it rather than assuming the `workers` option took.** A pool needs a cross-origin isolated
+     * page and a bundler that understands a worker entry, and when either is missing this says which
+     * in a sentence fit to put on a debug overlay. `createSplatSortWorker` warns once on the console
+     * for the same reason; this is the same fact as data, because a console warning is not something a
+     * consumer can show a player or assert in a test.
+     */
+    readonly parallelism: Parallelism;
+    /**
+     * The scalars an island's solve reads, in the layout `islandSolve.ts` names.
+     *
+     * Written once a tick by `step` so a consumer may change gravity or the friction model between
+     * ticks and have every character see it, including one reading them out of shared memory.
+     */
+    private dials;
+    private tree;
+    private islands;
+    private stepDt;
+    private leafOf;
+    private pairs;
+    private constraints;
+    private manifold;
+    private box;
+    private poseA;
+    private poseB;
+    /** Previous tick's impulses, by pair key then feature id. */
+    /**
+     * One manifold per contact plane a mesh pair produced. Allocated once; the tick may not.
+     *
+     * `MAX_MESH_MANIFOLDS` planes is a body wedged in a corner with room to spare. A pair that fills
+     * it drops the rest, which for a convex body against a mesh means dropping the shallowest planes
+     * — the tree returns candidates in its own order, so what is kept is the first eight it met.
+     */
+    /**
+     * The manifold set a compound pair fills, sized so a compound against one convex shape cannot
+     * overflow: one plane per part, and `MAX_PAIR_MANIFOLDS` is `MAX_BODY_PARTS`.
+     *
+     * Separate from `meshManifolds` rather than one larger set shared by both, because `collideMesh`
+     * fills up to the length it is given — handing it thirty-two would change how many contact planes
+     * a shipped mesh pair produces, which is a behaviour change nobody asked for.
+     */
+    private readonly pairManifolds;
+    private readonly meshManifolds;
+    private warm;
+    private nextWarm;
+    private warmN;
+    private warmT1;
+    private warmT2;
+    constructor(options?: WorldOptions);
+    /**
+     * Stop the worker pool, if there is one. Safe to call twice, and safe on a world without one.
+     *
+     * **A world with a pool must be disposed.** Its workers hold the staging `SharedArrayBuffer`, so
+     * a consumer replacing a world between levels leaks both the threads and every body's state with
+     * them.
+     */
+    dispose(): void;
+    /** Join two bodies. The relative pose they are in now becomes the one the joint holds. */
+    addJoint(desc: JointDesc): number;
+    addBody(desc: BodyDesc): number;
+    /**
+     * Never collide these two, whichever order they are given in and whatever their layers say.
+     *
+     * Both indices are followed through `removeBody`, so an exclusion cannot outlive the body it
+     * was made about and cannot be inherited by whatever takes its slot.
+     */
+    ignorePair(a: number, b: number): void;
+    /** Undo one `ignorePair`. Doing it to a pair that was never excluded is not an error. */
+    allowPair(a: number, b: number): void;
+    /** Whether these two are excluded. */
+    pairIgnored(a: number, b: number): boolean;
+    /**
+     * Follow the exclusions through a swap-remove.
+     *
+     * **A body index is a slot and not an identity**, which is the same fact `removeBody` clears the
+     * warm cache and the contact events for: removing one moves the last body into the hole, so a
+     * remembered index is either gone or now names somebody else. An exclusion left alone would
+     * quietly stop the newcomer colliding with whatever the departed was jointed to.
+     */
+    private followRemoval;
+    removeBody(index: number): void;
+    /** Advance one fixed tick. */
+    step(dt: number): void;
+    /**
+     * Advance one island through every substep. The executor calls this; nothing else should.
+     *
+     * 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.
+     */
+    solveIsland(island: number): void;
+    /**
+     * The flat view of this world an island's solve needs, and the only view a worker could hold.
+     *
+     * Built fresh because `grow` replaces the arrays underneath it; the object is five references and
+     * one allocation, which the solve that follows dwarfs.
+     *
+     * **Public because a character off this thread needs it.** `SerialExecutor` calls `solveIsland`;
+     * a staged or pooled character mirrors this state into shared memory and solves that instead, which
+     * it cannot do through a method closed over the live arrays.
+     */
+    get solveState(): IslandSolveState;
+    /** Copy the dials into the block every character reads. Called once a tick, before the islands run. */
+    private writeDials;
+    /** A body's world bounds, grown by the speculative margin so a contact is seen before it is made. */
+    private boundsOf;
+    private readPose;
+    private loadWarm;
+    private storeWarm;
+    /**
+     * Islands sleep, not bodies.
+     *
+     * A box that slept while its neighbour was still moving would be woken by that neighbour on the
+     * very next tick and never rest — so a body accumulates its counter only when **every** body in
+     * its island is below both thresholds, and the whole island resets together when one is not.
+     *
+     * Tick-counted and never time-based, because sleeping changes results and results have to replay.
+     */
+    private updateSleep;
+    /** Wake a body and everything sharing its island, which is what an external impulse must do. */
+    wakeIsland(index: number): void;
+    /** Whether every body in an island has been still long enough to stop being solved. */
+    /** The nearest body a ray meets. Fills `out` and allocates nothing. */
+    raycast(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDistance: number, out: RayHit, filter?: QueryFilter): boolean;
+    /** The first body a swept shape touches. */
+    shapecast(shape: ConvexShape, pose: ShapePose, dx: number, dy: number, dz: number, out: RayHit, filter?: QueryFilter): boolean;
+    /** Every body overlapping a shape, filling `out` to its length. Returns how many were written. */
+    overlap(shape: ConvexShape, pose: ShapePose, out: Int32Array, filter?: QueryFilter): number;
+    /**
+     * Apply an impulse at a world-space point.
+     *
+     * **The point is not optional**, and `bindings/core.ts` makes it required at the language boundary
+     * for the reason `AGENTS.md`'s step four gives: a caller who omits it gets an impulse through the
+     * centre of mass, which produces no rotation at all. That is a wrong *result* rather than an
+     * error, and it reads as a broken impulse rather than as a missing argument.
+     */
+    applyImpulse(body: number, px: number, py: number, pz: number, atX: number, atY: number, atZ: number): void;
+    /** A force applied for one tick, which is an impulse of `force · dt`. */
+    applyForce(body: number, fx: number, fy: number, fz: number, dt: number, atX: number, atY: number, atZ: number): void;
+    /** Set a body's velocity outright, waking whatever it was resting against. */
+    setVelocity(body: number, vx: number, vy: number, vz: number): void;
+    /**
+     * Move a body outright, which is a teleport rather than a push.
+     *
+     * The broadphase proxy moves with it, or the body would be found where it used to be until it
+     * next drifted out of its own fat bounds.
+     */
+    setPosition(body: number, x: number, y: number, z: number): void;
+    /** A body's mass, or zero where it has none because it is static or kinematic. */
+    bodyMass(body: number): number;
+    /** How many islands the last step found. */
+    get islandCount(): number;
+    /** Whether a body is currently asleep, for a caller deciding whether to bother. */
+    sleeping(index: number): boolean;
+    /** Whether a body has been still long enough to stop being integrated. */
+    private asleep;
+}