@codexo/exojs-physics 0.15.2 → 0.16.0

package/dist/esm/PhysicsWorld.js

@@ -1,630 +1,894 @@
-import { Signal, Vector } from '@codexo/exojs';
-import { NativePhysicsBackend } from './backend/NativePhysicsBackend.js';
-import { BindingRegistry } from './binding/BindingRegistry.js';
-import { Collider } from './Collider.js';
-import { PhysicsBody } from './PhysicsBody.js';
-import { QueryEngine } from './query/QueryEngine.js';
-import { TimeStepper } from './TimeStepper.js';
+import { aabbOverlap, createAabb } from "./Aabb.js";
+import { shouldCollide } from "./types.js";
+import { Collider, authoredCollider } from "./Collider.js";
+import { PhysicsBody } from "./PhysicsBody.js";
+import { sleepPenetrationTolerance } from "./solver/tolerances.js";
+import { NativePhysicsBackend } from "./backend/NativePhysicsBackend.js";
+import { BindingRegistry } from "./binding/BindingRegistry.js";
+import { sweepProxies } from "./collision/sweep.js";
+import { QueryEngine } from "./query/QueryEngine.js";
+import { TimeStepper } from "./TimeStepper.js";
+import { Signal, Vector } from "@codexo/exojs";
 
