@driftengine/physics 3.61.0

package/dist/stallEscape.js

@@ -0,0 +1,254 @@
+import { AXIS_X, AXIS_Y, AXIS_Z, moveAxis } from './collide/index.js';
+/**
+ * A kinematic body that has stopped making progress: find the cheapest way out, or say it is
+ * sealed.
+ *
+ * **Nothing else in this engine does this, and every rule in it was paid for in a shipping game.**
+ * A character controller resolves a move against geometry; it has no opinion about a body that has
+ * been asking to move for half a second and going nowhere. That gap is where players get stuck,
+ * and the cases are specific enough that a consumer meeting them for the first time will get them
+ * wrong in the same order everybody does:
+ *
+ * - a lamp base that arrests a fall on a contact no rule calls support, so the body is *grounded*
+ *   and cannot jump;
+ * - a notch with a ceiling a hand's width overhead, where every jump lifts three centimetres and
+ *   drops back — so a per-tick displacement test never arms, while the body sits at the same
+ *   coordinates for as long as the key is held;
+ * - a deck edge that carries **no collider at all**, refused from a ground query alone, so a
+ *   horizontal probe reports clear air and taking it walks the body into a slab;
+ * - an analytic deck that lifts a body back every tick it is pushed down, which with a collider
+ *   set that reports clear air below is a treadmill neither system is wrong about;
+ * - two columns a body will never fit between, where a held input undoes every nudge — a player
+ *   who was never stuck, and who must not be killed for pressing into a wall;
+ * - and a player merely *leaning* on scenery, who is not stuck at all and for whom being carried
+ *   sideways at a fixed rate with the controls doing nothing reads as the game shoving them.
+ *
+ * **Sealed is reported, never acted on.** This says there is nowhere to put the body; what that
+ * costs a player is the consumer's decision, and a capability that killed a character would be
+ * making a game's.
+ */
+/** Nothing happened: the body is getting somewhere, is not asking, or can jump out. */
+/**
+ * A vector's length, and **`Math.sqrt` rather than `Math.hypot`**.
+ *
+ * ECMAScript specifies `sqrt` exactly — it is one of the two operations it pins to IEEE-754 — and
+ * leaves `hypot` to the implementation, so two engines may disagree by an ulp. A solver whose
+ * replays and ghosts have to match cannot spend that, and `scripts/determinism.test.mjs` refuses it
+ * by name.
+ *
+ * What `hypot` buys and this gives up is intermediate overflow at magnitudes near `1e154` and
+ * underflow near `1e-162`. These are metres.
+ */
+function length(x, y, z) {
+    return Math.sqrt(x * x + y * y + z * z);
+}
+export const ESCAPE_IDLE = 0;
+/** The body was pushed along `axis`/`sign`, through the sweep, so geometry still decided. */
+export const ESCAPE_PUSHED = 1;
+/** Nothing had room, so the body was eased upward by hand. */
+export const ESCAPE_EASED = 2;
+/** No room in any of the six directions, and the budget is spent. The consumer decides. */
+export const ESCAPE_SEALED = 3;
+export class StallEscape {
+    /** Which axis the last push took, and which way along it. Read after `ESCAPE_PUSHED`. */
+    axis = AXIS_Y;
+    sign = 1;
+    progressM;
+    stalledTicks;
+    refusedTicksNeeded;
+    pushM;
+    budgetM;
+    probeM;
+    headroomM;
+    verticalBias;
+    stalled = 0;
+    refused = 0;
+    spent = 0;
+    anchorX = 0;
+    anchorY = 0;
+    anchorZ = 0;
+    anchored = false;
+    lastX = 0;
+    lastY = 0;
+    lastZ = 0;
+    constructor(options = {}) {
+        this.progressM = options.progressM ?? 0.5;
+        this.stalledTicks = options.stalledTicks ?? 30;
+        this.refusedTicksNeeded = options.refusedTicks ?? 20;
+        this.pushM = options.pushM ?? 0.04;
+        this.budgetM = options.budgetM ?? 4;
+        this.probeM = options.probeM ?? 0.4;
+        this.headroomM = options.headroomM ?? 0.5;
+        this.verticalBias = options.verticalBias ?? 0.35;
+    }
+    /** Back to watching, for a respawn or a restart. */
+    reset() {
+        this.stalled = 0;
+        this.refused = 0;
+        this.spent = 0;
+        this.anchored = false;
+    }
+    /**
+     * Watch this tick, and act where the body has genuinely stopped getting anywhere.
+     *
+     * Call it last in a tick, after the move has been resolved: it reads where the body ended up.
+     */
+    step(body, colliders, input, veto) {
+        const escaping = this.spent > 0;
+        if (!this.anchored) {
+            this.anchorX = body.x;
+            this.anchorY = body.y;
+            this.anchorZ = body.z;
+            this.lastX = body.x;
+            this.lastY = body.y;
+            this.lastZ = body.z;
+            this.anchored = true;
+        }
+        if (!escaping) {
+            const fromAnchor = length(body.x - this.anchorX, body.y - this.anchorY, body.z - this.anchorZ);
+            if (!input.trying || fromAnchor > this.progressM)
+                return this.standDown(body);
+            if (input.refused)
+                this.refused++;
+            if (++this.stalled < this.stalledTicks) {
+                this.remember(body);
+                return ESCAPE_IDLE;
+            }
+            /* And the world was pushing back for most of it. See `refused`. */
+            if (this.refused < this.refusedTicksNeeded)
+                return this.standDown(body);
+        }
+        /*
+         * Under way again — by more than the push itself. An escape clears any small threshold by
+         * construction, so measuring against one would have it read its own nudge as success and
+         * stand down on the tick after it starts.
+         */
+        const moved = length(body.x - this.lastX, body.y - this.lastY, body.z - this.lastZ);
+        this.remember(body);
+        if (escaping && moved > this.pushM * 2) {
+            this.stalled = 0;
+            this.refused = 0;
+            this.spent = 0;
+            return ESCAPE_IDLE;
+        }
+        /*
+         * **A body that can jump out is not stuck**, and asking here rather than at the top means the
+         * probe is paid for only on the rare tick where something is about to be pushed.
+         */
+        if (this.canJumpOut(body, colliders, input))
+            return this.standDown(body);
+        if (this.spent >= this.budgetM) {
+            this.stalled = 0;
+            this.refused = 0;
+            this.spent = 0;
+            /*
+             * **Asked without the veto, because this question is a different one.** Above, the veto
+             * answers *which way out is worth taking*; here the answer decides whether the consumer is
+             * told there is nowhere to put the body, and a direction that exists but gets undone is not
+             * the same thing as no direction at all. Conflating them turned a body wedged under a deck,
+             * which had real room below it, into one reported as sealed for holding forward.
+             */
+            return this.bestEscape(body, colliders, undefined) <= this.pushM
+                ? ESCAPE_SEALED
+                : ESCAPE_IDLE;
+        }
+        const room = this.bestEscape(body, colliders, veto);
+        this.spent += this.pushM;
+        if (room <= this.pushM) {
+            /*
+             * Genuinely enclosed — no direction has room for even one push. The vertical ease by hand is
+             * the only move left, and it is what this whole mechanism was originally written for: a
+             * pocket at an intersection that no single axis can retrace.
+             */
+            body.y += this.pushM;
+            this.remember(body);
+            return ESCAPE_EASED;
+        }
+        /*
+         * Otherwise take the freest direction, **through the sweep** so solid geometry still decides.
+         *
+         * Which is the whole point: an earlier version *bailed* whenever any direction had room, on
+         * the reasoning that a body with room is not wedged — true, and beside the point. Both of the
+         * traps this exists for had two free directions the entire time; what neither had was a way
+         * for the *consumer's inputs* to reach one, because holding forward asks for the direction
+         * that is refused and a dead stop asks for nothing at all. A body with somewhere to go and no
+         * way to get there is stuck, and the sum over six probes cannot tell the difference.
+         */
+        moveAxis(body, colliders, this.axis, this.sign * this.pushM);
+        this.remember(body);
+        return ESCAPE_PUSHED;
+    }
+    /** Clear the window and re-anchor where the body is now. */
+    standDown(body) {
+        this.stalled = 0;
+        this.refused = 0;
+        this.spent = 0;
+        this.anchorX = body.x;
+        this.anchorY = body.y;
+        this.anchorZ = body.z;
+        this.remember(body);
+        return ESCAPE_IDLE;
+    }
+    remember(body) {
+        this.lastX = body.x;
+        this.lastY = body.y;
+        this.lastZ = body.z;
+    }
+    /**
+     * Is the body standing on something, with room over its head to get off it?
+     *
+     * The one question that separates a trap from a player leaning on scenery. **Grounded** and
+     * **supported** are two different facts; **headroom** is what the notch lacked.
+     *
+     * Probed through the sweep rather than assumed, and the body is put back: a question may not
+     * move anything.
+     */
+    canJumpOut(body, colliders, input) {
+        if (!input.grounded || !input.supported)
+            return false;
+        const wasY = body.y;
+        const room = moveAxis(body, colliders, AXIS_Y, this.headroomM);
+        body.y = wasY;
+        return room >= this.headroomM;
+    }
+    /**
+     * The freest of the six axis directions, in metres of room. Writes the winner into
+     * `axis`/`sign`.
+     *
+     * Every probe is undone before the next: a question may not move anything.
+     */
+    bestEscape(body, colliders, veto) {
+        const x = body.x;
+        const y = body.y;
+        const z = body.z;
+        let bestRoom = 0;
+        let bestScore = 0;
+        this.axis = AXIS_Y;
+        this.sign = 1;
+        for (let i = 0; i < 6; i++) {
+            const axis = i < 2 ? AXIS_X : i < 4 ? AXIS_Y : AXIS_Z;
+            const sign = i % 2 === 0 ? 1 : -1;
+            const room = Math.abs(moveAxis(body, colliders, axis, sign * this.probeM));
+            const reached = axis === AXIS_X ? body.x : axis === AXIS_Z ? body.z : 0;
+            body.x = x;
+            body.y = y;
+            body.z = z;
+            if (veto !== undefined &&
+                (axis === AXIS_X || axis === AXIS_Z) &&
+                room > this.pushM &&
+                veto.horizontal(axis, reached)) {
+                continue;
+            }
+            if (veto !== undefined && axis === AXIS_Y && sign < 0 && veto.below())
+                continue;
+            const score = axis === AXIS_Y ? room * this.verticalBias : room;
+            if (score <= bestScore)
+                continue;
+            bestScore = score;
+            bestRoom = room;
+            this.axis = axis;
+            this.sign = sign;
+        }
+        return bestRoom;
+    }
+}

