@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/nav/obstacles.js

@@ -0,0 +1,294 @@
+import { OBSTACLE_AREA } from './mesh/areas.js';
+import { NavMesh } from './mesh/navmesh.js';
+/** Squared XZ distance from `(x, z)` to polygon `p` (0 inside). */
+function polyDistance2(mesh, p, x, z) {
+    if (mesh.containsXZ(p, x, z))
+        return 0;
+    const n = mesh.polyVertexCount(p);
+    const nvp = mesh.maxVertsPerPoly;
+    const verts = mesh.verts;
+    let best = Number.POSITIVE_INFINITY;
+    for (let k = 0; k < n; k++) {
+        const a = mesh.polys[p * nvp + k] * 3;
+        const b = mesh.polys[p * nvp + (k + 1 === n ? 0 : k + 1)] * 3;
+        const ax = verts[a];
+        const az = verts[a + 2];
+        const ex = verts[b] - ax;
+        const ez = verts[b + 2] - az;
+        const len = ex * ex + ez * ez;
+        let t = len > 0 ? ((x - ax) * ex + (z - az) * ez) / len : 0;
+        if (t < 0)
+            t = 0;
+        else if (t > 1)
+            t = 1;
+        const dx = ax + ex * t - x;
+        const dz = az + ez * t - z;
+        const d = dx * dx + dz * dz;
+        if (d < best)
+            best = d;
+    }
+    return best;
+}
+/** Separating-axis test between polygon `p` and a yawed box (both convex, XZ). */
+function polyOverlapsBox(mesh, p, bx, bz, hw, hd, yaw) {
+    const n = mesh.polyVertexCount(p);
+    const nvp = mesh.maxVertsPerPoly;
+    const verts = mesh.verts;
+    const c = Math.cos(yaw);
+    const s = Math.sin(yaw);
+    // Box axes: u = (c, s), v = (-s, c); the box's projection on an axis (nx, nz) has half width
+    // hw·|u·n| + hd·|v·n| around its centre.
+    const axes = n + 2;
+    for (let i = 0; i < axes; i++) {
+        let nx;
+        let nz;
+        if (i === n) {
+            nx = c;
+            nz = s;
+        }
+        else if (i === n + 1) {
+            nx = -s;
+            nz = c;
+        }
+        else {
+            const a = mesh.polys[p * nvp + i] * 3;
+            const b = mesh.polys[p * nvp + (i + 1 === n ? 0 : i + 1)] * 3;
+            nx = -(verts[b + 2] - verts[a + 2]);
+            nz = verts[b] - verts[a];
+        }
+        let pmin = Number.POSITIVE_INFINITY;
+        let pmax = Number.NEGATIVE_INFINITY;
+        for (let k = 0; k < n; k++) {
+            const v = mesh.polys[p * nvp + k] * 3;
+            const d = verts[v] * nx + verts[v + 2] * nz;
+            if (d < pmin)
+                pmin = d;
+            if (d > pmax)
+                pmax = d;
+        }
+        const bc = bx * nx + bz * nz;
+        const br = hw * Math.abs(c * nx + s * nz) + hd * Math.abs(-s * nx + c * nz);
+        if (bc + br < pmin || bc - br > pmax)
+            return false;
+    }
+    return true;
+}
+/** Whether a yawed box holds `(x, z)` once inflated by `pad` on every side. */
+function boxHolds(x, z, bx, bz, hw, hd, yaw, pad) {
+    const c = Math.cos(yaw);
+    const s = Math.sin(yaw);
+    const dx = x - bx;
+    const dz = z - bz;
+    const lx = dx * c + dz * s;
+    const lz = -dx * s + dz * c;
+    return Math.abs(lx) <= hw + pad && Math.abs(lz) <= hd + pad;
+}
+/** A set of up to `maxObstacles` obstacles over a mesh or a grid. */
+export function createObstacleSet(target, opts) {
+    const max = Math.max(1, opts.maxObstacles);
+    const mesh = target instanceof NavMesh ? target : null;
+    const grid = mesh ? null : target;
+    const slots = [];
+    for (let i = 0; i < max; i++) {
+        slots.push({
+            active: false,
+            id: 0,
+            kind: 'disc',
+            x: 0,
+            z: 0,
+            radius: 0,
+            w: 0,
+            d: 0,
+            yaw: 0,
+            dirty: false,
+            applied: false,
+            ax: 0,
+            az: 0,
+            aradius: 0,
+            aw: 0,
+            ad: 0,
+            ayaw: 0,
+            akind: 'disc',
+        });
+    }
+    const layer = grid && opts.layer && opts.layer.length >= grid.size
+        ? opts.layer
+        : new Float32Array(grid ? grid.size : 0);
+    const cover = new Uint16Array(mesh ? Math.max(1, mesh.polyCount) : grid ? grid.size : 1);
+    const saved = mesh ? new Uint8Array(Math.max(1, mesh.polyCount)) : null;
+    let nextId = 1;
+    let count = 0;
+    let version = 0;
+    const slotOf = (id) => {
+        if (id <= 0)
+            return undefined;
+        for (let i = 0; i < max; i++) {
+            const s = slots[i];
+            if (s.active && s.id === id)
+                return s;
+        }
+        return undefined;
+    };
+    /** Adds or removes one footprint's coverage; returns the polygons or cells whose state flipped. */
+    const stamp = (kind, x, z, radius, w, d, yaw, delta) => {
+        let flipped = 0;
+        const hw = w * 0.5;
+        const hd = d * 0.5;
+        if (mesh && saved) {
+            const n = mesh.polysInBox(x - radius, z - radius, x + radius, z + radius);
+            const found = mesh.polysFound;
+            for (let i = 0; i < n; i++) {
+                const p = found[i];
+                const hit = kind === 'disc'
+                    ? polyDistance2(mesh, p, x, z) <= radius * radius
+                    : polyOverlapsBox(mesh, p, x, z, hw, hd, yaw);
+                if (!hit)
+                    continue;
+                const was = cover[p];
+                const now = was + delta;
+                cover[p] = now;
+                if (was === 0 && now === 1) {
+                    saved[p] = mesh.area[p];
+                    mesh.area[p] = OBSTACLE_AREA;
+                    flipped++;
+                }
+                else if (was === 1 && now === 0) {
+                    mesh.area[p] = saved[p];
+                    flipped++;
+                }
+            }
+        }
+        else if (grid) {
+            const cs = grid.cellSize;
+            const pad = cs * 0.5;
+            const reach = radius + pad;
+            const x0 = Math.max(0, Math.floor((x - reach - grid.origin.x) / cs));
+            const z0 = Math.max(0, Math.floor((z - reach - grid.origin.z) / cs));
+            const x1 = Math.min(grid.width - 1, Math.floor((x + reach - grid.origin.x) / cs));
+            const z1 = Math.min(grid.height - 1, Math.floor((z + reach - grid.origin.z) / cs));
+            const r2 = reach * reach;
+            for (let cy = z0; cy <= z1; cy++) {
+                for (let cx = x0; cx <= x1; cx++) {
+                    const wx = grid.origin.x + (cx + 0.5) * cs;
+                    const wz = grid.origin.z + (cy + 0.5) * cs;
+                    let hit;
+                    if (kind === 'disc') {
+                        const dx = wx - x;
+                        const dz = wz - z;
+                        hit = dx * dx + dz * dz <= r2;
+                    }
+                    else {
+                        hit = boxHolds(wx, wz, x, z, hw, hd, yaw, pad);
+                    }
+                    if (!hit)
+                        continue;
+                    const i = cy * grid.width + cx;
+                    const was = cover[i];
+                    const now = was + delta;
+                    cover[i] = now;
+                    if (was === 0 && now === 1) {
+                        layer[i] = Infinity;
+                        flipped++;
+                    }
+                    else if (was === 1 && now === 0) {
+                        layer[i] = 0;
+                        flipped++;
+                    }
+                }
+            }
+        }
+        return flipped;
+    };
+    return {
+        obstacles: slots,
+        get count() {
+            return count;
+        },
+        get version() {
+            return version;
+        },
+        layer,
+        add(shape) {
+            for (let i = 0; i < max; i++) {
+                const s = slots[i];
+                if (s.active)
+                    continue;
+                s.active = true;
+                s.id = nextId++;
+                s.x = shape.x;
+                s.z = shape.z;
+                if ('radius' in shape) {
+                    s.kind = 'disc';
+                    s.radius = Math.max(0, shape.radius);
+                    s.w = s.d = s.radius * 2;
+                    s.yaw = 0;
+                }
+                else {
+                    s.kind = 'box';
+                    s.w = Math.max(0, shape.w);
+                    s.d = Math.max(0, shape.d);
+                    s.yaw = shape.yaw;
+                    s.radius = Math.sqrt(s.w * s.w + s.d * s.d) * 0.5;
+                }
+                s.dirty = true;
+                count++;
+                return s.id;
+            }
+            return -1;
+        },
+        move(id, x, z, yaw) {
+            const s = slotOf(id);
+            if (!s)
+                return;
+            if (s.x === x && s.z === z && (yaw === undefined || yaw === s.yaw))
+                return;
+            s.x = x;
+            s.z = z;
+            if (yaw !== undefined && s.kind === 'box')
+                s.yaw = yaw;
+            s.dirty = true;
+        },
+        remove(id) {
+            const s = slotOf(id);
+            if (!s)
+                return false;
+            s.active = false;
+            s.dirty = true;
+            count--;
+            return true;
+        },
+        get: slotOf,
+        apply() {
+            let flipped = 0;
+            for (let i = 0; i < max; i++) {
+                const s = slots[i];
+                if (!s.dirty)
+                    continue;
+                s.dirty = false;
+                if (s.applied) {
+                    flipped += stamp(s.akind, s.ax, s.az, s.aradius, s.aw, s.ad, s.ayaw, -1);
+                    s.applied = false;
+                }
+                if (s.active) {
+                    flipped += stamp(s.kind, s.x, s.z, s.radius, s.w, s.d, s.yaw, 1);
+                    s.applied = true;
+                    s.akind = s.kind;
+                    s.ax = s.x;
+                    s.az = s.z;
+                    s.aradius = s.radius;
+                    s.aw = s.w;
+                    s.ad = s.d;
+                    s.ayaw = s.yaw;
+                }
+            }
+            if (flipped > 0) {
+                version++;
+                if (mesh)
+                    mesh.version++;
+                else
+                    grid?.touch();
+            }
+            return flipped;
+        },
+    };
+}

