@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/geom/collide/slide.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Move and slide: the character-controller loop a game would otherwise write. `slide` sweeps the
+ * shape along its displacement, stops `skin` short of the first hit, projects what is left of the
+ * displacement onto the hit plane and repeats up to `maxIterations` times. A hit whose normal is
+ * within `maxSlope` of up is ground: the downward part of the remaining displacement is dropped
+ * there (standing on walkable ground is not sliding down it) and the rest follows the surface.
+ * Anything steeper is a wall: the remaining displacement slides along it horizontally (a wall
+ * cannot be climbed by pushing into it); when a wall blocks horizontal motion from the ground, or
+ * catches the shape no higher than `stepHeight` above its bottom, the shape first tries the same
+ * move `stepHeight` higher and drops back onto whatever walkable ground it finds (stairs; a
+ * rounded bottom landing on a step's lip counts when walkable ground lies under its centre).
+ * After the move a short probe downward decides `grounded`; a shape that was grounded and is not
+ * any more looks `snapDown` below for ground to stay on (so a step down or a slope's crest does
+ * not launch it). The shape itself is not moved: the final position goes into `out`, the game
+ * writes it back.
+ */
+import type { StaticCollider } from './bvh.js';
+import { type Shape, type Shape2 } from './shapes.js';
+export interface SlideOptions {
+    /** Sweep-and-project passes. Default 4. */
+    maxIterations?: number;
+    /** Gap kept between the shape and what it hit. Default 0.005. */
+    skin?: number;
+    /** Steepest ground that counts as walkable, in degrees from flat. Default 50. */
+    maxSlope?: number;
+    /** Highest ledge the shape walks up when a wall blocks it; 0 disables. Default 0.35. */
+    stepHeight?: number;
+    /** How far below to look for ground after the move when the shape has left it; 0 disables. Default 0.2. */
+    snapDown?: number;
+    /** Which layers collide. Default all. */
+    layerMask?: number;
+    /**
+     * Whether the shape stood on ground before this move (the previous result's `grounded`): the
+     * snap-down and the step-up only run from the ground. Default true.
+     */
+    wasGrounded?: boolean;
+}
+export interface SlideResult {
+    /** The shape's final centre. */
+    x: number;
+    y: number;
+    z: number;
+    /** Whether the shape ended on walkable ground (within `2 × skin` below it). */
+    grounded: boolean;
+    /** The ground's unit normal when `grounded`, else `[0, 1, 0]`. */
+    groundNormal: [number, number, number];
+    /** Whether a wall (a hit steeper than `maxSlope`) blocked part of the motion. */
+    hitWall: boolean;
+    /** Sweep hits during the move (step-ups counted once). */
+    hits: number;
+    /** Displacement not applied when the iterations ran out (zero otherwise). */
+    remaining: [number, number, number];
+}
+export declare function createSlideResult(): SlideResult;
+/**
+ * Moves `shape` by `(dx, dy, dz)` through the collider with the move-and-slide loop described
+ * above and writes where it ends up (the shape's centre) and how into `out`. The shape is read,
+ * not moved.
+ */
+export declare function slide(c: StaticCollider, shape: Shape, dx: number, dy: number, dz: number, opts?: SlideOptions, out?: SlideResult): SlideResult;
+/**
+ * `slide` for a circle or 2D box moving by `(dx, dz)` in the xz plane: every hit is a wall, no
+ * step or slope or snap; `out.y` is 0 and `grounded` false. The shape is lifted to the collider's
+ * height like the 2D queries.
+ */
+export declare function slide2(c: StaticCollider, shape: Shape2, dx: number, dz: number, opts?: SlideOptions, out?: SlideResult): SlideResult;

package/dist/geom/collide/slide.js

@@ -0,0 +1,375 @@
+import { ALL_LAYERS, createHit, createSweepHit, raycastReg, SW, sweepMove, } from './queries.js';
+import { isBox2, loadShape, SH, SH_BOX, SH_CAPSULE, SH_SPHERE, } from './shapes.js';
+export function createSlideResult() {
+    return {
+        x: 0,
+        y: 0,
+        z: 0,
+        grounded: false,
+        groundNormal: [0, 1, 0],
+        hitWall: false,
+        hits: 0,
+        remaining: [0, 0, 0],
+    };
+}
+/**
+ * The controller's registers: box half extents (0..2), position (3..5), remaining displacement
+ * (6..8), skin (9), cos of the slope limit (10), step height (11), snap-down (12), a saved
+ * position (13..15), the move's dy (16), the shape's half height (17: centre to bottom).
+ * Doubles live here and in `SW` / `SH` rather than in locals passed between functions, which
+ * V8 would box on every call.
+ */
+const P = new Float64Array(18);
+const P_SKIN = 9;
+const P_COS = 10;
+const P_STEP = 11;
+const P_SNAP = 12;
+const P_DY = 16;
+const P_HALF = 17;
+const hit = createSweepHit();
+const lineHit = createHit();
+/** Loads `shape` into `SH` and its centre into `P[3..5]`. */
+function copyShape(shape) {
+    loadShape(shape);
+    if (SH[0] === SH_BOX) {
+        P[0] = (SH[4] - SH[1]) / 2;
+        P[1] = (SH[5] - SH[2]) / 2;
+        P[2] = (SH[6] - SH[3]) / 2;
+        P[3] = SH[1] + P[0];
+        P[4] = SH[2] + P[1];
+        P[5] = SH[3] + P[2];
+        P[P_HALF] = P[1];
+    }
+    else {
+        P[3] = SH[1];
+        P[4] = SH[2];
+        P[5] = SH[3];
+        P[P_HALF] = SH[4] + SH[5];
+    }
+}
+/** Moves the working shape in `SH` to `P[3..5]`. */
+function place() {
+    if (SH[0] === SH_BOX) {
+        SH[1] = P[3] - P[0];
+        SH[2] = P[4] - P[1];
+        SH[3] = P[5] - P[2];
+        SH[4] = P[3] + P[0];
+        SH[5] = P[4] + P[1];
+        SH[6] = P[5] + P[2];
+    }
+    else {
+        SH[1] = P[3];
+        SH[2] = P[4];
+        SH[3] = P[5];
+    }
+}
+/** Sweeps the working shape along `P[6..8]`. */
+function sweepRemaining(c, mask) {
+    SW[0] = P[6];
+    SW[1] = P[7];
+    SW[2] = P[8];
+    return sweepMove(c, hit, mask);
+}
+/** Sweeps the working shape vertically by `SW[1]` (set by the caller: a double argument would be boxed). */
+function sweepY(c, mask) {
+    SW[0] = 0;
+    SW[2] = 0;
+    return sweepMove(c, hit, mask);
+}
+/**
+ * Moves the working shape toward the hit, stopping `skin` short of the surface along its normal,
+ * and takes the travelled part off the remaining displacement.
+ */
+function advanceToHit() {
+    if (hit.t === 0)
+        return;
+    const len = Math.sqrt(P[6] * P[6] + P[7] * P[7] + P[8] * P[8]);
+    const dirX = P[6] / len;
+    const dirY = P[7] / len;
+    const dirZ = P[8] / len;
+    const closing = -(dirX * hit.nx + dirY * hit.ny + dirZ * hit.nz);
+    const backoff = closing > 1e-6 ? P[P_SKIN] / closing : P[P_SKIN];
+    const travel = Math.max(0, hit.t * len - backoff);
+    P[3] += dirX * travel;
+    P[4] += dirY * travel;
+    P[5] += dirZ * travel;
+    const left = 1 - travel / len;
+    P[6] *= left;
+    P[7] *= left;
+    P[8] *= left;
+    place();
+}
+/** The plane normal `projectRemaining` works with. */
+const N = new Float64Array(3);
+/** Removes the component of the remaining displacement that goes into the plane with normal `N`. */
+function projectRemaining() {
+    const nx = N[0];
+    const ny = N[1];
+    const nz = N[2];
+    const into = P[6] * nx + P[7] * ny + P[8] * nz;
+    if (into < 0) {
+        P[6] -= nx * into;
+        P[7] -= ny * into;
+        P[8] -= nz * into;
+    }
+}
+/** Ground: drop the downward part of the remaining displacement, follow the surface with the rest. */
+function projectOnGround() {
+    if (P[7] < 0)
+        P[7] = 0;
+    N[0] = hit.nx;
+    N[1] = hit.ny;
+    N[2] = hit.nz;
+    projectRemaining();
+}
+/** Wall: slide along it horizontally (a ceiling, with no horizontal normal, uses its own). */
+function projectOnWall() {
+    const h = Math.sqrt(hit.nx * hit.nx + hit.nz * hit.nz);
+    if (h > 1e-6) {
+        N[0] = hit.nx / h;
+        N[1] = 0;
+        N[2] = hit.nz / h;
+    }
+    else {
+        N[0] = hit.nx;
+        N[1] = hit.ny;
+        N[2] = hit.nz;
+    }
+    projectRemaining();
+}
+/**
+ * The step-up: from the current position, go up to `stepHeight`, move the horizontal remainder
+ * there, come back down onto walkable ground no lower than where we started. Commits the move
+ * and returns true, or leaves everything as it was.
+ */
+function tryStep(c, mask, out) {
+    const hx = P[6];
+    const hz = P[8];
+    const horiz = Math.sqrt(hx * hx + hz * hz);
+    if (horiz < 1e-9)
+        return false;
+    const skin = P[P_SKIN];
+    P[13] = P[3];
+    P[14] = P[4];
+    P[15] = P[5];
+    // Up.
+    let up = P[P_STEP];
+    SW[1] = up;
+    if (sweepY(c, mask)) {
+        up = Math.max(0, hit.t * up - skin / Math.max(1e-6, -hit.ny));
+    }
+    if (up <= skin)
+        return false;
+    // Forward, at the raised height.
+    P[4] += up;
+    place();
+    SW[0] = hx;
+    SW[1] = 0;
+    SW[2] = hz;
+    let frac = 1;
+    if (sweepMove(c, hit, mask)) {
+        if (hit.t === 0)
+            return restore();
+        const closing = -((hx * hit.nx + hz * hit.nz) / horiz);
+        const backoff = closing > 1e-6 ? skin / closing : skin;
+        frac = Math.max(0, (hit.t * horiz - backoff) / horiz);
+        if (frac * horiz < 1e-6)
+            return restore();
+    }
+    P[3] += hx * frac;
+    P[5] += hz * frac;
+    place();
+    // Down onto the step: ground within `up` of the raised height, walkable.
+    const drop = up + skin;
+    SW[1] = -drop;
+    if (!sweepY(c, mask))
+        return restore();
+    if (hit.t === 0)
+        return restore();
+    if (hit.ny < P[P_COS]) {
+        // Not ground: a step's lip under the rounded bottom (the next moves carry the shape onto
+        // the step) or a slope too steep to stand on. Only the lip, no higher than a step above
+        // where we started, with walkable ground under the centre, counts.
+        const lip = hit.y <= P[14] - P[P_HALF] + P[P_STEP] + skin;
+        if (!lip || !lineGround(c, mask, drop + P[P_STEP]))
+            return restore();
+    }
+    // Commit.
+    P[4] -= Math.max(0, hit.t * drop - skin / hit.ny);
+    P[6] = hx * (1 - frac);
+    P[7] = 0;
+    P[8] = hz * (1 - frac);
+    place();
+    out.hits++;
+    return true;
+}
+/**
+ * Whether a line straight down from the working shape's centre meets walkable ground within
+ * `below` of the shape's bottom. A rounded bottom coming down onto a step's lip touches it on
+ * the hemisphere, where the contact normal is too steep to be ground although the shape is
+ * about to stand on the step: the line under the centre tells a lip (ground below) from a
+ * steep slope (the slope itself below).
+ */
+function lineGround(c, mask, below) {
+    return (raycastReg(c, P[3], P[4], P[5], 0, -1, 0, P[P_HALF] + below, lineHit, mask) &&
+        lineHit.ny >= P[P_COS]);
+}
+/** Puts the working shape back where `tryStep` started; always false. */
+function restore() {
+    P[3] = P[13];
+    P[4] = P[14];
+    P[5] = P[15];
+    place();
+    return false;
+}
+/**
+ * The loop over the working shape in `SH` from `P[3..5]` along `P[6..8]`. `flat` is the 2D
+ * case: every hit a wall, no ground, step or snap.
+ */
+function run(c, opts, out, flat) {
+    const maxIterations = opts.maxIterations ?? 4;
+    P[P_SKIN] = opts.skin ?? 0.005;
+    P[P_COS] = flat ? 2 : Math.cos(((opts.maxSlope ?? 50) * Math.PI) / 180);
+    P[P_STEP] = flat ? 0 : (opts.stepHeight ?? 0.35);
+    P[P_SNAP] = flat ? 0 : (opts.snapDown ?? 0.2);
+    const mask = opts.layerMask ?? ALL_LAYERS;
+    const wasGrounded = opts.wasGrounded ?? true;
+    P[P_DY] = P[7];
+    out.grounded = false;
+    out.groundNormal[0] = 0;
+    out.groundNormal[1] = 1;
+    out.groundNormal[2] = 0;
+    out.hitWall = false;
+    out.hits = 0;
+    let onGround = false;
+    for (let i = 0; i < maxIterations; i++) {
+        const len = Math.sqrt(P[6] * P[6] + P[7] * P[7] + P[8] * P[8]);
+        if (len < 1e-9) {
+            P[6] = P[7] = P[8] = 0;
+            break;
+        }
+        if (!sweepRemaining(c, mask)) {
+            P[3] += P[6];
+            P[4] += P[7];
+            P[5] += P[8];
+            P[6] = P[7] = P[8] = 0;
+            place();
+            break;
+        }
+        out.hits++;
+        if (hit.t === 0 && hit.depth > 0) {
+            // Started inside something: push out along the normal first.
+            const push = hit.depth + P[P_SKIN];
+            P[3] += hit.nx * push;
+            P[4] += hit.ny * push;
+            P[5] += hit.nz * push;
+            place();
+        }
+        else {
+            advanceToHit();
+        }
+        if (hit.ny >= P[P_COS]) {
+            onGround = true;
+            projectOnGround();
+            continue;
+        }
+        // A wall. From the ground, or when the obstacle is no higher than a step above the shape's
+        // bottom and the shape is not rising (a stair's edge caught under a capsule's lower cap),
+        // try to step over it.
+        if (P[P_STEP] > 0 &&
+            (wasGrounded || onGround || (P[P_DY] <= 0 && hit.y <= P[4] - P[P_HALF] + P[P_STEP])) &&
+            Math.sqrt(P[6] * P[6] + P[8] * P[8]) > 1e-9) {
+            const nx = hit.nx;
+            const ny = hit.ny;
+            const nz = hit.nz;
+            if (tryStep(c, mask, out)) {
+                onGround = true;
+                continue;
+            }
+            hit.nx = nx;
+            hit.ny = ny;
+            hit.nz = nz;
+        }
+        out.hitWall = true;
+        projectOnWall();
+    }
+    out.remaining[0] = P[6];
+    out.remaining[1] = P[7];
+    out.remaining[2] = P[8];
+    // Ground probe: a hair below for `grounded`; `snapDown` below when the shape has just left the ground.
+    if (!flat) {
+        const skin = P[P_SKIN];
+        const snap = P[P_SNAP] > 0 && wasGrounded && P[P_DY] <= 0;
+        const drop = snap ? P[P_SNAP] + skin : 2 * skin;
+        SW[1] = -drop;
+        if (sweepY(c, mask)) {
+            if (hit.ny >= P[P_COS]) {
+                if (hit.t > 0) {
+                    P[4] -= Math.max(0, hit.t * drop - skin / hit.ny);
+                    place();
+                }
+                out.grounded = true;
+                out.groundNormal[0] = hit.nx;
+                out.groundNormal[1] = hit.ny;
+                out.groundNormal[2] = hit.nz;
+            }
+            else if (lineGround(c, mask, P[P_STEP])) {
+                // Held up by a step's lip under the rounded bottom, ground under the centre: standing.
+                out.grounded = true;
+                out.groundNormal[0] = lineHit.nx;
+                out.groundNormal[1] = lineHit.ny;
+                out.groundNormal[2] = lineHit.nz;
+            }
+        }
+    }
+    out.x = P[3];
+    out.y = P[4];
+    out.z = P[5];
+    return out;
+}
+/**
+ * Moves `shape` by `(dx, dy, dz)` through the collider with the move-and-slide loop described
+ * above and writes where it ends up (the shape's centre) and how into `out`. The shape is read,
+ * not moved.
+ */
+export function slide(c, shape, dx, dy, dz, opts = {}, out = createSlideResult()) {
+    copyShape(shape);
+    P[6] = dx;
+    P[7] = dy;
+    P[8] = dz;
+    return run(c, opts, out, false);
+}
+const EPS_2D = 1e-3;
+/**
+ * `slide` for a circle or 2D box moving by `(dx, dz)` in the xz plane: every hit is a wall, no
+ * step or slope or snap; `out.y` is 0 and `grounded` false. The shape is lifted to the collider's
+ * height like the 2D queries.
+ */
+export function slide2(c, shape, dx, dz, opts = {}, out = createSlideResult()) {
+    const y0 = c.bounds.min[1] + EPS_2D;
+    const y1 = c.bounds.max[1] - EPS_2D;
+    P[3] = shape.x;
+    P[4] = (y0 + y1) / 2;
+    P[5] = shape.z;
+    if (isBox2(shape)) {
+        SH[0] = SH_BOX;
+        P[0] = shape.hw;
+        P[1] = Math.max(0, (y1 - y0) / 2);
+        P[2] = shape.hh;
+        P[P_HALF] = P[1];
+    }
+    else {
+        const half = (y1 - y0) / 2 - shape.r;
+        SH[0] = half <= 0 ? SH_SPHERE : SH_CAPSULE;
+        SH[4] = Math.max(0, half);
+        SH[5] = shape.r;
+        P[P_HALF] = SH[4] + shape.r;
+    }
+    place();
+    P[6] = dx;
+    P[7] = 0;
+    P[8] = dz;
+    run(c, opts, out, true);
+    out.y = 0;
+    return out;
+}

package/dist/geom/collide/tile-slide.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `slideTiles`: a 2D box moved against a tile grid, the platformer case. Axis-separated: each
+ * sub-step (at most half a tile) moves x then y and pushes the box out of what it entered.
+ * Solid tiles block from every side; one-way tiles only hold a box falling onto them from above;
+ * moving platforms (`movers`) are solid boxes that also carry what stands on them.
+ *
+ * Screen convention: y grows downward, so `+dy` falls, "ground" is below (`y + h`) and a
+ * ceiling above (`y`). A `GridSource` maps its column `x` and row `z` to tile `(cx, cy)`, its
+ * `origin` `[x, z]` to the world x, y of tile (0, 0). Pure arithmetic: no allocation per call.
+ */
+import { type GridSource } from './grid.js';
+/** What a tile is: `TILE_EMPTY`, `TILE_SOLID` or `TILE_ONE_WAY`. */
+export type TileKind = number;
+export declare const TILE_EMPTY = 0;
+export declare const TILE_SOLID = 1;
+/** Holds only from above: a box rising or moving sideways passes through. */
+export declare const TILE_ONE_WAY = 2;
+/** A tile map by query: `solidAt(cx, cy)` for any tile, `cellSize` wide, (0, 0) at `origin`. */
+export interface TileQuery {
+    cellSize: number;
+    /** World x, y of tile (0, 0)'s top-left corner. Default `[0, 0]`. */
+    origin?: readonly [number, number];
+    solidAt(cx: number, cy: number): TileKind;
+}
+/** A box: top-left corner and size. */
+export interface TileBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A moving platform's box this tick and how far it moved since the last one. */
+export interface TileMover extends TileBox {
+    dx: number;
+    dy: number;
+}
+export interface TileSlideOptions {
+    /** One-way tiles hold a falling box. Default true; false drops through them. */
+    oneWay?: boolean;
+    /**
+     * A box on the ground blocked sideways climbs a ledge up to this high (world units) instead
+     * of stopping. Default 0.
+     */
+    stepUp?: number;
+    /** Moving platforms: solid, and a box landing on one rides it (`riding`, then `carryBy`). */
+    movers?: readonly TileMover[];
+}
+/** Where `slideTiles` left the box, and what it touched. `createTileSlideResult` makes one. */
+export interface TileSlideResult {
+    x: number;
+    y: number;
+    /** The displacement made, carry included (`x - box.x`, `y - box.y`). */
+    dx: number;
+    dy: number;
+    /** Resting on a solid or one-way tile, or a mover, at the end of the move. */
+    onGround: boolean;
+    hitCeiling: boolean;
+    hitWall: boolean;
+    /** Index into `movers` of the platform the box stands on, or -1. */
+    riding: number;
+    /**
+     * A carry queued by `carryBy`, applied (against the tiles) before the next `slideTiles`
+     * moves the box with this result, then cleared.
+     */
+    carried: {
+        dx: number;
+        dy: number;
+    };
+}
+export declare function createTileSlideResult(): TileSlideResult;
+/**
+ * Queue `mover`'s motion this tick into `result.carried`, for the next `slideTiles` with that
+ * result to apply first. Call it with the platform the box rode last tick
+ * (`movers[result.riding]`), after the platforms move and before the box does. Returns `result`.
+ */
+export declare function carryBy(result: TileSlideResult, mover: {
+    readonly dx: number;
+    readonly dy: number;
+}): TileSlideResult;
+/**
+ * Move `box` by `(dx, dy)` against `tiles` (a `GridSource` or a `TileQuery`), writing where it
+ * ended and what it touched into `out` (returned). A carry queued in `out.carried` (`carryBy`)
+ * is applied first and cleared. The box is never moved more than half a tile per sub-step, so
+ * it cannot tunnel; a box sliding along a floor or wall of separate tiles never catches on their
+ * seams (each axis only tests the tiles ahead of its leading edge, inset by a small epsilon).
+ * `box` itself is not changed: copy `out.x`, `out.y` back.
+ */
+export declare function slideTiles(tiles: GridSource | TileQuery, box: TileBox, dx: number, dy: number, out: TileSlideResult, opts?: TileSlideOptions): TileSlideResult;