@driftengine/physics 3.61.0

package/dist/pairs.d.ts

@@ -0,0 +1,62 @@
+import type { BodySet } from './bodies.ts';
+import { DynamicTree } from './tree.ts';
+/**
+ * Candidate body pairs, ordered by body index and never by tree shape.
+ *
+ * **This is the file that makes the broadphase safe to change.** A dynamic tree's shape depends on
+ * the order proxies were inserted in, and its traversal order depends on its shape — so a pair list
+ * taken straight from the tree carries insertion history in it. Sequential impulses are
+ * order-dependent, so that history would reach the simulation's *result*, and a scene rebuilt in a
+ * different order would diverge while looking identical.
+ *
+ * So every pair is packed into one 32-bit key as `min * 2^16 + max`, radix-sorted, and nothing
+ * downstream ever learns there was a tree. **What this costs** is a two-pass sort over preallocated
+ * scratch each tick. **What would make it wrong** is more than 65,536 bodies, which the key cannot
+ * express; `MAX_BODIES` names that and the builder refuses past it rather than aliasing two pairs
+ * onto one key.
+ */
+/** The key packs two indices into 32 bits, so neither may reach this. */
+export declare const MAX_BODIES: number;
+export declare class PairSet {
+    /** Packed `(min, max)` keys, sorted ascending. Read `count` of them. */
+    keys: Uint32Array;
+    count: number;
+    private scratch;
+    private histogram;
+    private hits;
+    private queryBox;
+    constructor(capacity?: number);
+    /**
+     * Collect every candidate pair among the tree's proxies, sorted.
+     *
+     * `leafOf` maps a body index to its tree leaf, because a query answers with proxy ids and the
+     * tree needs the leaf to read a body's stored bounds back.
+     */
+    build(bodies: BodySet, tree: DynamicTree, leafOf: Int32Array, ignored?: ReadonlySet<number> | null): number;
+    private push;
+    /**
+     * Four passes of an 8-bit radix sort, which is stable and touches no comparator.
+     *
+     * A comparison sort would also be deterministic, and this is here for the hot path rather than
+     * for correctness: the pair list is rebuilt every tick and is the one array whose length grows
+     * with the square of local density.
+     */
+    private sort;
+}
+/** The 32-layer mask, both ways. A pair layersInteract only if each side admits the other. */
+export declare function layersInteract(bodies: BodySet, a: number, b: number): boolean;
+/**
+ * The key a pair of bodies is stored under, in either order.
+ *
+ * **Two bodies that must never collide cannot always be said with layers.** The mask is a property
+ * of each body on its own, so it can express "this kind does not meet that kind" and cannot express
+ * "these two in particular" — and a ragdoll is entirely the second thing: every bone overlaps the
+ * one it hangs from, because that is what having a radius means, while the same two *kinds* of bone
+ * elsewhere in the body must still collide. A consumer that tried it with layers spent a bit per
+ * bone and most of the 32 on one doll.
+ */
+export declare function pairKey(a: number, b: number): number;
+/** Unpack a key's lower body index. */
+export declare function pairA(key: number): number;
+/** Unpack a key's higher body index. */
+export declare function pairB(key: number): number;

package/dist/pairs.js

