@driftengine/physics 3.61.0

package/dist/controller.js

@@ -0,0 +1,641 @@
+import { BODY_DYNAMIC } from './bodies.js';
+import { createRayHit } from './query.js';
+import { capsuleShape, sphereShape } from './shape.js';
+/**
+ * A kinematic capsule character: the mechanism, and the feel that rides on it.
+ *
+ * **Kinematic and not a dynamic body.** A dynamic character falls over, cannot be steered crisply,
+ * and turns every design question about movement into a question about torque. Every shipping
+ * engine ships a kinematic controller for exactly that reason, and this one sweeps the same
+ * `PhysicsWorld` everything else queries, so it sees moving bodies as well as scenery.
+ *
+ * **Feel is here too, and that is a decision `AGENTS.md` records.** That file's worked example for
+ * the engine/game boundary once said a controller was game because "friction, coyote time and slide
+ * boost are one game's feel". The same file's *audio* rule draws the line correctly: the DSP graph
+ * is engine and which sounds play is game. A controller that takes a friction curve and a
+ * coyote-time duration takes numbers and time, which is what that file says engine APIs take; what
+ * stays game is which numbers. **What would make this wrong** is a parameter that only means
+ * something in one game.
+ *
+ * **Coyote time and jump buffering are counted in ticks**, never accumulated in a float of seconds.
+ * That is the determinism contract reaching into the feel layer, and the difference between a
+ * replay that matches and one that drifts by a frame after an hour of uptime.
+ */
+export const GROUNDED = 0;
+export const AIRBORNE = 1;
+export const SLIDING = 2;
+/** How many sweep-and-slide passes one move takes. Fixed, because a tolerance loop is banned. */
+const SLIDE_PASSES = 4;
+/**
+ * How far below the feet a snap looks. Not a skin.
+ *
+ * There was a skin here, subtracted from the sweep as `fraction − SKIN / travel`, and it made the
+ * controller **stop moving entirely** whenever a move was shorter than the skin: a character
+ * sliding downhill at a tenth of a metre per second travels 0.0017 m a tick, the term came to ten,
+ * the fraction clamped to zero, and it stood still on a slope it should have slid down. The sweep's
+ * own stop margin already leaves a tenth of a millimetre of clearance, which is what a skin was for.
+ */
+const SNAP_EPS = 0.001;
+export class CharacterController {
+    x = 0;
+    y = 0;
+    z = 0;
+    velX = 0;
+    velY = 0;
+    velZ = 0;
+    state = AIRBORNE;
+    /** The surface normal under the feet, meaningful when grounded or sliding. */
+    groundX = 0;
+    groundY = 1;
+    groundZ = 0;
+    /**
+     * Which way is up for this body, as a unit vector. World up unless a caller says otherwise.
+     *
+     * **The whole of this class used to assume one axis, and none of it was wrong for doing so.**
+     * `velY` was the only representation of vertical velocity, `gravity` was a scalar applied to it,
+     * `slopeCos` was measured against world Y, `stepHeight` was a height only because up was fixed,
+     * and the three states were decided by a downward probe. That is a complete and correct
+     * controller for a body on a floor, and it cannot represent one on a wall at all.
+     *
+     * A consumer needing one had to reimplement the sweep, the step-over, the slope test and the
+     * ground probe — roughly nine hundred lines that would not share this file's contact code, so
+     * the two would drift. It is not a gecko's problem: it is every wall-crawler, every
+     * arbitrary-gravity level and every walker on the inside of a rotating station.
+     *
+     * Settable per tick, because a body walking around a corner changes frame continuously and the
+     * alternative is rebuilding the controller. Read through `setUp`, which normalises, so the dot
+     * products below can assume unit length.
+     */
+    upX = 0;
+    upY = 1;
+    upZ = 0;
+    /**
+     * Which way this body falls, which is not always the way it stands.
+     *
+     * Tracks `up` until a caller sets it, and that default is the one that keeps every existing
+     * consumer unchanged. Kept separate because a support normal and a fall direction are different
+     * questions: a body clinging to a wall stands in the wall's frame and may still fall the way the
+     * world falls the moment it lets go.
+     */
+    gravityX = 0;
+    gravityY = 1;
+    gravityZ = 0;
+    /** Whether `setUp` should carry the fall direction with it. Cleared by `setGravityDirection`. */
+    gravityFollowsUp = true;
+    /** Which body is being stood on, or −1. */
+    groundBody = -1;
+    shape;
+    /**
+     * A ball the size of the capsule's foot, swept down to find ground.
+     *
+     * **A single ray from the capsule's axis is not enough**, and the failure is specific: a character
+     * balanced on the lip of a step has its axis over open air, the ray misses, it is reported
+     * airborne, and stepping is disabled — so it stalls on the edge of the very step it was climbing.
+     * A ball finds ground under any part of the foot. It is slightly smaller than the capsule so a
+     * wall pressed against the side cannot be mistaken for a floor.
+     */
+    foot;
+    radius;
+    halfHeight;
+    stepHeight;
+    slopeCos;
+    maxSpeed;
+    acceleration;
+    deceleration;
+    airControl;
+    jumpSpeed;
+    jumpCutoff;
+    gravity;
+    coyoteTicks;
+    jumpBufferTicks;
+    slideBoost;
+    pushStrength;
+    filter;
+    /** Ticks since the character last had ground under it. */
+    airTicks = 0;
+    /** Ticks since a jump was pressed and not yet used. */
+    bufferTicks = -1;
+    jumpHeld = false;
+    rising = false;
+    pose = { x: 0, y: 0, z: 0, qx: 0, qy: 0, qz: 0, qw: 1 };
+    hit = createRayHit();
+    /** `tryStep` needs its own, because it sweeps twice and `hit` is still being read afterwards. */
+    stepHit = createRayHit();
+    ground = createRayHit();
+    /** The analytic surface, where a consumer supplied one. See `GroundProbe`. */
+    probe;
+    /** Scratch for the probe, claimed once: `senseGround` runs every tick. */
+    probed = {
+        y: 0,
+        normalX: 0,
+        normalY: 1,
+        normalZ: 0,
+    };
+    constructor(options = {}) {
+        this.radius = options.radius ?? 0.35;
+        this.halfHeight = options.halfHeight ?? 0.6;
+        this.shape = capsuleShape(this.radius, this.halfHeight);
+        this.foot = sphereShape(this.radius * 0.95);
+        this.stepHeight = options.stepHeight ?? 0.35;
+        this.slopeCos = options.slopeCos ?? 0.7;
+        this.maxSpeed = options.maxSpeed ?? 5;
+        this.acceleration = options.acceleration ?? 40;
+        this.deceleration = options.deceleration ?? 30;
+        this.airControl = options.airControl ?? 0.3;
+        this.jumpSpeed = options.jumpSpeed ?? 6;
+        this.jumpCutoff = options.jumpCutoff ?? 0.4;
+        this.gravity = options.gravity ?? -20;
+        this.coyoteTicks = options.coyoteTicks ?? 6;
+        this.jumpBufferTicks = options.jumpBufferTicks ?? 6;
+        this.slideBoost = options.slideBoost ?? 8;
+        this.pushStrength = options.pushStrength ?? 1;
+        this.filter = options.filter;
+        this.probe = options.ground ?? null;
+    }
+    /**
+     * Point this body's up at a direction, normalising it.
+     *
+     * A zero-length vector is refused rather than normalised into a NaN frame, because every dot
+     * product below would then answer NaN and the states would read as a body that is nowhere. It
+     * keeps the frame it had, which is the defined state the two-backends rule asks for in the
+     * renderer and is the right answer here for the same reason.
+     */
+    setUp(x, y, z) {
+        const length = Math.sqrt(x * x + y * y + z * z);
+        if (length < 1e-6)
+            return;
+        this.upX = x / length;
+        this.upY = y / length;
+        this.upZ = z / length;
+        if (this.gravityFollowsUp) {
+            this.gravityX = this.upX;
+            this.gravityY = this.upY;
+            this.gravityZ = this.upZ;
+        }
+    }
+    /**
+     * Point the fall direction somewhere other than up, and stop it following.
+     *
+     * The sign convention is `up`'s: `gravity` is negative, so this is the direction a *rise* goes
+     * and gravity is applied against it. That is the same arithmetic as before — `velY += gravity *
+     * dt` with a gravity of −20 is an acceleration along −Y — generalised rather than reversed.
+     */
+    setGravityDirection(x, y, z) {
+        const length = Math.sqrt(x * x + y * y + z * z);
+        if (length < 1e-6)
+            return;
+        this.gravityX = x / length;
+        this.gravityY = y / length;
+        this.gravityZ = z / length;
+        this.gravityFollowsUp = false;
+    }
+    /** This body's speed along its own up. What `velY` was when up was always world Y. */
+    get speedAlongUp() {
+        return this.velX * this.upX + this.velY * this.upY + this.velZ * this.upZ;
+    }
+    /** Set that component, leaving the tangent velocity exactly as it was. */
+    setSpeedAlongUp(speed) {
+        const delta = speed - this.speedAlongUp;
+        this.velX += this.upX * delta;
+        this.velY += this.upY * delta;
+        this.velZ += this.upZ * delta;
+    }
+    /** Place the character, clearing whatever it was doing. */
+    teleport(x, y, z) {
+        this.x = x;
+        this.y = y;
+        this.z = z;
+        this.velX = 0;
+        this.velY = 0;
+        this.velZ = 0;
+        this.state = AIRBORNE;
+        this.airTicks = this.coyoteTicks + 1;
+    }
+    /** Advance one fixed tick. */
+    move(world, dt, input) {
+        this.senseGround(world);
+        this.applyFeel(dt, input);
+        this.sweep(world, dt);
+        this.standOnSurface(dt);
+        this.senseGround(world);
+    }
+    /**
+     * Let the analytic surface stop a descent, the way a body would have.
+     *
+     * **Without this a probe is a sensor and not a floor, and that was the shape of it until
+     * 2026-08-28.** `senseGround` read the surface and set `GROUNDED`, and nothing anywhere put the
+     * feet back on it: the sweep resolves bodies, the surface is not a body, so a character over a
+     * purely analytic world sank through it at gravity. It reported `GROUNDED` for three ticks while
+     * the gap stayed inside the six-centimetre tolerance, then went airborne and fell for ever —
+     * measured at ten metres under the floor after one second. Every test the seam had ran a single
+     * tick from feet already exactly on the surface, which is the one arrangement that cannot see it.
+     *
+     * A consumer with terrain therefore had to hold their own character up, which is the hundred
+     * lines they reported writing, and to write them again for anything else that stands on ground.
+     *
+     * **Only a descent this tick could have caused, which is what keeps it a floor rather than a
+     * magnet.** A character that is under the surface by more than this tick's fall is under it for
+     * some other reason — spawned in a cellar, walked into a tunnel, thrown through by an impulse —
+     * and hoisting them would be teleporting them through whatever is over their head. Rising is left
+     * alone entirely, so a jump leaves.
+     */
+    standOnSurface(dt) {
+        /*
+         * **A `GroundProbe` answers a height for an (x, z), so it describes a world-Y surface and
+         * nothing else.** There is no reading of it in a tilted frame: `sample(x, z)` has already
+         * chosen which axis is vertical. So this holds a body up only in the frame the probe is
+         * written in, and a consumer standing on a wall is standing on a collider rather than on an
+         * analytic surface. Skipped rather than approximated, because an approximation here is a body
+         * hoisted along the wrong axis, which is worse than not being hoisted.
+         */
+        if (this.upY < 0.999)
+            return;
+        if (this.probe === null || this.velY > 0)
+            return;
+        const feet = this.y - this.halfHeight - this.radius;
+        if (!this.probe.sample(this.x, this.z, this.probed, this.y))
+            return;
+        const sunk = this.probed.y - feet;
+        if (sunk < 0)
+            return;
+        /* This tick's fall, plus the same tolerance `senseGround` calls standing on something. */
+        if (sunk > -this.velY * dt + 0.06)
+            return;
+        this.y = this.probed.y + this.halfHeight + this.radius;
+        this.velY = 0;
+    }
+    /* ---------- feel ---------- */
+    applyFeel(dt, input) {
+        const grounded = this.state === GROUNDED;
+        if (grounded)
+            this.airTicks = 0;
+        else
+            this.airTicks++;
+        // Edge detection and buffering, both in ticks.
+        if (input.jump && !this.jumpHeld)
+            this.bufferTicks = 0;
+        else if (this.bufferTicks >= 0)
+            this.bufferTicks++;
+        if (this.bufferTicks > this.jumpBufferTicks)
+            this.bufferTicks = -1;
+        this.jumpHeld = input.jump;
+        // Steering, with less authority in the air.
+        let wantX = input.moveX;
+        let wantY = input.moveY ?? 0;
+        let wantZ = input.moveZ;
+        const want = Math.sqrt(wantX * wantX + wantY * wantY + wantZ * wantZ);
+        if (want > this.maxSpeed) {
+            wantX = (wantX / want) * this.maxSpeed;
+            wantY = (wantY / want) * this.maxSpeed;
+            wantZ = (wantZ / want) * this.maxSpeed;
+        }
+        const authority = grounded ? 1 : this.airControl;
+        const rate = want > 0 ? this.acceleration : this.deceleration;
+        const step = rate * authority * dt;
+        /*
+         * **Steering happens in the tangent plane, and the input is read as a world direction.**
+         *
+         * With up at world Y and no `moveY`, this is exactly what it was: the wanted vector has no Y
+         * component, the projection removes nothing, and approaching the three components approaches
+         * `velX` and `velZ` while leaving `velY` alone. With up anywhere else, the same input describes
+         * a direction in the world that is flattened onto the surface the body is standing on, which is
+         * what a caller means by "forward" when forward is along a wall — and `moveY` is what lets that
+         * direction leave the world XZ plane at all. See `ControllerInput.moveY`.
+         *
+         * The speed along up is held out and put back rather than being steered, because it belongs to
+         * gravity and the jump and not to the stick.
+         *
+         * **Unless the caller says the command is already the velocity it wants**, which is a body
+         * between two surfaces and is the one case this plane is the wrong one to read in. See
+         * `ControllerInput.projectMove`. The whole vector is steered then, at the same rate and under
+         * 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);
+        }
+        else {
+            const alongUp = this.speedAlongUp;
+            let tangentX = this.velX - this.upX * alongUp;
+            let tangentY = this.velY - this.upY * alongUp;
+            let tangentZ = this.velZ - this.upZ * alongUp;
+            const wantIntoUp = wantX * this.upX + wantY * this.upY + wantZ * this.upZ;
+            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);
+            this.velX = tangentX + this.upX * alongUp;
+            this.velY = tangentY + this.upY * alongUp;
+            this.velZ = tangentZ + this.upZ * alongUp;
+        }
+        if (this.state === SLIDING) {
+            /*
+             * Downhill along the surface: the gravity direction projected onto the plane. A slide that
+             * simply disabled control would leave a character stuck on a slope it cannot climb, which
+             * reads as being caught on geometry rather than as sliding.
+             */
+            const n = this.groundX * this.upX + this.groundY * this.upY + this.groundZ * this.upZ;
+            const downX = -(this.groundX - this.upX * n) * n;
+            const downY = -(this.groundY - this.upY * n) * n;
+            const downZ = -(this.groundZ - this.upZ * n) * n;
+            this.velX += downX * this.slideBoost * dt;
+            this.velY += downY * this.slideBoost * dt;
+            this.velZ += downZ * this.slideBoost * dt;
+        }
+        this.velX += this.gravityX * this.gravity * dt;
+        this.velY += this.gravityY * this.gravity * dt;
+        this.velZ += this.gravityZ * this.gravity * dt;
+        if (this.speedAlongUp <= 0)
+            this.rising = false;
+        // A jump is allowed while grounded, or within coyote ticks of having been.
+        const mayJump = this.airTicks <= this.coyoteTicks && this.state !== SLIDING;
+        if (this.bufferTicks >= 0 && mayJump) {
+            this.setSpeedAlongUp(this.jumpSpeed);
+            this.bufferTicks = -1;
+            this.airTicks = this.coyoteTicks + 1;
+            this.rising = true;
+            this.state = AIRBORNE;
+        }
+        else if (this.rising && !input.jump) {
+            // Released early: cut the rise, which is what makes a tap shorter than a hold.
+            this.setSpeedAlongUp(this.speedAlongUp * this.jumpCutoff);
+            this.rising = false;
+        }
+    }
+    /* ---------- mechanism ---------- */
+    /**
+     * Sweep, slide along whatever was hit, and try again — a fixed number of times.
+     *
+     * A step is attempted before sliding: lift by the step height, sweep forward, and drop. A
+     * character that slid off every lip would catch on kerbs and stair nosings, which reads as the
+     * world being sticky rather than as the character being short.
+     */
+    sweep(world, dt) {
+        let dx = this.velX * dt;
+        let dy = this.velY * dt;
+        let dz = this.velZ * dt;
+        for (let pass = 0; pass < SLIDE_PASSES; pass++) {
+            const travel = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            if (travel < 1e-6)
+                return;
+            this.readPose();
+            if (!world.shapecast(this.shape, this.pose, dx, dy, dz, this.hit, this.filter)) {
+                this.x += dx;
+                this.y += dy;
+                this.z += dz;
+                return;
+            }
+            const t = this.hit.fraction;
+            this.x += dx * t;
+            this.y += dy * t;
+            this.z += dz * t;
+            this.push(world, this.hit.body, this.hit.nx, this.hit.ny, this.hit.nz);
+            let remainX = dx * (1 - t);
+            let remainY = dy * (1 - t);
+            let remainZ = dz * (1 - t);
+            /*
+             * Try to step over the lip before sliding along it. The normal is read out first, because
+             * `tryStep` sweeps twice and the projection below still needs it — sharing one `RayHit`
+             * between them left the slide projecting against whatever the step's own sweep last found,
+             * which stopped the character dead at every kerb.
+             */
+            const hx = this.hit.nx;
+            const hy = this.hit.ny;
+            const hz = this.hit.nz;
+            const intoUp = hx * this.upX + hy * this.upY + hz * this.upZ;
+            if (intoUp < this.slopeCos &&
+                this.state === GROUNDED &&
+                this.tryStep(world, remainX, remainY, remainZ)) {
+                return;
+            }
+            // Project what is left onto the surface, which is what turns a stop into a slide.
+            const into = remainX * hx + remainY * hy + remainZ * hz;
+            remainX -= hx * into;
+            remainY -= hy * into;
+            remainZ -= hz * into;
+            const vInto = this.velX * hx + this.velY * hy + this.velZ * hz;
+            if (vInto < 0) {
+                this.velX -= hx * vInto;
+                this.velY -= hy * vInto;
+                this.velZ -= hz * vInto;
+            }
+            dx = remainX;
+            dy = remainY;
+            dz = remainZ;
+        }
+    }
+    /**
+     * Lift, sweep forward, drop. Returns whether the whole step was taken.
+     *
+     * **The lift and the drop are along this body's up rather than along world Y**, which is what
+     * makes `stepHeight` a height rather than a Y offset. The forward part is the remainder of the
+     * move flattened into the tangent plane, for the same reason: what is left of a blocked move
+     * includes whatever of it was along up, and lifting by the step height and then also moving up
+     * would climb twice.
+     */
+    tryStep(world, dx, dy, dz) {
+        const startX = this.x;
+        const startY = this.y;
+        const startZ = this.z;
+        const liftX = this.upX * this.stepHeight;
+        const liftY = this.upY * this.stepHeight;
+        const liftZ = this.upZ * this.stepHeight;
+        const intoUp = dx * this.upX + dy * this.upY + dz * this.upZ;
+        const flatX = dx - this.upX * intoUp;
+        const flatY = dy - this.upY * intoUp;
+        const flatZ = dz - this.upZ * intoUp;
+        this.x += liftX;
+        this.y += liftY;
+        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;
+        }
+        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;
+        }
+        // Nothing beneath the lifted position, so this was a gap rather than a step.
+        this.x = startX;
+        this.y = startY;
+        this.z = startZ;
+        return false;
+    }
+    /**
+     * Sweep the foot ball down, and fall back to a ray when what it finds is not walkable.
+     *
+     * The ball is what lets a character stand on the lip of a step: a ray from the capsule's axis has
+     * open air beneath it there, reports airborne, and disables the stepping that was carrying it up.
+     *
+     * **But a ball also brushes the side of the ledge it is walking off**, and a wall's normal is
+     * horizontal, so the ball alone reported *sliding* — which refused the coyote-time jump the
+     * character had every right to. So a non-walkable ball result is not trusted on its own: a ray
+     * down the axis decides whether there is genuinely a steep surface underfoot, or merely a wall
+     * beside it. Two cheap queries, and each covers the other's blind spot.
+     */
+    senseGround(world) {
+        this.readPose();
+        this.pose.x = this.x - this.upX * this.halfHeight;
+        this.pose.y = this.y - this.upY * this.halfHeight;
+        this.pose.z = this.z - this.upZ * this.halfHeight;
+        const reach = this.radius * 0.05 + 0.06;
+        if (world.shapecast(this.foot, this.pose, -this.upX * reach, -this.upY * reach, -this.upZ * reach, this.ground, this.filter)) {
+            const intoUp = this.ground.nx * this.upX + this.ground.ny * this.upY + this.ground.nz * this.upZ;
+            if (intoUp >= this.slopeCos) {
+                this.groundX = this.ground.nx;
+                this.groundY = this.ground.ny;
+                this.groundZ = this.ground.nz;
+                this.groundBody = this.ground.body;
+                this.state = GROUNDED;
+                return;
+            }
+        }
+        const axis = this.halfHeight + this.radius + 0.06;
+        if (!world.raycast(this.x, this.y, this.z, -this.upX, -this.upY, -this.upZ, axis, this.ground, this.filter)) {
+            /*
+             * Nothing solid under the feet. Ask the surface, where there is one — a banked deck is
+             * exactly the case a collider answers badly, and a consumer with one would otherwise be
+             * reported airborne while standing on it.
+             *
+             * Asked last rather than first, and that ordering is the decision: a body is a thing that
+             * is *there* and a surface is a description of where the ground *is*, so anything solid
+             * wins. A consumer with no probe reaches none of this.
+             */
+            if (this.probe !== null) {
+                const feet = this.y - this.halfHeight - this.radius;
+                if (this.probe.sample(this.x, this.z, this.probed, this.y) &&
+                    this.probed.y <= feet + 0.06) {
+                    if (feet - this.probed.y <= 0.06) {
+                        this.groundX = this.probed.normalX;
+                        this.groundY = this.probed.normalY;
+                        this.groundZ = this.probed.normalZ;
+                        /* No body holds this character up, and −1 is what that has always meant. */
+                        this.groundBody = -1;
+                        this.state = this.probed.normalY >= this.slopeCos ? GROUNDED : SLIDING;
+                        return;
+                    }
+                }
+            }
+            this.state = AIRBORNE;
+            this.groundBody = -1;
+            return;
+        }
+        this.groundX = this.ground.nx;
+        this.groundY = this.ground.ny;
+        this.groundZ = this.ground.nz;
+        this.groundBody = this.ground.body;
+        this.state = this.ground.ny >= this.slopeCos ? GROUNDED : SLIDING;
+    }
+    /*
+     * **There was a `snapToGround` here and it is gone, because it was measured and did nothing.**
+     *
+     * The idea is standard: horizontal speed can carry the feet past a crest faster than gravity
+     * pulls them down, so a controller pulls them back onto a surface just below. This one never
+     * fired at all at first — it ran only while still grounded, and at a crest the ground sense has
+     * already said airborne — and once that ordering was fixed it made the result *worse*. Descending
+     * a sharp forty-degree crest at six metres a second, the largest gap between the feet and the
+     * surface was **0.490 metres with it and 0.457 without**, over 120 ticks.
+     *
+     * The sweep-and-slide already follows a surface closely enough that there is nothing left for a
+     * snap to correct, because the slide projection puts the remaining motion *along* the surface
+     * rather than through it. **What would bring it back** is a measurement showing a visible hop at
+     * a crest that the slide does not absorb — at which point the instrument to build first is the
+     * foot-gap probe above, not the airborne-tick count, which reports a state rather than a distance
+     * and called this feature useful when it was inert.
+     */
+    /**
+     * Push a dynamic body the character walked into, so a crate is not a wall.
+     *
+     * **The push carries the character's speed, not its per-tick step.** Adding the displacement —
+     * four metres a second comes to 0.067 of a metre in a tick — is less than the impulse ground
+     * friction takes off a crate in the same tick, so the crate is pushed and immediately stopped and
+     * never moves at all. Measured: a 30 kg crate under 0.5 friction shed 0.082 a tick against 0.067
+     * put in.
+     *
+     * So it sets a *target* rather than accumulating: the body is brought up to the character's own
+     * speed into the surface, scaled by `pushStrength`, and never slowed if it is already faster.
+     * **What this gives up** is momentum transfer — a heavy crate moves as readily as a light one,
+     * because a kinematic character has no mass to trade. **What would make it wrong** is a consumer
+     * wanting mass to matter, and the answer then is a dynamic character, which §12 refuses for
+     * reasons that have nothing to do with this.
+     */
+    push(world, body, nx, ny, nz) {
+        if (body < 0 || this.pushStrength === 0)
+            return;
+        if (world.bodies.type[body] !== BODY_DYNAMIC)
+            return;
+        if ((world.bodies.invMass[body] ?? 0) === 0)
+            return;
+        // The surface normal points at the character, so the push goes the other way.
+        const into = -(this.velX * nx + this.velY * ny + this.velZ * nz);
+        if (into <= 0)
+            return;
+        const want = into * this.pushStrength;
+        const already = -((world.bodies.velX[body] ?? 0) * nx +
+            (world.bodies.velY[body] ?? 0) * ny +
+            (world.bodies.velZ[body] ?? 0) * nz);
+        if (already >= want)
+            return;
+        const add = want - already;
+        world.bodies.velX[body] = (world.bodies.velX[body] ?? 0) - nx * add;
+        world.bodies.velY[body] = (world.bodies.velY[body] ?? 0) - ny * add;
+        world.bodies.velZ[body] = (world.bodies.velZ[body] ?? 0) - nz * add;
+        world.wakeIsland(body);
+    }
+    /**
+     * The capsule at this body's position, standing along this body's up.
+     *
+     * **The quaternion used to be left at identity**, which was right while up was always world Y
+     * and is the one thing that cannot be left out once it is not: a body on a wall whose capsule is
+     * still world-vertical is swept against the wall by its side rather than its foot, so it rests a
+     * radius away instead of standing on it.
+     *
+     * The shortest arc from world Y to `up`, built directly rather than through an axis-angle,
+     * because the half-angle form is one square root. **The half turn is the case that has to be
+     * written out**: an up of exactly −Y makes the cross product zero and `w` zero with it, which
+     * normalises to NaN, and there is no shortest arc to pick because every arc is the same length.
+     * A turn about X is chosen, which is as good as any and is stable.
+     */
+    readPose() {
+        this.pose.x = this.x;
+        this.pose.y = this.y;
+        this.pose.z = this.z;
+        const w = 1 + this.upY;
+        if (w < 1e-6) {
+            this.pose.qx = 1;
+            this.pose.qy = 0;
+            this.pose.qz = 0;
+            this.pose.qw = 0;
+            return;
+        }
+        const qx = this.upZ;
+        const qz = -this.upX;
+        const inverse = 1 / Math.sqrt(qx * qx + qz * qz + w * w);
+        this.pose.qx = qx * inverse;
+        this.pose.qy = 0;
+        this.pose.qz = qz * inverse;
+        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;
+}