@driftengine/physics 3.61.0

package/dist/tree.js

@@ -0,0 +1,348 @@
+/**
+ * A dynamic bounding-volume tree over moving proxies.
+ *
+ * **Two structures answer two questions, and this is the second one.** `ColliderSet`'s uniform hash
+ * is right for static geometry: built once, from solids of known extent, never touched again. It is
+ * wrong for bodies, whose sizes vary by orders of magnitude and which move every tick — a large
+ * body straddles hundreds of cells and every body rehashes. *What would make this wrong* is a
+ * measurement showing the tree beats the hash on static geometry too, at which point they collapse
+ * into one and the hash goes.
+ *
+ * **Fat bounds are what make it incremental.** A proxy re-inserts only when its tight box leaves
+ * the margin it was given, so a body drifting slowly costs nothing but a comparison.
+ *
+ * **Nothing downstream may see this tree.** Insertion order decides tree shape and tree shape
+ * decides enumeration order, and with sequential impulses enumeration order changes the result.
+ * `pairs.ts` sorts by body index for exactly that reason, and this file's ordering is therefore
+ * free to be whatever the heuristic produces.
+ */
+/** How far a proxy's stored box is grown past its tight one, in metres. */
+const MARGIN = 0.1;
+/** A node with no child. Chosen over −1 so the arrays can stay unsigned. */
+export const NIL = 0x7fffffff;
+export class DynamicTree {
+    root = NIL;
+    /** minX, minY, minZ, maxX, maxY, maxZ per node. */
+    bounds;
+    parent;
+    child1;
+    child2;
+    /** The caller's own id for a leaf; −1 on an internal node. */
+    proxy;
+    height;
+    capacity;
+    free = 0;
+    nodeCount = 0;
+    stack;
+    constructor(capacity = 64) {
+        this.capacity = Math.max(2, capacity | 0);
+        this.bounds = new Float32Array(this.capacity * 6);
+        this.parent = new Int32Array(this.capacity);
+        this.child1 = new Int32Array(this.capacity);
+        this.child2 = new Int32Array(this.capacity);
+        this.proxy = new Int32Array(this.capacity);
+        this.height = new Int32Array(this.capacity);
+        this.stack = new Int32Array(64);
+        this.resetFreeList(0);
+    }
+    /** How many nodes are in use. A tree of n leaves has 2n − 1 nodes. */
+    get count() {
+        return this.nodeCount;
+    }
+    insert(proxyId, box) {
+        const leaf = this.allocate();
+        const at = leaf * 6;
+        this.bounds[at] = box.minX - MARGIN;
+        this.bounds[at + 1] = box.minY - MARGIN;
+        this.bounds[at + 2] = box.minZ - MARGIN;
+        this.bounds[at + 3] = box.maxX + MARGIN;
+        this.bounds[at + 4] = box.maxY + MARGIN;
+        this.bounds[at + 5] = box.maxZ + MARGIN;
+        this.proxy[leaf] = proxyId;
+        this.height[leaf] = 0;
+        this.insertLeaf(leaf);
+        return leaf;
+    }
+    remove(leaf) {
+        this.removeLeaf(leaf);
+        this.freeNode(leaf);
+    }
+    /**
+     * Re-place a proxy whose tight box has moved. Returns whether the tree changed.
+     *
+     * A move entirely inside the fat box is free: the stored bounds still enclose the proxy, so no
+     * query can miss it. That is the whole point of the margin, and the reason it is a *conservative*
+     * enlargement rather than a tolerance.
+     */
+    move(leaf, box) {
+        const at = leaf * 6;
+        if (box.minX >= (this.bounds[at] ?? 0) &&
+            box.minY >= (this.bounds[at + 1] ?? 0) &&
+            box.minZ >= (this.bounds[at + 2] ?? 0) &&
+            box.maxX <= (this.bounds[at + 3] ?? 0) &&
+            box.maxY <= (this.bounds[at + 4] ?? 0) &&
+            box.maxZ <= (this.bounds[at + 5] ?? 0)) {
+            return false;
+        }
+        const id = this.proxy[leaf] ?? 0;
+        this.removeLeaf(leaf);
+        this.bounds[at] = box.minX - MARGIN;
+        this.bounds[at + 1] = box.minY - MARGIN;
+        this.bounds[at + 2] = box.minZ - MARGIN;
+        this.bounds[at + 3] = box.maxX + MARGIN;
+        this.bounds[at + 4] = box.maxY + MARGIN;
+        this.bounds[at + 5] = box.maxZ + MARGIN;
+        this.proxy[leaf] = id;
+        this.insertLeaf(leaf);
+        return true;
+    }
+    /** Fill `out` with every proxy id whose stored box overlaps `box`. Returns how many. */
+    query(box, out) {
+        if (this.root === NIL)
+            return 0;
+        let top = 0;
+        this.stack[top++] = this.root;
+        let found = 0;
+        while (top > 0) {
+            const node = this.stack[--top] ?? NIL;
+            if (node === NIL)
+                continue;
+            const at = node * 6;
+            if ((this.bounds[at] ?? 0) > box.maxX ||
+                (this.bounds[at + 3] ?? 0) < box.minX ||
+                (this.bounds[at + 1] ?? 0) > box.maxY ||
+                (this.bounds[at + 4] ?? 0) < box.minY ||
+                (this.bounds[at + 2] ?? 0) > box.maxZ ||
+                (this.bounds[at + 5] ?? 0) < box.minZ) {
+                continue;
+            }
+            if (this.child1[node] === NIL) {
+                if (found < out.length)
+                    out[found] = this.proxy[node] ?? 0;
+                found++;
+                continue;
+            }
+            if (top + 2 > this.stack.length)
+                this.stack = growInt(this.stack, this.stack.length * 2);
+            this.stack[top++] = this.child1[node] ?? NIL;
+            this.stack[top++] = this.child2[node] ?? NIL;
+        }
+        return found > out.length ? out.length : found;
+    }
+    insertLeaf(leaf) {
+        if (this.root === NIL) {
+            this.root = leaf;
+            this.parent[leaf] = NIL;
+            return;
+        }
+        // Descend to the sibling whose union with the leaf costs the least surface area.
+        let node = this.root;
+        while (this.child1[node] !== NIL) {
+            const c1 = this.child1[node] ?? NIL;
+            const c2 = this.child2[node] ?? NIL;
+            node = this.unionArea(leaf, c1) < this.unionArea(leaf, c2) ? c1 : c2;
+        }
+        const sibling = node;
+        const oldParent = this.parent[sibling] ?? NIL;
+        const newParent = this.allocate();
+        this.parent[newParent] = oldParent;
+        this.proxy[newParent] = -1;
+        this.union(newParent, leaf, sibling);
+        this.height[newParent] = (this.height[sibling] ?? 0) + 1;
+        if (oldParent !== NIL) {
+            if (this.child1[oldParent] === sibling)
+                this.child1[oldParent] = newParent;
+            else
+                this.child2[oldParent] = newParent;
+        }
+        else {
+            this.root = newParent;
+        }
+        this.child1[newParent] = sibling;
+        this.child2[newParent] = leaf;
+        this.parent[sibling] = newParent;
+        this.parent[leaf] = newParent;
+        this.refit(this.parent[leaf] ?? NIL);
+    }
+    removeLeaf(leaf) {
+        if (leaf === this.root) {
+            this.root = NIL;
+            return;
+        }
+        const parent = this.parent[leaf] ?? NIL;
+        const grand = this.parent[parent] ?? NIL;
+        const sibling = this.child1[parent] === leaf ? (this.child2[parent] ?? NIL) : (this.child1[parent] ?? NIL);
+        if (grand !== NIL) {
+            if (this.child1[grand] === parent)
+                this.child1[grand] = sibling;
+            else
+                this.child2[grand] = sibling;
+            this.parent[sibling] = grand;
+            this.freeNode(parent);
+            this.refit(grand);
+        }
+        else {
+            this.root = sibling;
+            this.parent[sibling] = NIL;
+            this.freeNode(parent);
+        }
+    }
+    refit(from) {
+        let node = from;
+        while (node !== NIL) {
+            node = this.balance(node);
+            const c1 = this.child1[node] ?? NIL;
+            const c2 = this.child2[node] ?? NIL;
+            this.union(node, c1, c2);
+            const h1 = this.height[c1] ?? 0;
+            const h2 = this.height[c2] ?? 0;
+            this.height[node] = (h1 > h2 ? h1 : h2) + 1;
+            node = this.parent[node] ?? NIL;
+        }
+    }
+    /**
+     * One AVL-style rotation where a subtree leans by more than one, returning the new subtree root.
+     *
+     * **Without this the surface-area descent builds a chain, and it does so on the most ordinary
+     * scene there is.** Measured: sixty-four boxes in a row along x came out as a tree of height 63,
+     * because each new box unions most cheaply with the rightmost leaf and the descent therefore
+     * walks the right spine every time. A wall, a stack and a floor strip are all that shape, and a
+     * chain makes every query linear, which is the entire cost the tree exists to avoid. A grid was
+     * height 14 and hid it.
+     *
+     * The heuristic chooses *where* to insert and the rotation keeps the result usable; neither
+     * substitutes for the other. **What this costs** is a rotation test per node on the way up, all
+     * of it integer comparison. **What would make it wrong** is nothing measured yet; the alternative
+     * is a full rebuild, which is dearer and not incremental.
+     */
+    balance(a) {
+        if (this.child1[a] === NIL || (this.height[a] ?? 0) < 2)
+            return a;
+        const b = this.child1[a] ?? NIL;
+        const c = this.child2[a] ?? NIL;
+        const lean = (this.height[c] ?? 0) - (this.height[b] ?? 0);
+        if (lean > 1)
+            return this.rotate(a, c, b);
+        if (lean < -1)
+            return this.rotate(a, b, c);
+        return a;
+    }
+    /** Pull `up` above `a`, keeping `keep` as `a`'s remaining child. */
+    rotate(a, up, keep) {
+        const f = this.child1[up] ?? NIL;
+        const g = this.child2[up] ?? NIL;
+        const grand = this.parent[a] ?? NIL;
+        this.child1[up] = a;
+        this.parent[up] = grand;
+        this.parent[a] = up;
+        if (grand !== NIL) {
+            if (this.child1[grand] === a)
+                this.child1[grand] = up;
+            else
+                this.child2[grand] = up;
+        }
+        else {
+            this.root = up;
+        }
+        // The taller grandchild rises with `up`; the shorter one drops to `a`.
+        const tall = (this.height[f] ?? 0) > (this.height[g] ?? 0) ? f : g;
+        const short = tall === f ? g : f;
+        this.child2[up] = tall;
+        this.child2[a] = short;
+        this.child1[a] = keep;
+        this.parent[short] = a;
+        this.union(a, keep, short);
+        this.union(up, a, tall);
+        const hk = this.height[keep] ?? 0;
+        const hs = this.height[short] ?? 0;
+        this.height[a] = (hk > hs ? hk : hs) + 1;
+        const ha = this.height[a] ?? 0;
+        const ht = this.height[tall] ?? 0;
+        this.height[up] = (ha > ht ? ha : ht) + 1;
+        return up;
+    }
+    union(into, a, b) {
+        const t = into * 6;
+        const p = a * 6;
+        const q = b * 6;
+        for (let k = 0; k < 3; k++) {
+            const pa = this.bounds[p + k] ?? 0;
+            const qb = this.bounds[q + k] ?? 0;
+            this.bounds[t + k] = pa < qb ? pa : qb;
+            const pc = this.bounds[p + k + 3] ?? 0;
+            const qc = this.bounds[q + k + 3] ?? 0;
+            this.bounds[t + k + 3] = pc > qc ? pc : qc;
+        }
+    }
+    /** Surface area of the box enclosing two nodes. The heuristic, and only `+ - *`. */
+    unionArea(a, b) {
+        const p = a * 6;
+        const q = b * 6;
+        const ax = this.bounds[p] ?? 0;
+        const bx = this.bounds[q] ?? 0;
+        const ay = this.bounds[p + 1] ?? 0;
+        const by = this.bounds[q + 1] ?? 0;
+        const az = this.bounds[p + 2] ?? 0;
+        const bz = this.bounds[q + 2] ?? 0;
+        const cx = this.bounds[p + 3] ?? 0;
+        const dx = this.bounds[q + 3] ?? 0;
+        const cy = this.bounds[p + 4] ?? 0;
+        const dy = this.bounds[q + 4] ?? 0;
+        const cz = this.bounds[p + 5] ?? 0;
+        const dz = this.bounds[q + 5] ?? 0;
+        const w = (cx > dx ? cx : dx) - (ax < bx ? ax : bx);
+        const h = (cy > dy ? cy : dy) - (ay < by ? ay : by);
+        const d = (cz > dz ? cz : dz) - (az < bz ? az : bz);
+        return w * h + h * d + d * w;
+    }
+    allocate() {
+        if (this.free === NIL)
+            this.growNodes();
+        const node = this.free;
+        this.free = this.parent[node] ?? NIL;
+        this.parent[node] = NIL;
+        this.child1[node] = NIL;
+        this.child2[node] = NIL;
+        this.height[node] = 0;
+        this.nodeCount++;
+        return node;
+    }
+    freeNode(node) {
+        this.parent[node] = this.free;
+        this.child1[node] = NIL;
+        this.child2[node] = NIL;
+        this.height[node] = -1;
+        this.free = node;
+        this.nodeCount--;
+    }
+    growNodes() {
+        const old = this.capacity;
+        this.capacity *= 2;
+        this.bounds = growFloat(this.bounds, this.capacity * 6);
+        this.parent = growInt(this.parent, this.capacity);
+        this.child1 = growInt(this.child1, this.capacity);
+        this.child2 = growInt(this.child2, this.capacity);
+        this.proxy = growInt(this.proxy, this.capacity);
+        this.height = growInt(this.height, this.capacity);
+        this.resetFreeList(old);
+    }
+    resetFreeList(from) {
+        for (let i = from; i < this.capacity - 1; i++) {
+            this.parent[i] = i + 1;
+            this.height[i] = -1;
+        }
+        this.parent[this.capacity - 1] = NIL;
+        this.height[this.capacity - 1] = -1;
+        this.free = from;
+    }
+}
+function growFloat(a, n) {
+    const out = new Float32Array(n);
+    out.set(a);
+    return out;
+}
+function growInt(a, n) {
+    const out = new Int32Array(n);
+    out.set(a);
+    return out;
+}