@@ -0,0 +1,154 @@
+import { BODY_STATIC } from './bodies.js';
+import { DynamicTree } from './tree.js';
+/**
+ * Candidate body pairs, ordered by body index and never by tree shape.
+ *
+ * **This is the file that makes the broadphase safe to change.** A dynamic tree's shape depends on
+ * the order proxies were inserted in, and its traversal order depends on its shape — so a pair list
+ * taken straight from the tree carries insertion history in it. Sequential impulses are
+ * order-dependent, so that history would reach the simulation's *result*, and a scene rebuilt in a
+ * different order would diverge while looking identical.
+ *
+ * So every pair is packed into one 32-bit key as `min * 2^16 + max`, radix-sorted, and nothing
+ * downstream ever learns there was a tree. **What this costs** is a two-pass sort over preallocated
+ * scratch each tick. **What would make it wrong** is more than 65,536 bodies, which the key cannot
+ * express; `MAX_BODIES` names that and the builder refuses past it rather than aliasing two pairs
+ * onto one key.
+ */
+/** The key packs two indices into 32 bits, so neither may reach this. */
+export const MAX_BODIES = 1 << 16;
+export class PairSet {
+    /** Packed `(min, max)` keys, sorted ascending. Read `count` of them. */
+    keys;
+    count = 0;
+    scratch;
+    histogram = new Uint32Array(256);
+    hits;
+    queryBox = { minX: 0, minY: 0, minZ: 0, maxX: 0, maxY: 0, maxZ: 0 };
+    constructor(capacity = 256) {
+        this.keys = new Uint32Array(capacity);
+        this.scratch = new Uint32Array(capacity);
+        this.hits = new Int32Array(256);
+    }
+    /**
+     * Collect every candidate pair among the tree's proxies, sorted.
+     *
+     * `leafOf` maps a body index to its tree leaf, because a query answers with proxy ids and the
+     * tree needs the leaf to read a body's stored bounds back.
+     */
+    build(bodies, tree, leafOf, ignored = null) {
+        this.count = 0;
+        if (bodies.count >= MAX_BODIES) {
+            throw new Error(`PairSet: ${bodies.count} bodies exceeds the ${MAX_BODIES} a pair key holds`);
+        }
+        for (let a = 0; a < bodies.count; a++) {
+            const leaf = leafOf[a] ?? -1;
+            if (leaf < 0)
+                continue;
+            const at = leaf * 6;
+            this.queryBox.minX = tree.bounds[at] ?? 0;
+            this.queryBox.minY = tree.bounds[at + 1] ?? 0;
+            this.queryBox.minZ = tree.bounds[at + 2] ?? 0;
+            this.queryBox.maxX = tree.bounds[at + 3] ?? 0;
+            this.queryBox.maxY = tree.bounds[at + 4] ?? 0;
+            this.queryBox.maxZ = tree.bounds[at + 5] ?? 0;
+            let found = tree.query(this.queryBox, this.hits);
+            while (found === this.hits.length) {
+                // The query truncated, so it cannot be trusted to have reported everything.
+                this.hits = new Int32Array(this.hits.length * 2);
+                found = tree.query(this.queryBox, this.hits);
+            }
+            for (let k = 0; k < found; k++) {
+                const b = this.hits[k] ?? 0;
+                // Each unordered pair once, and never a body against itself.
+                if (b <= a)
+                    continue;
+                if (!layersInteract(bodies, a, b))
+                    continue;
+                /* `b > a` by the test above, so this is already the order `pairKey` writes. */
+                const key = a * MAX_BODIES + b;
+                /* The size test rather than the lookup: a world that never excluded a pair pays one
+                   integer compare per candidate, which is what keeps this out of everybody else's way. */
+                if (ignored !== null && ignored.size !== 0 && ignored.has(key))
+                    continue;
+                this.push(key);
+            }
+        }
+        this.sort();
+        return this.count;
+    }
+    push(key) {
+        if (this.count === this.keys.length) {
+            const wider = new Uint32Array(this.keys.length * 2);
+            wider.set(this.keys);
+            this.keys = wider;
+            this.scratch = new Uint32Array(wider.length);
+        }
+        this.keys[this.count++] = key;
+    }
+    /**
+     * Four passes of an 8-bit radix sort, which is stable and touches no comparator.
+     *
+     * A comparison sort would also be deterministic, and this is here for the hot path rather than
+     * for correctness: the pair list is rebuilt every tick and is the one array whose length grows
+     * with the square of local density.
+     */
+    sort() {
+        let from = this.keys;
+        let into = this.scratch;
+        for (let shift = 0; shift < 32; shift += 8) {
+            this.histogram.fill(0);
+            for (let i = 0; i < this.count; i++) {
+                this.histogram[((from[i] ?? 0) >>> shift) & 255]++;
+            }
+            let sum = 0;
+            for (let d = 0; d < 256; d++) {
+                const c = this.histogram[d] ?? 0;
+                this.histogram[d] = sum;
+                sum += c;
+            }
+            for (let i = 0; i < this.count; i++) {
+                const key = from[i] ?? 0;
+                const d = (key >>> shift) & 255;
+                into[this.histogram[d]++] = key;
+            }
+            const swap = from;
+            from = into;
+            into = swap;
+        }
+        // Four passes is even, so the result is back where it started.
+        this.keys = from;
+        this.scratch = into;
+    }
+}
+/** The 32-layer mask, both ways. A pair layersInteract only if each side admits the other. */
+export function layersInteract(bodies, a, b) {
+    if (bodies.type[a] === BODY_STATIC && bodies.type[b] === BODY_STATIC)
+        return false;
+    const la = bodies.layer[a] ?? 0;
+    const lb = bodies.layer[b] ?? 0;
+    const ma = bodies.mask[a] ?? 0;
+    const mb = bodies.mask[b] ?? 0;
+    return (la & mb) !== 0 && (lb & ma) !== 0;
+}
+/**
+ * The key a pair of bodies is stored under, in either order.
+ *
+ * **Two bodies that must never collide cannot always be said with layers.** The mask is a property
+ * of each body on its own, so it can express "this kind does not meet that kind" and cannot express
+ * "these two in particular" — and a ragdoll is entirely the second thing: every bone overlaps the
+ * one it hangs from, because that is what having a radius means, while the same two *kinds* of bone
+ * elsewhere in the body must still collide. A consumer that tried it with layers spent a bit per
+ * bone and most of the 32 on one doll.
+ */
+export function pairKey(a, b) {
+    return a < b ? a * MAX_BODIES + b : b * MAX_BODIES + a;
+}
+/** Unpack a key's lower body index. */
+export function pairA(key) {
+    return Math.floor(key / MAX_BODIES);
+}
+/** Unpack a key's higher body index. */
+export function pairB(key) {
+    return key % MAX_BODIES;
+}