-/** Gap left between a clamped bullet and the surface it hit (so it does not re-hit from inside). */
-const ccdSkin = 0.05;
+//#region src/PhysicsWorld.ts
 /**
- * The collision/query world: owns bodies, colliders, the detection backend,
- * bindings, the query engine and the fixed-step accumulator. Stepped by the
- * caller (commonly from a `Scene.update`), each fixed sub-step it integrates
- * body velocities, runs broad- and narrow-phase detection, solves contacts and
- * integrates positions, then fires immutable contact/sensor events and writes
- * bound node transforms. It holds **no module-level state**, so any number of
- * worlds run in isolation (gate I-1).
- *
- * The dynamics are a native, warm-started **TGS-Soft** solver (Box2D-v3 "soft
- * step"): each fixed step runs detection once, then several sub-steps, each
- * integrating gravity over the sub-step and solving contacts with a soft
- * position bias plus a bias-free relax pass; a 2-point block normal solve
- * propagates stack loads, and restitution is a separate final pass. Decoupling
- * stiffness from the iteration count keeps tall towers stable. The detection
- * backend sits behind an internal seam, so the solver is swappable without
- * touching this public surface.
- *
- * **Operating envelope.** The soft solver trades a little accuracy for
- * robustness, so it has a few documented limits — each stays finite/stable and
- * each is pinned by a gate in `dynamics.test.ts`:
- * - **Mass ratio** — resting stacks are slop-accurate up to ~100:1. Beyond that
- *   the velocity-capped soft push-out (`maxBiasVelocity`) lets the lighter body
- *   settle progressively deeper (≈6px at 500:1, fully through a thin floor by
- *   ~5000:1) — always finite, never exploding (SG-MR3).
- * - **No CCD** — detection runs once per fixed step with no swept test, so a
- *   body that travels farther than an obstacle's thickness in one step tunnels
- *   straight through it (it stays finite). Reliably stopping fast projectiles is
- *   a future bullet-mode feature (SG-X5).
- * - **{@link PhysicsWorldOptions.subStepCount}** — the default `4` is
- *   load-bearing for tall-stack stability; lowering it below `2` visibly
- *   degrades stacking, so do not reduce it for performance.
- */
-class PhysicsWorld {
-    /** Fires when two solid colliders begin touching. Argument is an immutable snapshot. */
-    onCollisionStart = new Signal();
-    /** Fires when two solid colliders stop touching (or one is destroyed). */
-    onCollisionEnd = new Signal();
-    /** Fires when a collider enters a sensor. */
-    onSensorEnter = new Signal();
-    /** Fires when a collider leaves a sensor. */
-    onSensorExit = new Signal();
-    /** World gravity (px/s², +Y down). Integrated each sub-step. */
-    gravity;
-    /** The fixed-step accumulator. */
-    timeStepper;
-    /** TGS-Soft sub-steps per fixed step. */
-    subStepCount;
-    /** Soft-contact stiffness in Hz. */
-    contactHertz;
-    /** Soft-contact damping ratio. */
-    dampingRatio;
-    /** Whether resting bodies are put to sleep. */
-    enableSleeping;
-    /** Linear sleep threshold (px/s). */
-    sleepLinearVelocity;
-    /** Angular sleep threshold (rad/s). */
-    sleepAngularVelocity;
-    /** Seconds below the thresholds before a body sleeps. */
-    timeToSleep;
-    _backend = new NativePhysicsBackend();
-    _bodies = [];
-    _colliders = [];
-    _joints = [];
-    _bindings = new BindingRegistry();
-    _query;
-    _commands = [];
-    /** Pooled union-find parent array for the per-step island pass (reused; sized to the body count). */
-    _islandParent = [];
-    /** Pooled per-island minimum sleep time, indexed by union-find root. */
-    _islandMinSleep = [];
-    /** Pooled ray-hit buffer + origin/direction for the CCD swept test. */
-    _ccdHits = [];
-    _ccdOrigin = { x: 0, y: 0 };
-    _ccdDir = { x: 0, y: 0 };
-    _nextBodyId = 1;
-    _nextColliderId = 1;
-    _dispatching = false;
-    _destroyed = false;
-    constructor(options = {}) {
-        this.gravity = new Vector(options.gravity?.x ?? 0, options.gravity?.y ?? 0);
-        this.timeStepper = new TimeStepper({
-            ...(options.fixedDelta !== undefined && { fixedDelta: options.fixedDelta }),
-            ...(options.maxSubSteps !== undefined && { maxSubSteps: options.maxSubSteps }),
-        });
-        const subStepCount = options.subStepCount ?? 4;
-        if (!Number.isInteger(subStepCount) || subStepCount < 1) {
-            throw new RangeError(`PhysicsWorld: subStepCount must be an integer ≥ 1, received ${subStepCount}.`);
-        }
-        this.subStepCount = subStepCount;
-        this.contactHertz = options.contactHertz ?? 30;
-        this.dampingRatio = options.dampingRatio ?? 10;
-        this.enableSleeping = options.enableSleeping ?? true;
-        this.sleepLinearVelocity = options.sleepLinearVelocity ?? 5;
-        this.sleepAngularVelocity = options.sleepAngularVelocity ?? 0.06;
-        this.timeToSleep = options.timeToSleep ?? 0.5;
-        this._query = new QueryEngine(this._colliders);
-    }
-    /** Live bodies (read-only view). */
-    get bodies() {
-        return this._bodies;
-    }
-    /** Live colliders (read-only view). */
-    get colliders() {
-        return this._colliders;
-    }
-    // ── lifecycle ──────────────────────────────────────────────────────────
-    /**
-     * Add a body to the world: allocates the body and its collider ids, registers
-     * the colliders, computes the mass model and tracks the body for stepping.
-     * Construct the body freely first (`new PhysicsBody({ … })`), then add it.
-     * Safe to call inside an event callback — the body push is deferred to the end
-     * of the step, exactly like collider registration. Returns the body.
-     *
-     * @throws if the body has already been added to a world.
-     */
-    add(body) {
-        this._assertAlive();
-        if (body.attached) {
-            throw new Error('PhysicsWorld.add: this body has already been added to a world.');
-        }
-        // Allocate the id + link/register colliders + aggregate mass now (matches the
-        // old createBody, which allocated the id synchronously); only the body-list
-        // push is deferred so it is safe inside an event dispatch.
-        body._attachToWorld(this, this._nextBodyId++);
-        this._defer(() => {
-            if (!body.destroyed) {
-                this._bodies.push(body);
-            }
-        });
-        return body;
-    }
-    /**
-     * Convenience: create a body carrying a single collider, add it to the world
-     * and bind it to `node` in one call. The node tracks `body.position` after each
-     * step. Returns the body. Equivalent to `new PhysicsBody(...)` + `add` + `bind`.
-     */
-    attach(node, options) {
-        const body = new PhysicsBody({
-            ...(options.type !== undefined && { type: options.type }),
-            ...(options.position !== undefined && { position: options.position }),
-            ...(options.angle !== undefined && { angle: options.angle }),
-            ...(options.gravityScale !== undefined && { gravityScale: options.gravityScale }),
-            ...(options.fixedRotation !== undefined && { fixedRotation: options.fixedRotation }),
-            colliders: [
-                new Collider({
-                    shape: options.shape,
-                    ...(options.offset !== undefined && { offset: options.offset }),
-                    ...(options.rotation !== undefined && { rotation: options.rotation }),
-                    ...(options.density !== undefined && { density: options.density }),
-                    ...(options.friction !== undefined && { friction: options.friction }),
-                    ...(options.restitution !== undefined && { restitution: options.restitution }),
-                    ...(options.isSensor !== undefined && { isSensor: options.isSensor }),
-                    ...(options.filter !== undefined && { filter: options.filter }),
-                }),
-            ],
-        });
-        this.add(body);
-        this.bind(body, node);
-        return body;
-    }
-    /** Destroy a body and its colliders. Deferred when called inside a callback. */
-    destroyBody(body) {
-        this._defer(() => this._removeBody(body));
-    }
-    /** Destroy a single collider, recomputing its body's mass. Deferred when called inside a callback. */
-    destroyCollider(collider) {
-        this._defer(() => this._removeCollider(collider));
-    }
-    /** Live joints (read-only view). */
-    get joints() {
-        return this._joints;
-    }
-    /**
-     * Add a constraint joint. Construct it first (`new DistanceJoint({ … })`),
-     * then add it. Wakes both bodies; safe inside a callback (registration is
-     * deferred). Returns the joint.
-     */
-    addJoint(joint) {
-        this._assertAlive();
-        joint.bodyA.wake();
-        joint.bodyB.wake();
-        this._defer(() => {
-            if (!this._joints.includes(joint)) {
-                this._joints.push(joint);
-            }
-        });
-        return joint;
-    }
-    /** Remove a joint, waking both bodies so they respond to the lost constraint. Deferred when called inside a callback. */
-    removeJoint(joint) {
-        joint.bodyA.wake();
-        joint.bodyB.wake();
-        this._defer(() => {
-            const index = this._joints.indexOf(joint);
-            if (index !== -1) {
-                this._joints.splice(index, 1);
-            }
-        });
-    }
-    // ── stepping ───────────────────────────────────────────────────────────
-    /**
-     * Advance the world by `frameDeltaSeconds`. Accumulates into fixed steps; each
-     * fixed step runs detection once, then a TGS-Soft sub-step loop (integrate
-     * gravity, solve contacts with a soft bias, integrate positions, relax) and a
-     * restitution pass, then writes the accumulated motion into each body. Finally
-     * dispatches events and writes bound node transforms.
-     */
-    step(frameDeltaSeconds) {
-        this._assertAlive();
-        const steps = this.timeStepper.advance(frameDeltaSeconds);
-        if (steps > 0) {
-            const subStepCount = this.subStepCount;
-            const h = this.timeStepper.fixedDelta / subStepCount;
-            const gravityX = this.gravity.x;
-            const gravityY = this.gravity.y;
-            const contactHertz = this.contactHertz;
-            const dampingRatio = this.dampingRatio;
-            const hasJoints = this._joints.length > 0;
-            const hasBullets = this._hasBullets();
-            for (let step = 0; step < steps; step++) {
-                // Detection runs once per fixed step (collider geometry is already current
-                // from the previous frame's finalize / attach / setTransform). TGS-Soft
-                // reuses the manifolds across the sub-steps below.
-                this._backend.detect(this._colliders);
-                // Sleep decision runs after detection (islands need the current contact
-                // set) and before the solver (so sleeping contacts are skipped, and a
-                // sleeping island touched by an awake body is woken first).
-                if (this.enableSleeping) {
-                    this._updateSleeping(this.timeStepper.fixedDelta);
-                }
-                this._backend.prepareSolve(h, contactHertz, dampingRatio);
-                if (hasJoints) {
-                    this._prepareJoints(h);
-                }
-                if (hasBullets) {
-                    this._recordBulletPositions();
-                }
-                for (let subStep = 0; subStep < subStepCount; subStep++) {
-                    // Integrate gravity/forces over the sub-step (forces persist across
-                    // sub-steps; cleared once per frame by `_finalizePosition`).
-                    for (const body of this._bodies) {
-                        body._integrateVelocity(h, gravityX, gravityY);
-                    }
-                    // Warm-start every sub-step (Box2D-v3 soft step): the relax pass leaves
-                    // each contact's normal velocity at zero, so re-applying the
-                    // accumulated impulse re-balances exactly this sub-step's gravity — the
-                    // impulse converges to the per-sub-step load (m·h·g), not the per-frame
-                    // load, which is what keeps tall stacks from pumping energy.
-                    this._backend.warmStart();
-                    if (hasJoints) {
-                        this._warmStartJoints();
-                    }
-                    // Main soft-bias velocity solve, integrate positions (accumulating
-                    // per-body delta), then the bias-free relax pass. Joints solve right
-                    // after the contacts in each pass (contacts are the stiffer constraint).
-                    this._backend.solveVelocities(true);
-                    if (hasJoints) {
-                        this._solveJoints(true);
-                    }
-                    for (const body of this._bodies) {
-                        body._integratePosition(h);
-                    }
-                    this._backend.solveVelocities(false);
-                    if (hasJoints) {
-                        this._solveJoints(false);
-                    }
-                }
-                // Separate restitution pass, then write the accumulated delta into each
-                // body's transform and re-sync collider geometry.
-                this._backend.applyRestitution();
-                for (const body of this._bodies) {
-                    body._finalizePosition();
-                }
-                if (hasBullets) {
-                    this._advanceBullets();
-                }
-            }
-            this._dispatchEvents();
-        }
-        this._bindings.sync();
-        this._drainCommands();
-    }
-    // ── binding ────────────────────────────────────────────────────────────
-    /** Link a body to a scene node; the node tracks the body after each step. */
-    bind(body, node) {
-        return this._bindings.bind(body, node);
-    }
-    /** Remove a body↔node link. */
-    unbind(body) {
-        this._bindings.unbind(body);
-    }
-    // ── queries ────────────────────────────────────────────────────────────
-    /** Colliders containing `point`. Fresh array. */
-    queryPoint(point, filter) {
-        return this._query.queryPoint(point, filter);
-    }
-    /** Colliders whose AABB overlaps `bounds`. Writes into `out` (cleared) if given. */
-    queryAabb(bounds, filter, out) {
-        return this._query.queryAabb(bounds, filter, out);
-    }
-    /** Invoke `callback` for each collider whose AABB overlaps `bounds`. Allocation-free. */
-    forEachAabbHit(bounds, filter, callback) {
-        this._query.forEachAabbHit(bounds, filter, callback);
-    }
-    /** Nearest collider hit by the ray, or `null`. */
-    rayCast(origin, direction, filter, maxDistance) {
-        return this._query.rayCast(origin, direction, filter, maxDistance);
-    }
-    /** All collider hits along the ray, sorted by distance. Writes into `out` (cleared) if given. */
-    rayCastAll(origin, direction, filter, out, maxDistance) {
-        return this._query.rayCastAll(origin, direction, filter, out, maxDistance);
-    }
-    /** Colliders overlapping `shape` placed at `position`/`angle`. Fresh array. */
-    overlapShape(shape, position, filter, angle) {
-        return this._query.overlapShape(shape, position, filter, angle);
-    }
-    /** Release every body, collider, binding and backend resource. */
-    destroy() {
-        if (this._destroyed) {
-            return;
-        }
-        this._destroyed = true;
-        for (const body of this._bodies) {
-            body._markDestroyed();
-        }
-        this._bodies.length = 0;
-        this._colliders.length = 0;
-        this._joints.length = 0;
-        this._commands.length = 0;
-        this._bindings.clear();
-        this._backend.destroy();
-        this.onCollisionStart.destroy();
-        this.onCollisionEnd.destroy();
-        this.onSensorEnter.destroy();
-        this.onSensorExit.destroy();
-    }
-    // ── BodyOwner ──────────────────────────────────────────────────────────
-    _allocateColliderId() {
-        return this._nextColliderId++;
-    }
-    _registerCollider(collider) {
-        this._defer(() => {
-            if (!collider.destroyed) {
-                this._colliders.push(collider);
-            }
-        });
-    }
-    // ── internals ──────────────────────────────────────────────────────────
-    /** The detection backend (internal; consumed by the debug draw layer). */
-    get backend() {
-        return this._backend;
-    }
-    _dispatchEvents() {
-        const graph = this._backend.contactGraph;
-        this._dispatching = true;
-        for (const event of graph.collisionEnd) {
-            this.onCollisionEnd.dispatch(event);
-        }
-        for (const event of graph.sensorExit) {
-            this.onSensorExit.dispatch(event);
-        }
-        for (const event of graph.collisionStart) {
-            this.onCollisionStart.dispatch(event);
-        }
-        for (const event of graph.sensorEnter) {
-            this.onSensorEnter.dispatch(event);
-        }
-        this._dispatching = false;
-    }
-    /**
-     * Accumulate per-body sleep timers and put/keep islands of resting bodies
-     * asleep so a stack sleeps and wakes as one unit. An island is a connected
-     * component of dynamic bodies joined by touching solid contacts (static and
-     * kinematic bodies are boundaries, not nodes); it sleeps once every member has
-     * stayed below the sleep thresholds for `timeToSleep`, and wakes the instant
-     * any member does (e.g. an awake body merges into it via a new contact).
-     * Deterministic: union-find roots break ties by lower index and the contact
-     * set is id-sorted.
-     */
-    _updateSleeping(dt) {
-        const bodies = this._bodies;
-        const count = bodies.length;
-        const parent = this._islandParent;
-        const minSleep = this._islandMinSleep;
-        // Assign dense indices, reset the union-find, and accumulate sleep timers for
-        // awake dynamic bodies (a sleeping body's timer stays frozen ≥ timeToSleep).
-        for (let i = 0; i < count; i++) {
-            const body = bodies[i];
-            body._islandIndex = i;
-            parent[i] = i;
-            minSleep[i] = Infinity;
-            if (body.type === 'dynamic' && !body.isSleeping) {
-                body._accumulateSleepTime(dt, this.sleepLinearVelocity, this.sleepAngularVelocity);
-            }
-        }
-        parent.length = count;
-        minSleep.length = count;
-        // Union dynamic↔dynamic solid contacts into islands.
-        for (const contact of this._backend.contactGraph.solidContacts) {
-            const bodyA = contact.a.body;
-            const bodyB = contact.b.body;
-            if (bodyA.type === 'dynamic' && bodyB.type === 'dynamic') {
-                this._union(bodyA._islandIndex, bodyB._islandIndex);
-            }
-        }
-        // Joints couple their two bodies into the same island (sleep/wake together).
-        for (const joint of this._joints) {
-            const bodyA = joint.bodyA;
-            const bodyB = joint.bodyB;
-            if (joint.enabled && bodyA.type === 'dynamic' && bodyB.type === 'dynamic') {
-                this._union(bodyA._islandIndex, bodyB._islandIndex);
-            }
-        }
-        // Per-island minimum sleep time over its dynamic members.
-        for (let i = 0; i < count; i++) {
-            const body = bodies[i];
-            if (body.type === 'dynamic') {
-                const root = this._find(i);
-                if (body._sleepTime < minSleep[root]) {
-                    minSleep[root] = body._sleepTime;
-                }
-            }
-        }
-        // Sleep an island iff every member has rested for `timeToSleep`; otherwise
-        // wake it (which also wakes any member dragged awake by a fresh contact).
-        const timeToSleep = this.timeToSleep;
-        for (let i = 0; i < count; i++) {
-            const body = bodies[i];
-            if (body.type === 'dynamic') {
-                body._setSleeping(minSleep[this._find(i)] >= timeToSleep);
-            }
-        }
-    }
-    /** Union-find union by lower index (deterministic roots). */
-    _union(a, b) {
-        const rootA = this._find(a);
-        const rootB = this._find(b);
-        if (rootA < rootB) {
-            this._islandParent[rootB] = rootA;
-        }
-        else if (rootB < rootA) {
-            this._islandParent[rootA] = rootB;
-        }
-    }
-    /** Union-find find with path halving. */
-    _find(index) {
-        const parent = this._islandParent;
-        while (parent[index] !== index) {
-            const grandparent = parent[parent[index]];
-            parent[index] = grandparent;
-            index = grandparent;
-        }
-        return index;
-    }
-    /** Build each joint's per-frame constraint data (once per fixed step). */
-    _prepareJoints(h) {
-        for (const joint of this._joints) {
-            joint._prepare(h);
-        }
-    }
-    /** Re-apply each joint's accumulated impulse (each sub-step). */
-    _warmStartJoints() {
-        for (const joint of this._joints) {
-            joint._warmStart();
-        }
-    }
-    /** One joint velocity pass (each sub-step, after the contacts). */
-    _solveJoints(useBias) {
-        for (const joint of this._joints) {
-            joint._solve(useBias);
-        }
-    }
-    /** Whether any dynamic body is flagged for continuous collision (bullet mode). */
-    _hasBullets() {
-        for (const body of this._bodies) {
-            if (body.isBullet && body.type === 'dynamic') {
-                return true;
-            }
-        }
-        return false;
-    }
-    /** Snapshot each bullet's centre of mass at the start of the fixed step (the swept-test origin). */
-    _recordBulletPositions() {
-        for (const body of this._bodies) {
-            if (body.isBullet && body.type === 'dynamic') {
-                body._ccdPrevX = body.worldCenterOfMassX;
-                body._ccdPrevY = body.worldCenterOfMassY;
-            }
-        }
-    }
-    /**
-     * Sweep each bullet's centre of mass along this fixed step's motion against every
-     * other body's colliders; if it would cross one, clamp the body just short of the
-     * surface and resolve the impact about the surface normal (a slide for a non-bouncy
-     * body, an elastic reflection as restitution → 1) so it cannot tunnel. Sweeps the
-     * centre point — good for small/point-like projectiles; a full swept-shape TOI for
-     * large fast bodies is backlog (raise sub-steps or thicken geometry meanwhile).
-     */
-    _advanceBullets() {
-        for (const body of this._bodies) {
-            if (!body.isBullet || body.type !== 'dynamic' || body.isSleeping) {
-                continue;
-            }
-            const newX = body.worldCenterOfMassX;
-            const newY = body.worldCenterOfMassY;
-            let dirX = newX - body._ccdPrevX;
-            let dirY = newY - body._ccdPrevY;
-            const distance = Math.hypot(dirX, dirY);
-            if (distance < 1e-6) {
-                continue;
-            }
-            dirX /= distance;
-            dirY /= distance;
-            this._ccdOrigin.x = body._ccdPrevX;
-            this._ccdOrigin.y = body._ccdPrevY;
-            this._ccdDir.x = dirX;
-            this._ccdDir.y = dirY;
-            const hits = this._query.rayCastAll(this._ccdOrigin, this._ccdDir, undefined, this._ccdHits, distance);
-            let blocked = null;
-            for (const hit of hits) {
-                // Sweep against every other body (static, kinematic, dynamic); sensors never
-                // block. Hits are distance-sorted, so the first match is the nearest surface.
-                if (hit.body !== body && !hit.collider.isSensor) {
-                    blocked = hit;
-                    break;
-                }
-            }
-            if (blocked === null) {
-                continue;
-            }
-            // Clamp the CoM just short of the surface (a pure translation — the rotation
-            // is already applied), then resolve the impact about the surface normal.
-            const clampDistance = Math.max(0, blocked.distance - ccdSkin);
-            const deltaX = body._ccdPrevX + dirX * clampDistance - newX;
-            const deltaY = body._ccdPrevY + dirY * clampDistance - newY;
-            this._ccdOrigin.x = body.x + deltaX;
-            this._ccdOrigin.y = body.y + deltaY;
-            body.setTransform(this._ccdOrigin, body.angle);
-            // Reflect about the true surface normal: a slide for a non-bouncy body
-            // (restitution 0), an elastic bounce as restitution → 1. The body's own
-            // restitution combines (max) with the surface's, matching the contact solver.
-            const nx = blocked.normal.x;
-            const ny = blocked.normal.y;
-            const vn = body.linearVelocityX * nx + body.linearVelocityY * ny;
-            if (vn < 0) {
-                const restitution = vn < -1 ? Math.max(this._bulletRestitution(body), blocked.collider.restitution) : 0;
-                const impulse = -(1 + restitution) * vn;
-                body.linearVelocityX += impulse * nx;
-                body.linearVelocityY += impulse * ny;
-            }
-        }
-    }
-    /** The highest restitution among a body's colliders (its CCD bounce factor). */
-    _bulletRestitution(body) {
-        let restitution = 0;
-        for (const collider of body.colliders) {
-            if (collider.restitution > restitution) {
-                restitution = collider.restitution;
-            }
-        }
-        return restitution;
-    }
-    /** Run `command` now, or queue it when inside an event dispatch (deferred to end of step). */
-    _defer(command) {
-        if (this._dispatching) {
-            this._commands.push(command);
-        }
-        else {
-            command();
-        }
-    }
-    _drainCommands() {
-        if (this._commands.length === 0) {
-            return;
-        }
-        const commands = this._commands.splice(0, this._commands.length);
-        for (const command of commands) {
-            command();
-        }
-    }
-    _removeBody(body) {
-        const index = this._bodies.indexOf(body);
-        if (index === -1) {
-            // Never added (created and destroyed within the same dispatch) — still
-            // tear down its colliders and mark it dead.
-            this._teardownBody(body);
-            return;
-        }
-        this._bodies.splice(index, 1);
-        this._teardownBody(body);
-    }
-    _teardownBody(body) {
-        for (const collider of body.colliders) {
-            this._detachCollider(collider);
-        }
-        this._bindings.unbind(body);
-        body._markDestroyed();
-    }
-    _removeCollider(collider) {
-        this._detachCollider(collider);
-        collider.body._removeCollider(collider);
-    }
-    _detachCollider(collider) {
-        const index = this._colliders.indexOf(collider);
-        if (index !== -1) {
-            this._colliders.splice(index, 1);
-        }
-        this._backend.removeCollider(collider);
-        collider._markDestroyed();
-    }
-    _assertAlive() {
-        if (this._destroyed) {
-            throw new Error('PhysicsWorld: the world has been destroyed.');
-        }
-    }
-}
+* Overlap left after clamping a bullet at its time of impact (the clamp
+* overshoots the contact by this much along the motion), so the next step's
+* discrete detection forms a real contact and the solver owns resting,
+* friction and events from then on.
+*/
+const ccdEmbed = .05;
+/**
+* Keep a host-supplied blend factor inside `[0, 1]`. A caller's own accumulator
+* can hand over a value outside it (a stale read, a custom scheduler), and an
+* unclamped one extrapolates the node past the simulated state instead of
+* blending between two known ones.
+*/
+const clampAlpha = (alpha) => {
+	if (!(alpha > 0)) return 0;
+	return alpha < 1 ? alpha : 1;
+};
+/**
+* Reject removing the last collider a dynamic body's mass rests on while it still
+* holds others. Such a body keeps colliding but has `invMass === 0`, which the
+* solver cannot tell apart from a static body - the same state `PhysicsBody`
+* refuses to be constructed in.
+*
+* Removing the body's *only* collider is fine: a body with no geometry at all is
+* a body still being assembled, not a silently broken one.
+*/
+const assertBodyKeepsItsMass = (collider) => {
+	const body = collider.body;
+	if (body.type !== "dynamic" || collider.shape.massProperties === null || collider.density <= 0) return;
+	let remaining = 0;
+	for (const other of body.colliders) {
+		if (other === collider) continue;
+		if (other.shape.massProperties !== null && other.density > 0) return;
+		remaining++;
+	}
+	if (remaining === 0) return;
+	throw new Error("PhysicsWorld.destroyCollider: this is the only collider carrying mass for a dynamic body — removing it would leave the body colliding but massless. Destroy the body instead, or give it another solid collider first.");
+};
+/**
+* `true` when a static/kinematic body - an island boundary, never an island
+* member - is being driven this step, either through its velocity or by a
+* {@link PhysicsBody.setTransform} teleport. Speed is deliberately not compared
+* against the sleep thresholds: a platform creeping along at 1 px/s still has to
+* push its passengers, and it is exactly that sub-threshold case where nothing
+* else would keep them awake.
+*/
+const isMovingBoundary = (body) => body._teleported || body.linearVelocityX !== 0 || body.linearVelocityY !== 0 || body.angularVelocity !== 0;
+/**
+* `true` while a contact still carries more overlap than the solver leaves
+* behind at rest. Read from the manifold detection just produced, which is the
+* same separation the solver's push-out bias is about to act on - the sleep gate
+* and the constraint it gates therefore agree by construction.
+*/
+const isUnresolved = (manifold) => {
+	for (let i = 0; i < manifold.pointCount; i++) if ((i === 0 ? manifold.points[0] : manifold.points[1]).penetration > .75) return true;
+	return false;
+};
+/**
+* {@link PhysicsWorld.attach}'s default `position`: `node`'s current WORLD
+* translation, duck-typed the same way `AudioListener` reads a follow target -
+* real {@link SceneNode}s expose `getWorldTransform()`, test doubles that omit
+* it fall back to `(0, 0)` (the previous, surprising default).
+*/
+const worldPositionOf = (node) => {
+	const asNode = node;
+	if (typeof asNode.getWorldTransform === "function") {
+		const world = asNode.getWorldTransform();
+		return {
+			x: world.x,
+			y: world.y
+		};
+	}
+	return {
+		x: 0,
+		y: 0
+	};
+};
+/**
+* {@link PhysicsWorld.attach}'s default `angle` (radians): `node`'s current
+* WORLD rotation, decomposed from `getWorldTransform()`'s linear part
+* (`atan2(-c, a)` - `SceneNode.updateTransform` builds its rotation block as
+* `[[cosθ, sinθ], [-sinθ, cosθ]]`, i.e. `b = sinθ`/`c = -sinθ`, matching the
+* radians ⇄ degrees round-trip `PhysicsBinding.sync` already relies on).
+* Falls back to `0` for a duck-typed node without `getWorldTransform`.
+*/
+const worldAngleOf = (node) => {
+	const asNode = node;
+	if (typeof asNode.getWorldTransform === "function") {
+		const world = asNode.getWorldTransform();
+		return Math.atan2(-world.c, world.a);
+	}
+	return 0;
+};
+/**
+* The collision/query world: owns bodies, colliders, the detection backend,
+* bindings, the query engine and the fixed-step accumulator. Stepped by the
+* caller (commonly from a `Scene.update`), each fixed sub-step it integrates
+* body velocities, runs broad- and narrow-phase detection, solves contacts and
+* integrates positions, then fires immutable contact/sensor events and writes
+* bound node transforms. It holds **no module-level state**, so any number of
+* worlds run in isolation.
+*
+* The dynamics are a native, warm-started **TGS-Soft** solver (Box2D-v3 "soft
+* step"): each fixed step runs detection once, then several sub-steps, each
+* integrating gravity over the sub-step and solving contacts with a soft
+* position bias plus a bias-free relax pass; a 2-point block normal solve
+* propagates stack loads, and restitution is a separate final pass. Decoupling
+* stiffness from the iteration count keeps tall towers stable. The detection
+* backend sits behind an internal seam, so the solver is swappable without
+* touching this public surface.
+*
+* **Operating envelope.** The soft solver trades a little accuracy for
+* robustness, so it has a few documented limits - each stays finite and stable,
+* and each is pinned by a gate in `dynamics.test.ts` or
+* `contact-push-out.test.ts`:
+* - **Resting contacts** settle within a small, fixed tolerance. A face contact
+*   settles at exactly that tolerance; a single-point contact settles slightly
+*   deeper, and that gap grows with acceleration. Very high accelerations
+*   eventually exceed what the push-out can resolve within a step, at which
+*   point the contact holds a slightly deeper resting depth instead of the
+*   tolerance - keep gravity in the range ordinary 2D games use.
+* - **Mass ratio** - contacts between bodies of very different mass degrade
+*   gradually rather than at a fixed ratio. What sets the practical limit is how
+*   thick the supporting geometry is relative to the lighter body, not the ratio
+*   alone: a light body squeezed against a boundary thinner than itself is the
+*   case that fails first, and it fails by sinking through.
+* - **Scale-relative behaviour** - the solver's tolerances are absolute lengths,
+*   so a very small shape sees them as a large fraction of itself, and a very
+*   large one as a negligible one. Keep the shapes of one world within a couple
+*   of orders of magnitude of each other.
+* - **CCD is opt-in and translation-only** - detection runs once per fixed
+*   step, so an ordinary body that crosses more than roughly half a barrier's
+*   total thickness within one step may end up on the wrong side of it, either
+*   passing through or being resolved out of the far face. Flag fast
+*   projectiles with {@link PhysicsBody.isBullet}: each of the body's colliders
+*   is then shape-cast along the step's motion (an exact translation-only sweep
+*   of the full shape, not just the centre) and clamped at the first impact.
+*   Rotation over the step is not swept - a long body spinning fast enough to
+*   sweep past an obstacle within one step can still miss it.
+* - **{@link PhysicsWorldOptions.subStepCount}** - the default `4` is
+*   load-bearing for tall-stack stability; lowering it below `2` visibly
+*   degrades stacking, so do not reduce it for performance.
+* - **Broad phase is a dynamic AABB tree** (`AabbTreeBroadPhase`), stateful
+*   across fixed steps: a collider whose tight AABB stays inside its stored
+*   fat AABB costs nothing to re-sync, and only colliders that actually move
+*   outside their margin trigger a tree update and a local re-query for new
+*   neighbours. Detection still walks every live collider once per step (a
+*   cheap containment check for each), so there is a small linear floor, but
+*   the dominant cost - reinsertion and neighbour discovery - is driven by
+*   how much actually moved, not by the total live collider count; sleeping
+*   bodies skip that dominant cost entirely. Scales to tens of thousands of
+*   simultaneously-live colliders, including dense clusters that would
+*   degrade a sort-and-sweep broad phase; very large or highly dynamic
+*   worlds may still benefit from splitting into several smaller
+*   `PhysicsWorld` instances (e.g. per room/chunk).
+*/
+var PhysicsWorld = class {
+	/** Fires when two solid colliders begin touching. Argument is an immutable snapshot. */
+	onCollisionStart = new Signal();
+	/** Fires when two solid colliders stop touching (or one is destroyed). */
+	onCollisionEnd = new Signal();
+	/** Fires when a collider enters a sensor. */
+	onSensorEnter = new Signal();
+	/** Fires when a collider leaves a sensor. */
+	onSensorExit = new Signal();
+	/** World gravity (px/s², +Y down). Integrated each sub-step. */
+	gravity;
+	/** The fixed-step accumulator. */
+	timeStepper;
+	/** TGS-Soft sub-steps per fixed step. */
+	subStepCount;
+	/** Soft-contact stiffness in Hz. */
+	contactHertz;
+	/** Soft-contact damping ratio. */
+	dampingRatio;
+	/** Whether resting bodies are put to sleep. */
+	enableSleeping;
+	/** Linear sleep threshold (px/s). */
+	sleepLinearVelocity;
+	/** Angular sleep threshold (rad/s). */
+	sleepAngularVelocity;
+	/** Seconds below the thresholds before a body sleeps. */
+	timeToSleep;
+	/**
+	* Runs once per solid contact per fixed step, after contact generation and
+	* before island building and the solver, so a contact it disables applies no
+	* impulse and does not couple its two bodies into one sleeping island.
+	*
+	* At most one modifier per world - it mutates simulation state, so a
+	* multi-listener signal would make the outcome depend on registration order.
+	* Set to `null` to remove it; the per-contact values then stay at the
+	* defaults derived from the two colliders.
+	*/
+	contactModifier;
+	/**
+	* Whether bound nodes are placed between the last two fixed states rather than
+	* snapped to the latest one. Toggleable at runtime; switching it off snaps
+	* every bound node back to the current fixed state on the next sync.
+	*/
+	interpolation;
+	/**
+	* Supplies the `[0, 1)` blend factor for interpolated bindings. Defaults to
+	* this world's own accumulator; point it at the host's own fraction
+	* (`() => app.frameAlpha`) when the world runs as a `System`, because
+	* {@link fixedUpdate} never advances the local accumulator.
+	*/
+	frameAlphaSource;
+	_backend = new NativePhysicsBackend();
+	_bodies = [];
+	_colliders = [];
+	/**
+	* What detection actually runs over: the authored colliders, with a chain
+	* replaced by the edge proxies it fans out into. The broad phase, the narrow
+	* phase and the queries all read this list; `_colliders` stays the authored
+	* set every public surface reports.
+	*/
+	_detectionColliders = [];
+	/** Pooled scratch for re-syncing a single body's broad-phase leaves. */
+	_leafScratch = [];
+	_joints = [];
+	_bindings = new BindingRegistry();
+	_query;
+	_commands = [];
+	/** Pooled union-find parent array for the per-step island pass (reused; sized to the body count). */
+	_islandParent = [];
+	/** Pooled per-island minimum sleep time, indexed by union-find root. */
+	_islandMinSleep = [];
+	/** Pooled scratch for the CCD pass (clamp target, per-pair sweep hit, best hit, swept AABB) - keeps the sweep allocation-free. */
+	_ccdClampPosition = {
+		x: 0,
+		y: 0
+	};
+	_ccdSweepHit = {
+		t: 0,
+		normalX: 0,
+		normalY: 0
+	};
+	_ccdBestHit = {
+		t: 0,
+		normalX: 0,
+		normalY: 0
+	};
+	_ccdSweptAabb = createAabb();
+	/** Pooled result buffer for the CCD pass's broad-phase query (refilled per bullet collider). */
+	_ccdCandidates = [];
+	/**
+	* Narrow-phase sweep tests run by the CCD pass since world creation. Pairs
+	* rejected by the swept-AABB prune never count, so slow bullets far from any
+	* geometry keep this at zero (the cheap path).
+	*
+	* @internal - test/diagnostic hook.
+	*/
+	_ccdSweepTests = 0;
+	/**
+	* Colliders the CCD pass pulled out of the broad phase since world creation -
+	* the size of the candidate set the swept-AABB prune and the narrow-phase
+	* sweep then work on. Counted separately from {@link _ccdSweepTests} because
+	* the two measure different halves: this is what the pass looks at, that is
+	* what it actually sweeps. Stays proportional to the geometry near the
+	* bullets, not to the world's collider count.
+	*
+	* @internal - test/diagnostic hook.
+	*/
+	_ccdBroadPhaseCandidates = 0;
+	_nextBodyId = 1;
+	_nextColliderId = 1;
+	_dispatching = false;
+	_destroyed = false;
+	constructor(options = {}) {
+		this.gravity = new Vector(options.gravity?.x ?? 0, options.gravity?.y ?? 0);
+		this.timeStepper = new TimeStepper({
+			...options.fixedDelta !== void 0 && { fixedDelta: options.fixedDelta },
+			...options.maxSubSteps !== void 0 && { maxSubSteps: options.maxSubSteps }
+		});
+		const subStepCount = options.subStepCount ?? 4;
+		if (!Number.isInteger(subStepCount) || subStepCount < 1) throw new RangeError(`PhysicsWorld: subStepCount must be an integer ≥ 1, received ${subStepCount}.`);
+		this.subStepCount = subStepCount;
+		this.contactHertz = options.contactHertz ?? 30;
+		this.dampingRatio = options.dampingRatio ?? 10;
+		this.enableSleeping = options.enableSleeping ?? true;
+		this.sleepLinearVelocity = options.sleepLinearVelocity ?? 5;
+		this.sleepAngularVelocity = options.sleepAngularVelocity ?? .06;
+		this.timeToSleep = options.timeToSleep ?? .5;
+		this.contactModifier = options.contactModifier ?? null;
+		this.interpolation = options.interpolation ?? false;
+		this.frameAlphaSource = options.frameAlphaSource ?? (() => this.timeStepper.alpha);
+		this._query = new QueryEngine(this._detectionColliders, this._backend.spatialIndex);
+	}
+	/** Live bodies (read-only view). */
+	get bodies() {
+		return this._bodies;
+	}
+	/** Live colliders (read-only view). */
+	get colliders() {
+		return this._colliders;
+	}
+	/**
+	* @internal - the geometry the broad phase and the narrow phase actually hold:
+	* every authored collider, with a chain replaced by its per-edge proxies.
+	* Consumed by the debug draw layer, which visualises what the solver sees;
+	* public identity stays {@link colliders}.
+	*/
+	get detectionGeometry() {
+		return this._detectionColliders;
+	}
+	/**
+	* Add a body to the world: allocates the body and its collider ids, registers
+	* the colliders, computes the mass model and tracks the body for stepping.
+	* Construct the body freely first (`new PhysicsBody({ ... })`), then add it.
+	* Safe to call inside an event callback - the body push is deferred to the end
+	* of the step, exactly like collider registration. Returns the body.
+	*
+	* @throws if the body has already been added to a world.
+	*/
+	add(body) {
+		this._assertAlive();
+		if (body.attached) throw new Error("PhysicsWorld.add: this body has already been added to a world.");
+		body._attachToWorld(this, this._nextBodyId++);
+		this._defer(() => {
+			if (!body.destroyed) this._bodies.push(body);
+		});
+		return body;
+	}
+	/**
+	* Convenience: create a body carrying a single collider, add it to the world
+	* and bind it to `node` in one call. The node tracks `body.position` after each
+	* step. Returns the body. Equivalent to `new PhysicsBody(...)` + `add` + `bind`.
+	*
+	* When `options.position`/`options.angle` are omitted, the body starts at
+	* `node`'s current WORLD position/rotation (via `getWorldTransform()`,
+	* composed through any transform-group boundary) rather than `(0, 0)` -
+	* otherwise a body attached to an already-placed node would visibly "teleport"
+	* to the origin on the next step. Pass `position`/`angle` explicitly to override.
+	*/
+	attach(node, options) {
+		const body = new PhysicsBody({
+			...options.type !== void 0 && { type: options.type },
+			position: options.position ?? worldPositionOf(node),
+			angle: options.angle ?? worldAngleOf(node),
+			...options.gravityScale !== void 0 && { gravityScale: options.gravityScale },
+			...options.fixedRotation !== void 0 && { fixedRotation: options.fixedRotation },
+			colliders: [new Collider({
+				shape: options.shape,
+				...options.offset !== void 0 && { offset: options.offset },
+				...options.rotation !== void 0 && { rotation: options.rotation },
+				...options.density !== void 0 && { density: options.density },
+				...options.friction !== void 0 && { friction: options.friction },
+				...options.restitution !== void 0 && { restitution: options.restitution },
+				...options.isSensor !== void 0 && { isSensor: options.isSensor },
+				...options.filter !== void 0 && { filter: options.filter }
+			})]
+		});
+		this.add(body);
+		this.bind(body, node);
+		return body;
+	}
+	/**
+	* Destroy a body and its colliders. Every dynamic body touching it is woken,
+	* so anything that was resting on the destroyed body falls once its support is
+	* gone. Deferred when called inside a callback.
+	*/
+	destroyBody(body) {
+		this._defer(() => this._removeBody(body));
+	}
+	/**
+	* Destroy a single collider, recomputing its body's mass. Wakes every dynamic
+	* body touching it, the same way {@link destroyBody} does. Deferred when
+	* called inside a callback.
+	*/
+	destroyCollider(collider) {
+		assertBodyKeepsItsMass(collider);
+		this._defer(() => this._removeCollider(collider));
+	}
+	/** Live joints (read-only view). */
+	get joints() {
+		return this._joints;
+	}
+	/**
+	* Add a constraint joint. Construct it first (`new DistanceJoint({ ... })`),
+	* then add it. Wakes both bodies; safe inside a callback (registration is
+	* deferred). Returns the joint.
+	*/
+	addJoint(joint) {
+		this._assertAlive();
+		joint.bodyA.wake();
+		joint.bodyB.wake();
+		this._defer(() => {
+			if (!this._joints.includes(joint)) this._joints.push(joint);
+		});
+		return joint;
+	}
+	/** Remove a joint, waking both bodies so they respond to the lost constraint. Deferred when called inside a callback. */
+	removeJoint(joint) {
+		joint.bodyA.wake();
+		joint.bodyB.wake();
+		this._defer(() => {
+			const index = this._joints.indexOf(joint);
+			if (index !== -1) this._joints.splice(index, 1);
+		});
+	}
+	/**
+	* Advance the world by `frameDeltaSeconds`. Accumulates into fixed steps; each
+	* fixed step runs detection once, then a TGS-Soft sub-step loop (integrate
+	* gravity, solve contacts with a soft bias, integrate positions, relax) and a
+	* restitution pass, then writes the accumulated motion into each body. Finally
+	* dispatches events and writes bound node transforms.
+	*
+	* **Prefer registering the world as a system instead**
+	* (`app.systems.add(world, { order: SystemOrder.Physics })` or the scene
+	* equivalent) so {@link fixedUpdate} drives stepping directly from the
+	* engine's own fixed-timestep scheduler - one call per fixed step, no
+	* accumulator duplication. `step` remains available here for manual/advanced
+	* driving (e.g. a fixed-but-non-standard rate, or stepping outside the
+	* normal frame loop entirely): pass any delta and this accumulator converts
+	* it into the right number of fixed sub-steps (0, 1, or several, clamped by
+	* {@link PhysicsWorldOptions.maxSubSteps}).
+	*
+	* Either way the simulation is frame-rate independent and deterministic -
+	* the same sequence of deltas replays identically. `timeStepper.alpha`
+	* (`[0, 1)`) is the leftover sub-step fraction after this call, for callers
+	* that want to interpolate a bound node's rendered position between the last
+	* two fixed states instead of snapping to the latest one (bindings do not do
+	* this automatically - {@link bind} always writes the latest fixed-step
+	* transform verbatim).
+	*/
+	step(frameDeltaSeconds) {
+		this._assertAlive();
+		const steps = this.timeStepper.advance(frameDeltaSeconds);
+		if (steps > 0) {
+			const subStepCount = this.subStepCount;
+			const h = this.timeStepper.fixedDelta / subStepCount;
+			const gravityX = this.gravity.x;
+			const gravityY = this.gravity.y;
+			const contactHertz = this.contactHertz;
+			const dampingRatio = this.dampingRatio;
+			const hasJoints = this._joints.length > 0;
+			const hasBullets = this._hasBullets();
+			for (let step = 0; step < steps; step++) this._stepOnce(h, subStepCount, gravityX, gravityY, contactHertz, dampingRatio, hasJoints, hasBullets);
+			this._dispatchEvents();
+		}
+		this._syncBindings();
+		this._drainCommands();
+	}
+	/**
+	* Advance by exactly one fixed step, driven directly by the engine's own
+	* fixed-timestep scheduler when this world is registered as a `System`
+	* (`app.systems.add(world, { order: SystemOrder.Physics })` or the scene
+	* equivalent) - bypasses {@link timeStepper}'s variable-delta accumulator
+	* entirely, since the caller has already decided exactly when a fixed step
+	* occurs. Prefer this over manual {@link step} once the world is
+	* system-registered; `step` remains available for advanced manual driving.
+	* Always advances by exactly {@link timeStepper}'s configured `fixedDelta`,
+	* regardless of the caller's actual fixed-step interval - if the engine's
+	* `Application.fixedTimeStep` doesn't match this world's `fixedDelta`, the
+	* simulation stays deterministic but runs at the wrong wall-clock speed
+	* relative to real time.
+	*/
+	fixedUpdate(_step) {
+		this._assertAlive();
+		const subStepCount = this.subStepCount;
+		const h = this.timeStepper.fixedDelta / subStepCount;
+		this._stepOnce(h, subStepCount, this.gravity.x, this.gravity.y, this.contactHertz, this.dampingRatio, this._joints.length > 0, this._hasBullets());
+		this._dispatchEvents();
+		if (!this.interpolation) this._bindings.sync();
+		this._drainCommands();
+	}
+	/**
+	* Variable-rate `System` phase: places bound nodes for the frame that is about
+	* to be drawn. Only does work while {@link interpolation} is on - otherwise
+	* {@link fixedUpdate} has already snapped them to the latest fixed state.
+	*/
+	update(_delta) {
+		this._assertAlive();
+		if (this.interpolation) this._bindings.syncInterpolated(clampAlpha(this.frameAlphaSource()));
+	}
+	/** Present bound nodes, snapping or interpolating according to {@link interpolation}. */
+	_syncBindings() {
+		if (this.interpolation) this._bindings.syncInterpolated(clampAlpha(this.frameAlphaSource()));
+		else this._bindings.sync();
+	}
+	_stepOnce(h, subStepCount, gravityX, gravityY, contactHertz, dampingRatio, hasJoints, hasBullets) {
+		this._backend.detect(this._detectionColliders);
+		if (this.contactModifier !== null) this._backend.applyContactModifier(this.contactModifier);
+		if (this.enableSleeping) this._updateSleeping(this.timeStepper.fixedDelta);
+		this._backend.prepareSolve(h, contactHertz, dampingRatio);
+		if (hasJoints) this._prepareJoints(h);
+		if (hasBullets) this._recordBulletPositions();
+		for (let subStep = 0; subStep < subStepCount; subStep++) {
+			for (const body of this._bodies) body._integrateVelocity(h, gravityX, gravityY);
+			this._backend.warmStart();
+			if (hasJoints) this._warmStartJoints();
+			this._backend.solveVelocities(true);
+			if (hasJoints) this._solveJoints(true);
+			for (const body of this._bodies) body._integratePosition(h);
+			this._backend.solveVelocities(false);
+			if (hasJoints) this._solveJoints(false);
+		}
+		this._backend.applyRestitution();
+		for (const body of this._bodies) body._finalizePosition();
+		if (hasBullets) this._advanceBullets();
+	}
+	/**
+	* Link a body to a scene node; the node tracks the body after each step.
+	* Destroying the node is enough to end the link - the next step drops it
+	* rather than writing into the node's released transform, so an explicit
+	* {@link unbind} is only needed to stop tracking a node that stays alive.
+	*
+	* @throws if `node` is already destroyed.
+	*/
+	bind(body, node) {
+		return this._bindings.bind(body, node);
+	}
+	/** Remove a body↔node link. */
+	unbind(body) {
+		this._bindings.unbind(body);
+	}
+	/** Colliders containing `point`. Fresh array. */
+	queryPoint(point, filter) {
+		return this._query.queryPoint(point, filter);
+	}
+	/** Colliders whose AABB overlaps `bounds`. Writes into `out` (cleared) if given. */
+	queryAabb(bounds, filter, out) {
+		return this._query.queryAabb(bounds, filter, out);
+	}
+	/** Invoke `callback` for each collider whose AABB overlaps `bounds`. Allocation-free. */
+	forEachAabbHit(bounds, filter, callback) {
+		this._query.forEachAabbHit(bounds, filter, callback);
+	}
+	/** Nearest collider hit by the ray, or `null`. */
+	rayCast(origin, direction, filter, maxDistance) {
+		return this._query.rayCast(origin, direction, filter, maxDistance);
+	}
+	/** All collider hits along the ray, sorted by distance. Writes into `out` (cleared) if given. */
+	rayCastAll(origin, direction, filter, out, maxDistance) {
+		return this._query.rayCastAll(origin, direction, filter, out, maxDistance);
+	}
+	/** Colliders overlapping `shape` placed at `position`/`angle`. Fresh array. */
+	overlapShape(shape, position, filter, angle) {
+		return this._query.overlapShape(shape, position, filter, angle);
+	}
+	/** Release every body, collider, binding and backend resource. */
+	destroy() {
+		if (this._destroyed) return;
+		this._destroyed = true;
+		for (const body of this._bodies) {
+			for (const collider of body.colliders) collider._markDestroyed();
+			body._markDestroyed();
+		}
+		this._bodies.length = 0;
+		this._colliders.length = 0;
+		this._detectionColliders.length = 0;
+		this._joints.length = 0;
+		this._commands.length = 0;
+		this._bindings.clear();
+		this._backend.destroy();
+		this.onCollisionStart.destroy();
+		this.onCollisionEnd.destroy();
+		this.onSensorEnter.destroy();
+		this.onSensorExit.destroy();
+	}
+	_allocateColliderId() {
+		return this._nextColliderId++;
+	}
+	_registerCollider(collider) {
+		this._defer(() => {
+			if (collider.destroyed) return;
+			this._colliders.push(collider);
+			const edges = collider.chainEdges;
+			if (edges === null) {
+				this._detectionColliders.push(collider);
+				return;
+			}
+			for (const edge of edges) this._detectionColliders.push(edge);
+		});
+	}
+	/** The detection backend (internal; consumed by the debug draw layer). */
+	get backend() {
+		return this._backend;
+	}
+	_dispatchEvents() {
+		const graph = this._backend.contactGraph;
+		this._dispatching = true;
+		for (const event of graph.collisionEnd) this.onCollisionEnd.dispatch(event);
+		for (const event of graph.sensorExit) this.onSensorExit.dispatch(event);
+		for (const event of graph.collisionStart) this.onCollisionStart.dispatch(event);
+		for (const event of graph.sensorEnter) this.onSensorEnter.dispatch(event);
+		this._dispatching = false;
+	}
+	/**
+	* Accumulate per-body sleep timers and put/keep islands of resting bodies
+	* asleep so a stack sleeps and wakes as one unit. An island is a connected
+	* component of dynamic bodies joined by touching solid contacts (static and
+	* kinematic bodies are boundaries, not nodes); it sleeps once every member has
+	* stayed below the sleep thresholds for `timeToSleep`, and wakes the instant
+	* any member does (e.g. an awake body merges into it via a new contact).
+	* A boundary that is itself moving resets the sleep timer of every dynamic
+	* body it touches, so a platform keeps its passengers awake however slowly it
+	* travels; so does a contact still carrying more penetration than the solver
+	* leaves at rest, because the push-out that resolves it is slower than the
+	* sleep velocity threshold and a body would otherwise be frozen embedded.
+	* Deterministic: union-find roots break ties by lower index and the contact
+	* set is id-sorted.
+	*/
+	_updateSleeping(dt) {
+		const bodies = this._bodies;
+		const count = bodies.length;
+		const parent = this._islandParent;
+		const minSleep = this._islandMinSleep;
+		for (let i = 0; i < count; i++) {
+			const body = bodies[i];
+			body._islandIndex = i;
+			parent[i] = i;
+			minSleep[i] = Infinity;
+			if (body.type === "dynamic" && !body.isSleeping) body._accumulateSleepTime(dt, this.sleepLinearVelocity, this.sleepAngularVelocity);
+		}
+		parent.length = count;
+		minSleep.length = count;
+		this._unionContactIslands();
+		for (const joint of this._joints) {
+			const bodyA = joint.bodyA;
+			const bodyB = joint.bodyB;
+			if (joint.enabled && bodyA.type === "dynamic" && bodyB.type === "dynamic") this._union(bodyA._islandIndex, bodyB._islandIndex);
+		}
+		for (let i = 0; i < count; i++) {
+			const body = bodies[i];
+			if (body.type === "dynamic") {
+				const root = this._find(i);
+				if (body._sleepTime < minSleep[root]) minSleep[root] = body._sleepTime;
+			}
+		}
+		const timeToSleep = this.timeToSleep;
+		for (let i = 0; i < count; i++) {
+			const body = bodies[i];
+			if (body.type === "dynamic") body._setSleeping(minSleep[this._find(i)] >= timeToSleep);
+		}
+	}
+	/**
+	* Union dynamic↔dynamic solid contacts into islands. A dynamic body touching a
+	* MOVING static/kinematic body has its sleep timer reset instead: those types
+	* are island boundaries, not members, so nothing else would keep the passenger
+	* of a slow-moving platform awake - and the solver skips a contact whose
+	* dynamic side is asleep, letting the platform drive straight through it.
+	*
+	* The same traversal resets the sleep timer of both sides of a contact whose
+	* penetration the solver has not worked off yet, so the island it belongs to
+	* stays awake until the overlap is within the tolerance the solver itself
+	* converges to.
+	*/
+	_unionContactIslands() {
+		for (const contact of this._backend.contactGraph.solidContacts) {
+			if (!contact.enabled) continue;
+			const bodyA = contact.a.body;
+			const bodyB = contact.b.body;
+			const dynamicA = bodyA.type === "dynamic";
+			const dynamicB = bodyB.type === "dynamic";
+			if (dynamicA && dynamicB) this._union(bodyA._islandIndex, bodyB._islandIndex);
+			else if (dynamicA && isMovingBoundary(bodyB)) bodyA._sleepTime = 0;
+			else if (dynamicB && isMovingBoundary(bodyA)) bodyB._sleepTime = 0;
+			if ((dynamicA || dynamicB) && isUnresolved(contact.manifold)) {
+				if (dynamicA) bodyA._sleepTime = 0;
+				if (dynamicB) bodyB._sleepTime = 0;
+			}
+		}
+	}
+	/** Union-find union by lower index (deterministic roots). */
+	_union(a, b) {
+		const rootA = this._find(a);
+		const rootB = this._find(b);
+		if (rootA < rootB) this._islandParent[rootB] = rootA;
+		else if (rootB < rootA) this._islandParent[rootA] = rootB;
+	}
+	/** Union-find find with path halving. */
+	_find(index) {
+		const parent = this._islandParent;
+		while (parent[index] !== index) {
+			const grandparent = parent[parent[index]];
+			parent[index] = grandparent;
+			index = grandparent;
+		}
+		return index;
+	}
+	/** Build each joint's per-frame constraint data (once per fixed step). */
+	_prepareJoints(h) {
+		for (const joint of this._joints) joint._prepare(h);
+	}
+	/** Re-apply each joint's accumulated impulse (each sub-step). */
+	_warmStartJoints() {
+		for (const joint of this._joints) joint._warmStart();
+	}
+	/** One joint velocity pass (each sub-step, after the contacts). */
+	_solveJoints(useBias) {
+		for (const joint of this._joints) joint._solve(useBias);
+	}
+	/** Whether any dynamic body is flagged for continuous collision (bullet mode). */
+	_hasBullets() {
+		for (const body of this._bodies) if (body.isBullet && body.type === "dynamic") return true;
+		return false;
+	}
+	/** Snapshot each bullet's centre of mass at the start of the fixed step (the swept-test origin). */
+	_recordBulletPositions() {
+		for (const body of this._bodies) if (body.isBullet && body.type === "dynamic") {
+			body._ccdPrevX = body.worldCenterOfMassX;
+			body._ccdPrevY = body.worldCenterOfMassY;
+		}
+	}
+	/**
+	* Shape-cast each bullet's colliders along this fixed step's motion against
+	* every other body's colliders; if any would cross one, clamp the body at the
+	* earliest impact and resolve it about the surface normal (a slide for a
+	* non-bouncy body, an elastic reflection as restitution → 1) so it cannot
+	* tunnel. The sweep is an exact translation-only cast of the full shapes
+	* (Minkowski ray for circles, swept SAT for polygon pairs) - the step's
+	* rotation is applied before the sweep, not swept through. Pairs already
+	* overlapping at the start of the step are skipped: the discrete solver owns
+	* them (that hand-off is what lets a landed bullet rest on real contacts).
+	* Filters and sensors behave exactly as in the discrete narrow phase.
+	*/
+	_advanceBullets() {
+		this._backend.spatialIndex?.sync(this._colliders);
+		for (const body of this._bodies) {
+			if (!body.isBullet || body.type !== "dynamic" || body.isSleeping) continue;
+			const newX = body.worldCenterOfMassX;
+			const newY = body.worldCenterOfMassY;
+			const dx = newX - body._ccdPrevX;
+			const dy = newY - body._ccdPrevY;
+			const distance = Math.hypot(dx, dy);
+			if (distance < 1e-6) continue;
+			const blocked = this._sweepBulletColliders(body, dx, dy);
+			if (blocked === null) continue;
+			const best = this._ccdBestHit;
+			const clampDistance = Math.min(distance, best.t * distance + ccdEmbed);
+			if (clampDistance < distance) {
+				const pullBack = (clampDistance - distance) / distance;
+				this._ccdClampPosition.x = body.x + dx * pullBack;
+				this._ccdClampPosition.y = body.y + dy * pullBack;
+				body.setTransform(this._ccdClampPosition, body.angle);
+				this._backend.spatialIndex?.sync(this._detectionLeavesOf(body));
+			}
+			const vn = body.linearVelocityX * best.normalX + body.linearVelocityY * best.normalY;
+			if (vn < 0) {
+				const impulse = -(1 + (vn < -1 ? Math.max(this._bulletRestitution(body), blocked.restitution) : 0)) * vn;
+				body.linearVelocityX += impulse * best.normalX;
+				body.linearVelocityY += impulse * best.normalY;
+			}
+		}
+	}
+	/**
+	* Find the earliest impact for a bullet whose colliders translated by
+	* `(dx, dy)` this step. Each of the bullet's colliders queries the broad
+	* phase with its swept AABB, so the pass costs what the geometry around the
+	* bullet's path costs - not one iteration per collider in the world. Returns
+	* the blocking collider (with the impact written into {@link _ccdBestHit}),
+	* or `null` when nothing blocks the motion.
+	*/
+	_sweepBulletColliders(body, dx, dy) {
+		const hit = this._ccdSweepHit;
+		const best = this._ccdBestHit;
+		const swept = this._ccdSweptAabb;
+		const spatialIndex = this._backend.spatialIndex;
+		let blocked = null;
+		best.t = Infinity;
+		for (const collider of body.colliders) {
+			if (collider.isSensor) continue;
+			const aabb = collider.aabb;
+			swept.minX = dx > 0 ? aabb.minX - dx : aabb.minX;
+			swept.maxX = dx < 0 ? aabb.maxX - dx : aabb.maxX;
+			swept.minY = dy > 0 ? aabb.minY - dy : aabb.minY;
+			swept.maxY = dy < 0 ? aabb.maxY - dy : aabb.maxY;
+			const candidates = spatialIndex === void 0 ? this._detectionColliders : spatialIndex.queryAabb(swept, this._ccdCandidates);
+			this._ccdBroadPhaseCandidates += candidates.length;
+			for (const other of candidates) {
+				const target = authoredCollider(other);
+				if (target.isSensor || other.body === body || !shouldCollide(collider.filter, target.filter)) continue;
+				if (!aabbOverlap(swept, other.aabb)) continue;
+				this._ccdSweepTests++;
+				if (sweepProxies(collider, dx, dy, other, hit) && hit.t < best.t) {
+					best.t = hit.t;
+					best.normalX = hit.normalX;
+					best.normalY = hit.normalY;
+					blocked = target;
+				}
+			}
+		}
+		return blocked;
+	}
+	/** The highest restitution among a body's colliders (its CCD bounce factor). */
+	_bulletRestitution(body) {
+		let restitution = 0;
+		for (const collider of body.colliders) if (collider.restitution > restitution) restitution = collider.restitution;
+		return restitution;
+	}
+	/** Run `command` now, or queue it when inside an event dispatch (deferred to end of step). */
+	_defer(command) {
+		if (this._dispatching) this._commands.push(command);
+		else command();
+	}
+	_drainCommands() {
+		if (this._commands.length === 0) return;
+		const commands = this._commands.splice(0);
+		for (const command of commands) command();
+	}
+	_removeBody(body) {
+		const index = this._bodies.indexOf(body);
+		if (index === -1) {
+			this._teardownBody(body);
+			return;
+		}
+		this._bodies.splice(index, 1);
+		this._teardownBody(body);
+	}
+	_teardownBody(body) {
+		for (const collider of body.colliders) this._detachCollider(collider);
+		this._bindings.unbind(body);
+		body._markDestroyed();
+	}
+	_removeCollider(collider) {
+		this._detachCollider(collider);
+		collider.body._removeCollider(collider);
+	}
+	_detachCollider(collider) {
+		const index = this._colliders.indexOf(collider);
+		if (index !== -1) this._colliders.splice(index, 1);
+		this._wakeTouchingBodies(collider);
+		const edges = collider.chainEdges;
+		if (edges === null) this._removeDetectionCollider(collider);
+		else for (const edge of edges) this._removeDetectionCollider(edge);
+		collider._markDestroyed();
+	}
+	/** Drop one broad-phase leaf: an authored collider, or one chain edge proxy. */
+	_removeDetectionCollider(collider) {
+		const index = this._detectionColliders.indexOf(collider);
+		if (index !== -1) this._detectionColliders.splice(index, 1);
+		this._backend.removeCollider(collider);
+	}
+	/**
+	* The broad-phase leaves of one body - its colliders, with a chain replaced by
+	* its edge proxies. Returns pooled scratch, valid until the next call.
+	*/
+	_detectionLeavesOf(body) {
+		const leaves = this._leafScratch;
+		leaves.length = 0;
+		for (const collider of body.colliders) {
+			const edges = collider.chainEdges;
+			if (edges === null) {
+				leaves.push(collider);
+				continue;
+			}
+			for (const edge of edges) leaves.push(edge);
+		}
+		return leaves;
+	}
+	/**
+	* Wake every dynamic body still touching `collider` at the moment it leaves
+	* the world. A sleeping body's sleep timer is frozen, so the island pass alone
+	* can never re-open its sleep decision: losing the support it rested on just
+	* removes a contact, and the island (now smaller, or a lone body) still reports
+	* a long-expired timer and is put straight back to sleep - a stack whose floor,
+	* platform or bottom box is destroyed would hang in mid-air forever. Kinematic
+	* and static supports are the sharp edge, since they are island boundaries
+	* rather than nodes and so are invisible to wake propagation, but the same hole
+	* exists for a dynamic support. Waking the far side of each contact is enough:
+	* the woken body's reset timer propagates through the rest of its sleeping
+	* island on the next step, exactly like any other wake event.
+	*/
+	_wakeTouchingBodies(collider) {
+		for (const contact of this._backend.contactGraph.solidContacts) {
+			let other;
+			if (contact.ownerA === collider) other = contact.ownerB;
+			else if (contact.ownerB === collider) other = contact.ownerA;
+			else continue;
+			if (other.body.type === "dynamic") other.body.wake();
+		}
+	}
+	_assertAlive() {
+		if (this._destroyed) throw new Error("PhysicsWorld: the world has been destroyed.");
+	}
+};
 
+//#endregion
 export { PhysicsWorld };
-//# sourceMappingURL=PhysicsWorld.js.map
+//# sourceMappingURL=PhysicsWorld.js.map