package/dist/vehicle.d.ts

@@ -0,0 +1,154 @@
+import type { QueryFilter } from './query.ts';
+import type { PhysicsWorld } from './world.ts';
+import type { GroundProbe } from './controller.ts';
+/**
+ * A raycast vehicle: a chassis body, and wheels that are rays rather than bodies.
+ *
+ * **Rigid wheels on joints are the obvious alternative and are unstable in practice.** They need
+ * joint stiffness and substep counts that nobody wants to pay, which is why Bullet, Godot and Unity
+ * all raycast. *What that costs, said where the decision is:* a raycast wheel cannot wedge in
+ * geometry, cannot collide with another wheel, and a vehicle on its side behaves as a box rather
+ * than as a car. *What would reverse it* is a game about vehicles interlocking with terrain.
+ *
+ * **The tyre curve is a table the caller supplies.** Pacejka's magic formula is `sin(atan(…))` and
+ * both are banned from the tick, so grip is sampled from a curve and linearly interpolated. This is
+ * the one place in Track B where the arithmetic contract produced a *better* API than the closed
+ * form it replaced: a curve is edited by moving a point, and a magic formula is edited by guessing
+ * at a coefficient nobody can picture.
+ *
+ * Everything here is applied as an impulse at a point on the chassis, so the vehicle's roll, pitch
+ * and weight transfer fall out of the solver rather than being modelled separately.
+ */
+/**
+ * Grip against slip, as a lookup table.
+ *
+ * `force[i]` is the fraction of the load available as lateral or longitudinal force at
+ * `slip[i]`. Both arrays are the same length and `slip` must ascend. Beyond the last entry the
+ * final value is held, which is what a tyre past its peak does.
+ */
+export interface TyreCurve {
+    readonly slip: Float32Array;
+    readonly force: Float32Array;
+}
+/** A curve that rises to a peak and falls away, which is what a tyre does. */
+export declare function defaultTyreCurve(peak?: number): TyreCurve;
+export interface WheelOptions {
+    /** Where the suspension is anchored, in the chassis's local frame. */
+    x: number;
+    y: number;
+    z: number;
+    radius?: number;
+    /** How far the wheel may travel below its anchor. */
+    suspensionTravel?: number;
+    /** Spring rate, in newtons per metre of compression. */
+    stiffness?: number;
+    /** Damping, in newtons per metre per second. */
+    damping?: number;
+    /** Whether steering input turns this wheel. */
+    steers?: boolean;
+    /** Whether engine and brake force reach it. */
+    driven?: boolean;
+}
+export interface VehicleOptions {
+    wheels: readonly WheelOptions[];
+    /** Maximum steering angle, as the tangent of the angle rather than the angle. */
+    maxSteerTangent?: number;
+    /** Newtons at full throttle, shared across driven wheels. */
+    engineForce?: number;
+    /** Newtons at full brake. */
+    brakeForce?: number;
+    longitudinal?: TyreCurve;
+    lateral?: TyreCurve;
+    filter?: QueryFilter;
+    /**
+     * A surface the wheels can rest on that is not a body.
+     *
+     * The same seam `CharacterController` takes, and here for the same reason plus one: a consumer
+     * whose ground is a height function had a character that stood on it and a car that fell through
+     * it, so the world's floor was two things that had to be kept in step by hand. It was reported
+     * that way — a hundred lines of ground query written consumer-side, and then written again for
+     * everything else that stands on it.
+     *
+     * Consulted only where the wheel's ray found no body, on the same ruling the controller carries:
+     * a body is a thing that is there and a surface is a description of where the ground is.
+     */
+    ground?: GroundProbe;
+}
+export interface VehicleInput {
+    /** −1 to 1. */
+    throttle: number;
+    /** 0 to 1. */
+    brake: number;
+    /** −1 to 1, scaled by `maxSteerTangent`. */
+    steer: number;
+}
+export declare class Vehicle {
+    readonly chassis: number;
+    readonly wheelCount: number;
+    /** Whether each wheel found ground on the last update. */
+    readonly grounded: Uint8Array;
+    /** How far each wheel's suspension is compressed, in metres. */
+    readonly compression: Float32Array;
+    /** Where each wheel's contact is, xyz-packed. Meaningful where `grounded`. */
+    readonly contact: Float32Array;
+    private readonly local;
+    private readonly radius;
+    private readonly travel;
+    private readonly stiffness;
+    private readonly damping;
+    private readonly steers;
+    private readonly driven;
+    private readonly maxSteerTangent;
+    private readonly engineForce;
+    private readonly brakeForce;
+    private readonly longitudinal;
+    private readonly lateral;
+    /**
+     * The suspension ray must ignore the car it holds up.
+     *
+     * A wheel anchor sits *inside* the chassis by construction — that is what a suspension mount is —
+     * and a ray starting inside a body reports that body at fraction zero, which is the right answer
+     * to the question a line-of-sight test asks and the wrong one here. Left unfiltered, every wheel
+     * found the chassis at zero distance, read the suspension as fully compressed, and pushed the car
+     * against itself: it sank onto its own chassis and sat there.
+     */
+    private readonly filter;
+    private readonly hit;
+    private readonly probe;
+    /** Scratch for the probe, claimed once: every wheel asks it every tick. */
+    private readonly probed;
+    /**
+     * Every wheel's impulse, gathered before any is applied: `rx ry rz px py pz` per wheel.
+     *
+     * **Applying them one at a time makes the car curve.** Each wheel then sees a velocity the
+     * previous wheel has already changed, so the left front's lateral impulse biases what the right
+     * front computes, and the asymmetry accumulates into a yaw rather than cancelling. Measured on a
+     * symmetric car under straight throttle: 0.011 metres of drift after 2 metres, 0.64 after 39, and
+     * **5.49 after 155** — a curve, not a wobble. Forces at an instant are simultaneous, and gathering
+     * them is both the correct physics and the cheaper fix.
+     */
+    private readonly pending;
+    constructor(chassis: number, options: VehicleOptions);
+    /** Advance the vehicle one fixed tick. Call before `world.step`. */
+    update(world: PhysicsWorld, dt: number, input: VehicleInput): void;
+    /** Add an impulse at a wheel's anchor to what will be applied at the end of the pass. */
+    /**
+     * Rest a wheel on the analytic surface, filling `hit` as a ray against a body would have.
+     *
+     * Everything downstream — the spring, the damper, the tyre frame flattened onto the ground —
+     * reads `hit`, so filling it is the whole of the wiring and no grip code learns that a surface
+     * exists.
+     *
+     * **The column is the anchor's own and the drop is measured along the chassis's down**, which is
+     * exact while the chassis is upright and off by its tilt when it is not: the true contact sits a
+     * little to the side of the column that was sampled, and on a slope that column is a little
+     * higher or lower than the contact. At the lean angles a car spends its life at the error is
+     * millimetres, and the alternative is solving a ray against an arbitrary height function, which
+     * is an iteration this package does not allow itself. A vehicle on its roof finds no ground here
+     * at all, because there is no downward intersection to find, which is the honest answer.
+     */
+    private probeUnder;
+    private gather;
+}
+/** Sample a curve at `at`, holding the last value beyond its end. */
+export declare function sampleTyreCurve(curve: TyreCurve, at: number): number;