package/dist/query.d.ts

@@ -0,0 +1,71 @@
+import type { BodySet } from './bodies.ts';
+import type { ShapePose } from './manifold.ts';
+import type { ConvexShape } from './shape.ts';
+import { DynamicTree } from './tree.ts';
+/**
+ * Asking the world questions: rays, shape sweeps and overlaps.
+ *
+ * **Nothing allocates.** Every result fills a caller-owned object, and a multi-hit query fills a
+ * caller-supplied array to its length and returns a count — so a query in a tick costs no garbage.
+ *
+ * **Ties break by body index**, which is the same rule the pair list follows and is here for the
+ * same reason: an answer decided by which proxy the tree reached first is an answer decided by
+ * insertion history. **No test pins it**, and that is worth saying rather than leaving somebody to
+ * look: two distinct bodies can only sit at the identical ray distance if they are coincident, and
+ * the tree has never been observed to enumerate coincident proxies out of index order — so a bare
+ * `<=` passes every variation tried. One comparison buys the guarantee by construction instead.
+ *
+ * A shapecast is conservative advancement over the same distance query the manifold code uses,
+ * capped at a fixed iteration count. **What that gives up** is exactness at a grazing angle, where
+ * advancement converges slowly and the cap stops it early — the hit is then reported slightly late.
+ * **What would make it wrong** is a consumer relying on a sweep for precise placement rather than
+ * for a first touch; the answer then is a root-find on the separation, which costs more per query.
+ */
+/** What a ray or a sweep found. Caller-owned; a query fills it and never allocates one. */
+export interface RayHit {
+    body: number;
+    /** Fraction along the ray or sweep, in [0, 1]. */
+    fraction: number;
+    x: number;
+    y: number;
+    z: number;
+    nx: number;
+    ny: number;
+    nz: number;
+}
+export declare function createRayHit(): RayHit;
+/** Which bodies a query is allowed to see. */
+export interface QueryFilter {
+    /** The querier's own layer, tested against each body's mask. */
+    layer?: number;
+    /** Which layers the querier wants, tested against each body's layer. */
+    mask?: number;
+    /** A body to ignore, usually the one asking. */
+    ignore?: number;
+}
+/**
+ * The nearest body a ray meets, or `false` if it meets none.
+ *
+ * A ray starting *inside* a body reports that body at fraction zero, with the normal of the face it
+ * is nearest to leaving through. Reporting nothing instead is the tempting alternative and is worse:
+ * a line-of-sight test would then say a wall it started inside was not there.
+ */
+export declare function raycastWorld(bodies: BodySet, tree: DynamicTree, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, maxDistance: number, out: RayHit, filter?: QueryFilter): boolean;
+/**
+ * Every body overlapping a shape at a pose. Fills `out` to its length and returns how many.
+ *
+ * A return equal to `out.length` means the buffer filled, and the caller has been told about that
+ * many rather than about all of them. Returning the true total instead would invite a loop over
+ * entries that were never written.
+ */
+export declare function overlapWorld(bodies: BodySet, tree: DynamicTree, shape: ConvexShape, pose: ShapePose, out: Int32Array, filter?: QueryFilter): number;
+/**
+ * Sweep a shape from one point to another and report the first body it touches.
+ *
+ * Conservative advancement: step by the current separation, which cannot overshoot a contact, and
+ * stop after a fixed number of steps. A fixed count rather than a tolerance, because §3a forbids
+ * iterating to one.
+ */
+export declare function shapecastWorld(bodies: BodySet, tree: DynamicTree, shape: ConvexShape, pose: ShapePose, dx: number, dy: number, dz: number, out: RayHit, filter?: QueryFilter): boolean;
+/** Whether a body is one a query should treat as scenery. */
+export declare function isStaticBody(bodies: BodySet, i: number): boolean;