package/dist/nav/path.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `NavPath`: a reusable list of world XZ waypoints, `followPath`, which turns one into a
+ * desired velocity per tick, and string pulling (`smoothPath` over `hasLineOfWalkable`, both
+ * honouring the grid's edge-cost hook). Allocation-free after the path's capacity settles.
+ */
+import type { EdgeCost, NavGrid, NavPoint } from './grid.js';
+export interface NavPath {
+    /** Waypoints as world `x, z` pairs; `length * 2` floats are valid. Grows in place as needed. */
+    points: Float32Array;
+    /** Waypoints in the path (0 when no path). */
+    length: number;
+    /** Index of the waypoint `followPath` is heading for. */
+    cursor: number;
+    /** `grid.version` when the path was found; differs from the grid's once the grid was edited. */
+    version: number;
+}
+/** A path with room for `capacity` waypoints (grows on demand). */
+export declare function createNavPath(capacity?: number): NavPath;
+/** Makes room for `count` waypoints (1.5× growth), keeping the floats already there. */
+export declare function reservePath(path: NavPath, count: number): void;
+/** Empties the path (`length` 0, `cursor` 0); the buffer stays. */
+export declare function clearPath(path: NavPath): void;
+/** Writes waypoint `i` into `out`. */
+export declare function pathPoint(path: NavPath, i: number, out: NavPoint): NavPoint;
+/** The sum of the segment lengths, world units. */
+export declare function pathDistance(path: NavPath): number;
+export type FollowResult = 'moving' | 'arrived';
+/**
+ * Heads for `path.points[path.cursor]` at `speed`: the cursor advances when `position` is within
+ * `arriveRadius` of its waypoint, and the last waypoint reached is `'arrived'` with a zero
+ * velocity. `outVelocity` is the desired velocity (world units per second), full speed until the
+ * end (pair with `steer.arrive` for a slow-down). An empty path is `'arrived'`.
+ */
+export declare function followPath(path: NavPath, position: Readonly<NavPoint>, speed: number, arriveRadius: number, outVelocity: NavPoint): FollowResult;
+export interface LineOfWalkableOptions {
+    /**
+     * The step-cost hook the line honours per cell pair it crosses: a pair the hook blocks
+     * (`Infinity`) breaks the line, so a one-way ledge is never cut across. Default: the grid's own
+     * `edgeCost`; `null` opts out (walkability only).
+     */
+    edgeCost?: EdgeCost | null;
+}
+/**
+ * True when a straight segment between the centres of two cells crosses walkable cells only
+ * (a supercover walk: a segment through a corner needs both cells beside the corner walkable,
+ * so it never slips between two diagonal walls) and no cell pair along it is blocked by the
+ * edge-cost hook (the grid's, or `opts.edgeCost`; `null` ignores hooks). Both endpoints must be
+ * walkable. Allocation-free.
+ */
+export declare function hasLineOfWalkable(grid: NavGrid, x0: number, y0: number, x1: number, y1: number, opts?: LineOfWalkableOptions): boolean;
+/**
+ * String pulling: drops every waypoint that a straight line of walkable cells can skip, in
+ * place, so a staircase of cell centres becomes a few straight legs. A leg never crosses a cell
+ * pair the edge-cost hook blocks (`hasLineOfWalkable` with `opts`), so a bend at a cliff stays.
+ * On a 4-neighbour grid a leg never leaves its row or column: only collinear waypoints are
+ * dropped, so the path keeps every corner and makes no diagonal cut. `path.cursor` is reset to
+ * 0. Returns the path. Allocation-free.
+ */
+export declare function smoothPath(grid: NavGrid, path: NavPath, opts?: LineOfWalkableOptions): NavPath;

package/dist/nav/path.js

@@ -0,0 +1,177 @@
+/** A path with room for `capacity` waypoints (grows on demand). */
+export function createNavPath(capacity = 64) {
+    return { points: new Float32Array(Math.max(1, capacity) * 2), length: 0, cursor: 0, version: -1 };
+}
+/** Makes room for `count` waypoints (1.5× growth), keeping the floats already there. */
+export function reservePath(path, count) {
+    const need = count * 2;
+    if (path.points.length >= need)
+        return;
+    const next = new Float32Array(Math.max(need, Math.ceil(path.points.length * 1.5)));
+    next.set(path.points);
+    path.points = next;
+}
+/** Empties the path (`length` 0, `cursor` 0); the buffer stays. */
+export function clearPath(path) {
+    path.length = 0;
+    path.cursor = 0;
+}
+/** Writes waypoint `i` into `out`. */
+export function pathPoint(path, i, out) {
+    out.x = path.points[i * 2];
+    out.z = path.points[i * 2 + 1];
+    return out;
+}
+/** The sum of the segment lengths, world units. */
+export function pathDistance(path) {
+    const p = path.points;
+    let d = 0;
+    for (let i = 1; i < path.length; i++) {
+        const dx = p[i * 2] - p[i * 2 - 2];
+        const dz = p[i * 2 + 1] - p[i * 2 - 1];
+        d += Math.sqrt(dx * dx + dz * dz);
+    }
+    return d;
+}
+/**
+ * Heads for `path.points[path.cursor]` at `speed`: the cursor advances when `position` is within
+ * `arriveRadius` of its waypoint, and the last waypoint reached is `'arrived'` with a zero
+ * velocity. `outVelocity` is the desired velocity (world units per second), full speed until the
+ * end (pair with `steer.arrive` for a slow-down). An empty path is `'arrived'`.
+ */
+export function followPath(path, position, speed, arriveRadius, outVelocity) {
+    const n = path.length;
+    if (n === 0) {
+        outVelocity.x = 0;
+        outVelocity.z = 0;
+        return 'arrived';
+    }
+    if (path.cursor >= n)
+        path.cursor = n - 1;
+    const r2 = arriveRadius * arriveRadius;
+    const p = path.points;
+    let dx = p[path.cursor * 2] - position.x;
+    let dz = p[path.cursor * 2 + 1] - position.z;
+    while (dx * dx + dz * dz <= r2) {
+        if (path.cursor >= n - 1) {
+            outVelocity.x = 0;
+            outVelocity.z = 0;
+            return 'arrived';
+        }
+        path.cursor++;
+        dx = p[path.cursor * 2] - position.x;
+        dz = p[path.cursor * 2 + 1] - position.z;
+    }
+    const d = Math.sqrt(dx * dx + dz * dz);
+    outVelocity.x = (dx / d) * speed;
+    outVelocity.z = (dz / d) * speed;
+    return 'moving';
+}
+/**
+ * True when a straight segment between the centres of two cells crosses walkable cells only
+ * (a supercover walk: a segment through a corner needs both cells beside the corner walkable,
+ * so it never slips between two diagonal walls) and no cell pair along it is blocked by the
+ * edge-cost hook (the grid's, or `opts.edgeCost`; `null` ignores hooks). Both endpoints must be
+ * walkable. Allocation-free.
+ */
+export function hasLineOfWalkable(grid, x0, y0, x1, y1, opts) {
+    if (!grid.isWalkable(x0, y0) || !grid.isWalkable(x1, y1))
+        return false;
+    const hook = opts === undefined || opts.edgeCost === undefined ? grid.edgeCost : opts.edgeCost;
+    const width = grid.width;
+    let x = x0;
+    let y = y0;
+    const dx = Math.abs(x1 - x0);
+    const dy = Math.abs(y1 - y0);
+    const sx = x1 > x0 ? 1 : -1;
+    const sy = y1 > y0 ? 1 : -1;
+    // Integer DDA: the next vertical boundary is crossed at t = (ix + 0.5) / dx, the next
+    // horizontal one at (iy + 0.5) / dy; both scaled by 2·dx·dy so the comparison is exact.
+    let ix = 0;
+    let iy = 0;
+    while (ix < dx || iy < dy) {
+        const from = y * width + x;
+        const tx = (2 * ix + 1) * dy;
+        const ty = (2 * iy + 1) * dx;
+        if (ix < dx && (iy >= dy || tx < ty)) {
+            x += sx;
+            ix++;
+        }
+        else if (iy < dy && (ix >= dx || ty < tx)) {
+            y += sy;
+            iy++;
+        }
+        else {
+            // Exactly through a corner: both cells beside it must be open, then step diagonally.
+            if (!grid.isWalkable(x + sx, y) || !grid.isWalkable(x, y + sy))
+                return false;
+            x += sx;
+            y += sy;
+            ix++;
+            iy++;
+        }
+        if (!grid.isWalkable(x, y))
+            return false;
+        if (hook) {
+            const e = hook(from, y * width + x, grid);
+            if (e === Infinity || Number.isNaN(e))
+                return false;
+        }
+    }
+    return true;
+}
+const sa = { x: 0, y: 0 };
+const sb = { x: 0, y: 0 };
+/**
+ * String pulling: drops every waypoint that a straight line of walkable cells can skip, in
+ * place, so a staircase of cell centres becomes a few straight legs. A leg never crosses a cell
+ * pair the edge-cost hook blocks (`hasLineOfWalkable` with `opts`), so a bend at a cliff stays.
+ * On a 4-neighbour grid a leg never leaves its row or column: only collinear waypoints are
+ * dropped, so the path keeps every corner and makes no diagonal cut. `path.cursor` is reset to
+ * 0. Returns the path. Allocation-free.
+ */
+export function smoothPath(grid, path, opts) {
+    const n = path.length;
+    path.cursor = 0;
+    if (n < 3)
+        return path;
+    const p = path.points;
+    let write = 1;
+    if (grid.neighbours === 4) {
+        for (let i = 1; i < n - 1; i++) {
+            const ax = p[i * 2] - p[write * 2 - 2];
+            const az = p[i * 2 + 1] - p[write * 2 - 1];
+            const bx = p[i * 2 + 2] - p[i * 2];
+            const bz = p[i * 2 + 3] - p[i * 2 + 1];
+            // Keep the waypoint when the run bends (the cross product of the two legs is not zero).
+            if (ax * bz - az * bx !== 0) {
+                p[write * 2] = p[i * 2];
+                p[write * 2 + 1] = p[i * 2 + 1];
+                write++;
+            }
+        }
+        p[write * 2] = p[n * 2 - 2];
+        p[write * 2 + 1] = p[n * 2 - 1];
+        path.length = write + 1;
+        return path;
+    }
+    let anchor = 0;
+    while (anchor < n - 1) {
+        grid.toCell(p[anchor * 2], p[anchor * 2 + 1], sa);
+        // The furthest waypoint visible from the anchor; the next one is always reachable.
+        let far = anchor + 1;
+        for (let j = n - 1; j > anchor + 1; j--) {
+            grid.toCell(p[j * 2], p[j * 2 + 1], sb);
+            if (hasLineOfWalkable(grid, sa.x, sa.y, sb.x, sb.y, opts)) {
+                far = j;
+                break;
+            }
+        }
+        p[write * 2] = p[far * 2];
+        p[write * 2 + 1] = p[far * 2 + 1];
+        write++;
+        anchor = far;
+    }
+    path.length = write;
+    return path;
+}

package/dist/nav/query-queue.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A path queue: requests are tickets, `update()` spends a fixed budget of A* pops per call on
+ * them in order (one search in flight at a time, the budget left over flowing to the next
+ * ticket), so a hundred agents asking for routes at once cost the same per frame as one. Works
+ * over a `NavMesh` (a `MeshSearch`) or a `NavGrid` (a sliced copy of `findPath`'s A*, same
+ * expansions, same paths). Grid paths are string-pulled when asked. A search whose target
+ * changed version under it restarts. Every array is allocated at creation.
+ */
+import type { FindPathOptions } from './astar.js';
+import { type NavCell, type NavGrid } from './grid.js';
+import { type FindMeshPathOptions, type NavPath3 } from './mesh/mesh-path.js';
+import { NavMesh, type NavPoint3 } from './mesh/navmesh.js';
+import { type NavPath } from './path.js';
+export type PathStatus = 'pending' | 'done' | 'failed' | 'none';
+export interface PathQueueOptions {
+    /** How many tickets may wait or be in flight at once. */
+    maxQueries: number;
+    /** A* pops spent per `update()`, shared by the tickets it works on. Default 256. */
+    iterationsPerUpdate?: number;
+}
+export interface PathRequestOptions extends FindMeshPathOptions, FindPathOptions {
+    /** Grid only: string-pull the path (`smoothPath`) when it is done. Default false. */
+    smooth?: boolean;
+}
+export interface PathQueue {
+    /** Tickets waiting or in flight. */
+    readonly pending: number;
+    /** Tickets finished since creation (done or failed). */
+    readonly finished: number;
+    /**
+     * Queues a search from `from` to `to` into `out` (a `NavPath3` on a mesh, a `NavPath` on a
+     * grid). Grid ends are cells. Returns the ticket (> 0), or -1 when the queue is full. `out`
+     * is written only when the ticket completes (`'done'`), and never after a cancel.
+     */
+    request(from: Readonly<NavPoint3> | Readonly<NavCell>, to: Readonly<NavPoint3> | Readonly<NavCell>, out: NavPath3 | NavPath, opts?: PathRequestOptions): number;
+    /** Spends the budget; returns the pops used. */
+    update(): number;
+    /** `'pending'` while queued or in flight, `'done'`/`'failed'` once finished, `'none'` for an unknown or cancelled ticket. */
+    status(ticket: number): PathStatus;
+    /** Drops a ticket; its `out` is left untouched. False when the ticket is unknown. */
+    cancel(ticket: number): boolean;
+    /** Called once per finished ticket (within `update`) with its outcome. */
+    onDone: ((ticket: number, ok: boolean, out: NavPath3 | NavPath) => void) | null;
+}
+/** A queue of path searches over a mesh or a grid, sliced across `update()` calls. */
+export declare function createPathQueue(target: NavMesh | NavGrid, opts: PathQueueOptions): PathQueue;