@driftengine/physics 4.8.0 → 4.8.2

package/dist/controller.d.ts

@@ -303,6 +303,8 @@ export declare class CharacterController {
      * would climb twice.
      */
     private tryStep;
+    /** Put the body back where a step began, and say the step was not taken. */
+    private stepBack;
     /**
      * Sweep the foot ball down, and fall back to a ray when what it finds is not walkable.
      *

package/dist/controller.js

@@ -36,6 +36,8 @@ const SLIDE_PASSES = 4;
  * own stop margin already leaves a tenth of a millimetre of clearance, which is what a skin was for.
  */
 const SNAP_EPS = 0.001;
+/** How far past a step's edge a step that landed on the edge carries the body's axis. */
+const STEP_OVER = 0.01;
 export class CharacterController {
     x = 0;
     y = 0;
@@ -311,9 +313,10 @@ export class CharacterController {
          * the same clamp and air control — only the plane is given up, not the feel.
          */
         if (input.projectMove === false) {
-            this.velX = approach(this.velX, wantX, step);
-            this.velY = approach(this.velY, wantY, step);
-            this.velZ = approach(this.velZ, wantZ, step);
+            const t = approachFraction(wantX - this.velX, wantY - this.velY, wantZ - this.velZ, step);
+            this.velX = t === 1 ? wantX : this.velX + (wantX - this.velX) * t;
+            this.velY = t === 1 ? wantY : this.velY + (wantY - this.velY) * t;
+            this.velZ = t === 1 ? wantZ : this.velZ + (wantZ - this.velZ) * t;
         }
         else {
             const alongUp = this.speedAlongUp;
@@ -324,9 +327,10 @@ export class CharacterController {
             const wantTangentX = wantX - this.upX * wantIntoUp;
             const wantTangentY = wantY - this.upY * wantIntoUp;
             const wantTangentZ = wantZ - this.upZ * wantIntoUp;
-            tangentX = approach(tangentX, wantTangentX, step);
-            tangentY = approach(tangentY, wantTangentY, step);
-            tangentZ = approach(tangentZ, wantTangentZ, step);
+            const t = approachFraction(wantTangentX - tangentX, wantTangentY - tangentY, wantTangentZ - tangentZ, step);
+            tangentX = t === 1 ? wantTangentX : tangentX + (wantTangentX - tangentX) * t;
+            tangentY = t === 1 ? wantTangentY : tangentY + (wantTangentY - tangentY) * t;
+            tangentZ = t === 1 ? wantTangentZ : tangentZ + (wantTangentZ - tangentZ) * t;
             this.velX = tangentX + this.upX * alongUp;
             this.velY = tangentY + this.upY * alongUp;
             this.velZ = tangentZ + this.upZ * alongUp;
@@ -452,26 +456,69 @@ export class CharacterController {
         this.z += liftZ;
         this.readPose();
         if (world.shapecast(this.shape, this.pose, flatX, flatY, flatZ, this.stepHit, this.filter)) {
-            this.x = startX;
-            this.y = startY;
-            this.z = startZ;
-            return false;
+            return this.stepBack(startX, startY, startZ);
         }
         this.x += flatX;
         this.y += flatY;
         this.z += flatZ;
         this.readPose();
-        if (world.shapecast(this.shape, this.pose, -liftX, -liftY, -liftZ, this.stepHit, this.filter)) {
-            const drop = this.stepHeight * this.stepHit.fraction - SNAP_EPS;
-            this.x -= this.upX * drop;
-            this.y -= this.upY * drop;
-            this.z -= this.upZ * drop;
-            return true;
+        if (!world.shapecast(this.shape, this.pose, -liftX, -liftY, -liftZ, this.stepHit, this.filter)) {
+            // Nothing beneath the lifted position, so this was a gap rather than a step.
+            return this.stepBack(startX, startY, startZ);
         }
-        // Nothing beneath the lifted position, so this was a gap rather than a step.
-        this.x = startX;
-        this.y = startY;
-        this.z = startZ;
+        let landing = this.stepHit.nx * this.upX + this.stepHit.ny * this.upY + this.stepHit.nz * this.upZ;
+        if (landing < this.slopeCos) {
+            /*
+             * **Landed on the lip, so go on over it.** The forward part of a step is what was left of
+             * the tick's move when the body met the step, and at a tick's length that can be millimetres:
+             * the foot ball then comes down on the step's edge, a contact far too steep to stand on, and
+             * the body was set there airborne, slid off, and never stepped again. Measured with a 0.32 m
+             * radius and a 0.35 m step height: a 0.25 m rise climbed and a 0.28 m one did not.
+             *
+             * The edge's normal points from the edge at the ball's centre, so its part across up is how
+             * far the axis stands short of the edge. Moving that far again, plus a centimetre, puts the
+             * ball over the step's top, where the drop meets a face. The body moves up to one radius
+             * further in that tick than it was going to, which is the price of a step taken in one tick.
+             */
+            const lipX = this.stepHit.nx - this.upX * landing;
+            const lipY = this.stepHit.ny - this.upY * landing;
+            const lipZ = this.stepHit.nz - this.upZ * landing;
+            const lip = Math.sqrt(lipX * lipX + lipY * lipY + lipZ * lipZ);
+            // An edge behind the move, or beside it, is not one this step was climbing.
+            if (lip < 1e-6 || lipX * flatX + lipY * flatY + lipZ * flatZ >= 0) {
+                return this.stepBack(startX, startY, startZ);
+            }
+            const reach = (this.radius * lip + STEP_OVER) / lip;
+            const overX = -lipX * reach;
+            const overY = -lipY * reach;
+            const overZ = -lipZ * reach;
+            this.readPose();
+            if (world.shapecast(this.shape, this.pose, overX, overY, overZ, this.stepHit, this.filter)) {
+                return this.stepBack(startX, startY, startZ);
+            }
+            this.x += overX;
+            this.y += overY;
+            this.z += overZ;
+            this.readPose();
+            if (!world.shapecast(this.shape, this.pose, -liftX, -liftY, -liftZ, this.stepHit, this.filter)) {
+                return this.stepBack(startX, startY, startZ);
+            }
+            landing =
+                this.stepHit.nx * this.upX + this.stepHit.ny * this.upY + this.stepHit.nz * this.upZ;
+            if (landing < this.slopeCos)
+                return this.stepBack(startX, startY, startZ);
+        }
+        const drop = this.stepHeight * this.stepHit.fraction - SNAP_EPS;
+        this.x -= this.upX * drop;
+        this.y -= this.upY * drop;
+        this.z -= this.upZ * drop;
+        return true;
+    }
+    /** Put the body back where a step began, and say the step was not taken. */
+    stepBack(x, y, z) {
+        this.x = x;
+        this.y = y;
+        this.z = z;
         return false;
     }
     /**
@@ -630,12 +677,18 @@ export class CharacterController {
         this.pose.qw = w * inverse;
     }
 }
-/** Move `from` toward `to` by at most `step`. */
-function approach(from, to, step) {
-    const d = to - from;
-    if (d > step)
-        return from + step;
-    if (d < -step)
-        return from - step;
-    return to;
+/**
+ * How much of the way to close a gap of `(dx, dy, dz)` this tick: exactly 1 when the gap is no
+ * longer than `step`, which the caller reads as "land on the target", and `step` of its length
+ * otherwise.
+ *
+ * **Toward the wanted velocity as a vector, by at most `step` in length.** It was one world axis at
+ * a time, each by the whole step, so a diagonal gained and lost speed √2 times as fast as a straight
+ * run while the clamp on the wanted vector kept its top speed honest — the faster diagonal lived in
+ * the acceleration. What it gives up is that an axis no longer reaches its target on its own
+ * schedule: turning from one direction to another now curves rather than squaring the corner.
+ */
+function approachFraction(dx, dy, dz, step) {
+    const gap = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    return gap <= step ? 1 : step / gap;
 }

package/dist/manifold.js

@@ -113,6 +113,68 @@ function roundRound(a, b, margin, out) {
     return true;
 }
 /* ---------- sphere or capsule against a polytope ---------- */
+/** Where along a capsule's segment the search settles: 0.618 to the 30th of 1.2 m is under a micron. */
+const SEGMENT_STEPS = 30;
+const INV_PHI = 0.6180339887498949;
+/** Each end's direction away from the polytope, and its separation, read by the segment search. */
+const END_DIR = new Float64Array(9);
+const END_SEP = new Float64Array(2);
+/** The manifold being filled by `roundPolytope`, kept here so adding a contact allocates nothing. */
+const ROUND = { count: 0, bestSep: Infinity, nx: 0, ny: 1, nz: 0, margin: 0, flipped: false };
+/** Add the contact `CLOSEST` and `END_DIR[slot]` describe, at `separation`, as `feature`. */
+function emitRound(out, slot, separation, feature) {
+    if (separation > ROUND.margin || ROUND.count >= MAX_CONTACTS)
+        return;
+    // Normal points from the round shape toward the polytope, then flipped if A was the polytope.
+    const ux = END_DIR[slot * 3] ?? 0;
+    const uy = END_DIR[slot * 3 + 1] ?? 0;
+    const uz = END_DIR[slot * 3 + 2] ?? 0;
+    if (separation < ROUND.bestSep) {
+        ROUND.bestSep = separation;
+        ROUND.nx = ROUND.flipped ? ux : -ux;
+        ROUND.ny = ROUND.flipped ? uy : -uy;
+        ROUND.nz = ROUND.flipped ? uz : -uz;
+    }
+    const at = ROUND.count * 3;
+    out.points[at] = CLOSEST[0];
+    out.points[at + 1] = CLOSEST[1];
+    out.points[at + 2] = CLOSEST[2];
+    out.separations[ROUND.count] = separation;
+    out.featureIds[ROUND.count] = feature;
+    ROUND.count++;
+}
+/**
+ * The signed distance from a point to the polytope, with the direction away from it left in
+ * `END_DIR[slot]`: positive outside, the deepest face's plane distance inside.
+ */
+function signedDistance(poly, polyWorld, faces, px, py, pz, slot) {
+    closestOnPolytope(poly, polyWorld, planesB, faces, px, py, pz);
+    let ux = px - CLOSEST[0];
+    let uy = py - CLOSEST[1];
+    let uz = pz - CLOSEST[2];
+    let d = Math.sqrt(ux * ux + uy * uy + uz * uz);
+    if (CLOSEST[6] < 0) {
+        // Inside: the closest face's outward normal is the direction, and depth is its plane distance.
+        ux = CLOSEST[3];
+        uy = CLOSEST[4];
+        uz = CLOSEST[5];
+        d = CLOSEST[6];
+    }
+    else if (d === 0) {
+        ux = CLOSEST[3];
+        uy = CLOSEST[4];
+        uz = CLOSEST[5];
+    }
+    else {
+        ux /= d;
+        uy /= d;
+        uz /= d;
+    }
+    END_DIR[slot * 3] = ux;
+    END_DIR[slot * 3 + 1] = uy;
+    END_DIR[slot * 3 + 2] = uz;
+    return d;
+}
 function roundPolytope(round, poly, polyPose, margin, out, flipped) {
     // `worldA` holds whichever shape was passed first, so read the round one from the right buffer.
     const roundWorld = flipped ? worldB : worldA;
@@ -120,67 +182,79 @@ function roundPolytope(round, poly, polyPose, margin, out, flipped) {
     planesToWorld(poly, polyPose, polyWorld, planesB);
     const points = round.vertices.length / 3;
     const faces = faceCount(poly);
-    let count = 0;
-    let bestSep = Infinity;
-    let nx = 0;
-    let ny = 1;
-    let nz = 0;
-    for (let p = 0; p < points; p++) {
-        const px = roundWorld[p * 3] ?? 0;
-        const py = roundWorld[p * 3 + 1] ?? 0;
-        const pz = roundWorld[p * 3 + 2] ?? 0;
-        closestOnPolytope(poly, polyWorld, planesB, faces, px, py, pz);
-        let ux = px - CLOSEST[0];
-        let uy = py - CLOSEST[1];
-        let uz = pz - CLOSEST[2];
-        let d = Math.sqrt(ux * ux + uy * uy + uz * uz);
-        if (CLOSEST[6] < 0) {
-            // Inside: the closest face's outward normal is the direction, and depth is its plane distance.
-            ux = CLOSEST[3];
-            uy = CLOSEST[4];
-            uz = CLOSEST[5];
-            d = CLOSEST[6];
-        }
-        else if (d === 0) {
-            ux = CLOSEST[3];
-            uy = CLOSEST[4];
-            uz = CLOSEST[5];
-        }
-        else {
-            ux /= d;
-            uy /= d;
-            uz /= d;
-        }
-        const separation = d - round.radius - poly.radius;
-        if (separation > margin)
-            continue;
-        if (count >= MAX_CONTACTS)
-            break;
-        // Normal points from the round shape toward the polytope, then flipped if A was the polytope.
-        const sx = flipped ? ux : -ux;
-        const sy = flipped ? uy : -uy;
-        const sz = flipped ? uz : -uz;
-        if (separation < bestSep) {
-            bestSep = separation;
-            nx = sx;
-            ny = sy;
-            nz = sz;
-        }
-        const at = count * 3;
-        out.points[at] = CLOSEST[0];
-        out.points[at + 1] = CLOSEST[1];
-        out.points[at + 2] = CLOSEST[2];
-        out.separations[count] = separation;
+    const radii = round.radius + poly.radius;
+    ROUND.count = 0;
+    ROUND.bestSep = Infinity;
+    ROUND.nx = 0;
+    ROUND.ny = 1;
+    ROUND.nz = 0;
+    ROUND.margin = margin;
+    ROUND.flipped = flipped;
+    for (let p = 0; p < points && p < 2; p++) {
+        const separation = signedDistance(poly, polyWorld, faces, roundWorld[p * 3] ?? 0, roundWorld[p * 3 + 1] ?? 0, roundWorld[p * 3 + 2] ?? 0, p) - radii;
+        END_SEP[p] = separation;
         // The endpoint that produced it, which is stable while the capsule keeps its orientation.
-        out.featureIds[count] = 0x40000000 | p;
-        count++;
+        emitRound(out, p, separation, 0x40000000 | p);
     }
-    if (count === 0)
+    /*
+     * **A capsule is a segment, and its middle can be the part that touches.** This used to ask only
+     * its two ends, which is exact for a ball and for a capsule lying on a face, and wrong wherever the
+     * segment crosses an edge: a standing capsule walked through a slab across its waist, because
+     * neither end ball came within reach of it, and a capsule lying across a rail fell through it.
+     *
+     * The distance from a point on the segment to a convex polytope is convex along the segment, so
+     * its least value is at an end exactly when the slope there points away from the other end. Each
+     * end's direction away from the polytope is that slope, so a capsule whose ends are the answer, as
+     * one standing on a floor always is, costs nothing more. Otherwise a fixed number of golden-section
+     * steps finds the interior point, and it is kept only where it is nearer than both ends.
+     */
+    if (points === 2) {
+        const ax = roundWorld[0] ?? 0;
+        const ay = roundWorld[1] ?? 0;
+        const az = roundWorld[2] ?? 0;
+        const sx = (roundWorld[3] ?? 0) - ax;
+        const sy = (roundWorld[4] ?? 0) - ay;
+        const sz = (roundWorld[5] ?? 0) - az;
+        const leavesFirst = sx * (END_DIR[0] ?? 0) + sy * (END_DIR[1] ?? 0) + sz * (END_DIR[2] ?? 0);
+        const leavesSecond = -(sx * (END_DIR[3] ?? 0) +
+            sy * (END_DIR[4] ?? 0) +
+            sz * (END_DIR[5] ?? 0));
+        if (leavesFirst < 0 && leavesSecond < 0) {
+            let lo = 0;
+            let hi = 1;
+            let m1 = hi - (hi - lo) * INV_PHI;
+            let m2 = lo + (hi - lo) * INV_PHI;
+            let f1 = signedDistance(poly, polyWorld, faces, ax + sx * m1, ay + sy * m1, az + sz * m1, 2);
+            let f2 = signedDistance(poly, polyWorld, faces, ax + sx * m2, ay + sy * m2, az + sz * m2, 2);
+            for (let step = 0; step < SEGMENT_STEPS; step++) {
+                if (f1 <= f2) {
+                    hi = m2;
+                    m2 = m1;
+                    f2 = f1;
+                    m1 = hi - (hi - lo) * INV_PHI;
+                    f1 = signedDistance(poly, polyWorld, faces, ax + sx * m1, ay + sy * m1, az + sz * m1, 2);
+                }
+                else {
+                    lo = m1;
+                    m1 = m2;
+                    f1 = f2;
+                    m2 = lo + (hi - lo) * INV_PHI;
+                    f2 = signedDistance(poly, polyWorld, faces, ax + sx * m2, ay + sy * m2, az + sz * m2, 2);
+                }
+            }
+            const at = (lo + hi) / 2;
+            const separation = signedDistance(poly, polyWorld, faces, ax + sx * at, ay + sy * at, az + sz * at, 2) - radii;
+            if (separation < Math.min(END_SEP[0] ?? Infinity, END_SEP[1] ?? Infinity) - 1e-7) {
+                emitRound(out, 2, separation, 0x40000000 | 2);
+            }
+        }
+    }
+    if (ROUND.count === 0)
         return false;
-    out.nx = nx;
-    out.ny = ny;
-    out.nz = nz;
-    out.count = count;
+    out.nx = ROUND.nx;
+    out.ny = ROUND.ny;
+    out.nz = ROUND.nz;
+    out.count = ROUND.count;
     return true;
 }
 /* ---------- polytope against polytope ---------- */

package/dist/query.js

@@ -697,7 +697,15 @@ export function shapecastWorld(bodies, tree, shape, pose, dx, dy, dz, out, filte
             }
             else if (!collideShapes(shape, poseA, other, poseB, 1e9, manifold))
                 break;
-            const gap = manifold.separations[0] ?? 0;
+            /*
+             * **The nearest contact, not the first one written.** A capsule's manifold holds a point per
+             * end, and the first is its lower end: reading only that advanced the sweep by the distance
+             * from the lower ball while the upper one was the nearer, so a standing capsule swept clean
+             * through a beam at head height.
+             */
+            let gap = Infinity;
+            for (let c = 0; c < manifold.count; c++)
+                gap = Math.min(gap, manifold.separations[c] ?? gap);
             if (gap < 1e-4) {
                 /*
                  * A shape already touching a surface it is travelling *along* has not run into it.
@@ -713,7 +721,25 @@ export function shapecastWorld(bodies, tree, shape, pose, dx, dy, dz, out, filte
                 touched = true;
                 break;
             }
-            t += gap / travel;
+            /*
+             * **How far the shapes may close along the contact normal, not along the travel.** The
+             * manifold's normal separates the two by `gap`, so they cannot meet before the sweep has
+             * closed that much along it. Dividing by the whole travel was always safe and crawled
+             * wherever the travel grazes the surface: a ball dropping past the lip of a step closes on it
+             * at a sixth of its speed, and twenty-four steps ended before it arrived, so the sweep said
+             * nothing was there. A mesh keeps the old step, since one triangle's normal does not separate
+             * the whole mesh.
+             */
+            if (isMesh(shape) || isMesh(other)) {
+                t += gap / travel;
+            }
+            else {
+                const closing = dx * manifold.nx + dy * manifold.ny + dz * manifold.nz;
+                // Not closing along the normal that separates them, so they never meet on this travel.
+                if (closing <= 1e-12)
+                    break;
+                t += gap / closing;
+            }
             if (t > 1)
                 break;
         }

package/dist/ragdoll.d.ts

@@ -88,7 +88,15 @@ export interface Ragdoll {
     readonly bodyOf: Int32Array;
     /** How many bones were built. */
     readonly boneCount: number;
-    /** Write the ragdoll's current shape into a pose. */
+    /**
+     * Write the ragdoll's current shape into a pose.
+     *
+     * Each joint is turned by the bone that **starts** at it, which is the joint a skinned limb
+     * follows — the forearm's body turns the elbow — and a joint with no bone below it rides the one
+     * it hangs off. Translations are the rig's own, in each parent's frame. A root's rotation is
+     * written in the frame the character's node is placed in, at `rootX`, `rootY` and `rootZ`, with
+     * no rotation of its own; a joint no bone reaches is left as the pose had it.
+     */
     writePose(out: PoseTarget): void;
     /** Steer the bodies toward a pose. Weight 1 tracks it, weight 0 goes limp. */
     drive(world: PhysicsWorld, pose: PoseTarget, weight: number): void;