package/dist/sweptStep.d.ts

@@ -0,0 +1,173 @@
+import type { Axis, Body } from './collide/index.ts';
+import type { ColliderSet } from './colliderSet.ts';
+/**
+ * Moving a kinematic body horizontally, one axis at a time, through a world that has opinions.
+ *
+ * **The half a sweep does not cover.** `moveAxis` answers "what stopped me"; it has nothing to say
+ * about whether the thing that stopped you was a kerb you should have stepped over, a face the
+ * world calls solid but carries no collider for, a facet seam you clipped in mid-air, or a corner
+ * that has just trapped you because both axes refused in the same tick. Every one of those is a
+ * rule rather than a query, and every one of them is the same in any game.
+ *
+ * **Three opinions the geometry cannot hold**, taken structurally through `WorldOpinion` — the
+ * third time this package has needed that shape, after `GroundProbe` and `EscapeVeto`, and for the
+ * same reason each time: a consumer with an analytic surface knows things a collider set does not.
+ * A deck drawn as a smooth ribbon carries no boxes at all, so its *edge* is as solid as a wall and
+ * nothing in the collider set says so.
+ *
+ * **What it will not do is decide what you are standing on.** That question drags in every noun a
+ * game has — what the surface is made of, whether it burns, whether it launches you — and it stays
+ * with the consumer. This owns the move; the consumer owns the meaning.
+ */
+/** Anything with a planar velocity the sweep may redirect. */
+export interface SweptState {
+    velX: number;
+    velZ: number;
+}
+/**
+ * What the world knows that its colliders do not.
+ *
+ * Declared structurally, so nothing is imported in either direction.
+ */
+export interface WorldOpinion {
+    /**
+     * Is there a face standing where the body has just moved to, that it can neither step onto nor
+     * pass under? `from` is where it started on `axis`.
+     *
+     * The case this exists for: a deck drawn as a smooth surface carries no collision boxes, so
+     * every one of its edges is scenery. A body walks into the side of a raised slab and keeps
+     * going, which looks exactly like clipping through the world because it is.
+     */
+    blocked(axis: Axis, from: number): boolean;
+    /**
+     * How far the world's own surface would rise to meet a body standing at `(x, z)` with its feet
+     * at `feetY`, or null where it has no opinion. Negative for a descent.
+     */
+    riseTo(x: number, z: number, feetY: number): number | null;
+    /**
+     * Whether the world vouches for its own rises *here*.
+     *
+     * The retry below overrules a collider that refused a move, on the grounds that the surface says
+     * the ground rises to meet it. That is right on ground the world authored as travelable and
+     * wrong everywhere else: a terrace wall, a station lip and a courtyard edge are real, intended walls
+     * and the hull is the only honest answer for them. A consumer with no such distinction answers
+     * the same thing every time and pays nothing.
+     */
+    vouches(): boolean;
+}
+export interface SweptStepOptions {
+    /** How high a lip may be and still be stepped over. */
+    stepHeight?: number;
+    /**
+     * How much of a shortfall counts as a graze rather than a wall, for a body in the air, metres.
+     *
+     * A facet seam is a few centimetres and mid-flight is exactly where one is most likely to be
+     * clipped in passing rather than run into. A genuine wall does not pass it: hit one square and
+     * the move is near zero regardless of how small it was.
+     */
+    grazeM?: number;
+    /**
+     * How wide something has to be before it is scenery rather than a post, metres.
+     *
+     * A deck's own geometry spans most of a cross-section by construction, metres in at least one
+     * direction; a lamp post is fourteen centimetres. The width test alone tells them apart, and it
+     * is what keeps the vouched retry from walking a body through a real obstacle.
+     */
+    propFootprintM?: number;
+    /** How much exploratory lift a vouched retry is worth where the surface reports no rise. */
+    facetClearM?: number;
+    /** A rise smaller than this is not a rise. Matches whatever the consumer's own snap ignores. */
+    riseSlackM?: number;
+    /**
+     * The least horizontal contact normal that counts as a wall.
+     *
+     * Below it the contact is a floor or a ceiling, and redirecting horizontal motion along one of
+     * those would let a body climb.
+     */
+    wallNormalMin?: number;
+    /** How hard a body slides off something it is merely perched on, metres per second squared. */
+    slipAccel?: number;
+    /** The speed a slip starts at, so it is not defeated by a body pressing into the contact. */
+    slipNudge?: number;
+    /** How little movement counts as a slip having achieved nothing, metres. */
+    slipBlockedM?: number;
+    /** How long after a step up a rim is still treated as a plateau rather than a wall, seconds. */
+    stepGraceSec?: number;
+}
+export declare class SweptStep {
+    /**
+     * Whether the world refused a horizontal move this tick.
+     *
+     * Read by anything that wants to tell a body that is stuck from one that is going in circles —
+     * `StallEscape` is the obvious consumer, and the two were written for each other.
+     */
+    moveRefused: boolean;
+    /** Seconds since the last successful step up. See `stepGraceSec`. */
+    sinceStepUp: number;
+    private readonly stepHeight;
+    private readonly grazeM;
+    private readonly propFootprintM;
+    private readonly facetClearM;
+    private readonly riseSlackM;
+    private readonly wallNormalMin;
+    private readonly slipAccel;
+    private readonly slipNudge;
+    private readonly slipBlockedM;
+    private readonly stepGraceSec;
+    /**
+     * Open a tick: forget last tick's refusal and age the step-up grace.
+     *
+     * **Both counters live here or they live in two places**, which is exactly the bug this seam
+     * shipped with for one commit: the consumer kept its own `sinceStepUp`, advanced it, and the
+     * engine's stayed pinned at whatever the last step set — so the grace below never expired and a
+     * body perched on a rim was told, for ever, that it had just climbed onto a plateau.
+     */
+    beginTick(dt: number): void;
+    /**
+     * Scratch for the prop query, claimed once and sized for the worst measured.
+     *
+     * A dense cluster of geometry can return dozens of candidates — measured at 102 in one query on
+     * a wide bank — and a buffer smaller than that silently drops whatever does not fit, dropping
+     * the one post among them exactly as often as it keeps it.
+     */
+    private readonly propProbe;
+    constructor(options?: SweptStepOptions);
+    slipOffContact(body: Body, state: SweptState, dt: number, colliders: ColliderSet): boolean;
+    moveHorizontal(body: Body, state: SweptState, axis: Axis, want: number, colliders: ColliderSet, supported: boolean, world: WorldOpinion): void;
+    /**
+     * Is a standalone prop — not the deck's own wedge geometry — actually
+     * standing anywhere along this axis's swept move? The one distinction the
+     * on-Way trust in `moveHorizontal` cannot make from the smooth surface
+     * alone: the ground query answers for the deck itself, so a lamp, a
+     * brazier's stand or an arch post planted exactly where the deck reads
+     * clear is invisible to it. Real obstacles still have to collide — a lamp
+     * or any other placed item in the path must still register an impact — so
+     * before the deck's own hull is overruled, this asks whether anything
+     * narrow enough to be a *post*
+     * rather than a *slab* occupies the path. The deck's own wedges span most
+     * of a cross-section by construction, metres in at least one horizontal
+     * direction; a lamp post is fourteen centimetres. `this.propFootprintM` sits
+     * comfortably between the two, so the width test alone tells them apart.
+     *
+     * The box spans `before` to the full `want`, not only the endpoint —
+     * `moveAxis` already stopped short of a real prop, so the prop itself sits
+     * somewhere inside that span, never exactly on the far end this checks
+     * against. A box at the endpoint alone missed it outright: placed items
+     * such as lamps were ignored and a body passed straight through them.
+     *
+     * A dense cluster of wedges nearby can return dozens of candidates —
+     * measured at 102 in one query on a wide bank — well past the buffer this
+     * used to carry, which silently dropped whatever did not fit and dropped
+     * the one lamp among them exactly as often as it kept it. `propProbe` is
+     * sized for the worst of what was actually measured, with headroom.
+     */
+    private blockedByProp;
+    /**
+     * Is there a walkable face standing in the body's current column that the character can
+     * neither step onto nor pass under? See `moveHorizontal` for why this exists.
+     *
+     * Uses its own hit rather than `this.hit`, which `resolveSurface` owns for the whole
+     * tick and reads after both axes have moved.
+     */
+    private tryStepUp;
+}