@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/nav/mesh/areas.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Area types on a `NavMesh`: every polygon carries one byte (`mesh.area`, 0 by default) that a
+ * query multiplies its step cost by (`areaCost`) or filters on (`areaMask`). `markArea` stamps a
+ * box or a convex polygon onto the polygons whose centre it holds; a bake takes the same shapes
+ * as `areas`. Area 255 is reserved for dynamic obstacles and is never walked.
+ */
+import type { NavMesh } from './navmesh.js';
+/** The area byte dynamic obstacles stamp; every query treats it as blocked. */
+export declare const OBSTACLE_AREA = 255;
+/** An axis-aligned box on the XZ plane, with an optional height band. */
+export interface AreaBox {
+    minX: number;
+    minZ: number;
+    maxX: number;
+    maxZ: number;
+    /** Polygons whose centre lies outside `[minY, maxY]` are left alone. Default: any height. */
+    minY?: number;
+    maxY?: number;
+}
+/** A convex polygon on the XZ plane: `x, z` pairs in either winding, with an optional height band. */
+export interface AreaPolygon {
+    points: ArrayLike<number>;
+    minY?: number;
+    maxY?: number;
+}
+export type AreaShape = AreaBox | AreaPolygon;
+/** One stamp of a bake's `areas` list. */
+export interface AreaStamp {
+    shape: AreaShape;
+    /** The area byte, 0..254 (255 is reserved for obstacles). */
+    area: number;
+}
+/** Per-area cost multipliers (256 entries; `Infinity` excludes an area) with every area at 1. */
+export declare function createAreaCosts(fill?: number): Float32Array;
+/** Per-area walkability (256 entries; 0 excludes an area) with every area allowed. */
+export declare function createAreaMask(allow?: number): Uint8Array;
+/** Whether `(x, z)` lies inside the shape (edges included) and `y` within its height band. */
+export declare function areaShapeContains(shape: AreaShape, x: number, y: number, z: number): boolean;
+/**
+ * Sets `mesh.area[p] = area` for every polygon whose centre lies inside `shape`; polygons
+ * carrying the obstacle area (255) are left alone. Bumps `mesh.version` when any changed.
+ * Returns the number of polygons stamped. Edit-time; allocation-free.
+ */
+export declare function markArea(mesh: NavMesh, shape: AreaShape, area: number): number;

package/dist/nav/mesh/areas.js

@@ -0,0 +1,98 @@
+/** The area byte dynamic obstacles stamp; every query treats it as blocked. */
+export const OBSTACLE_AREA = 255;
+/** Per-area cost multipliers (256 entries; `Infinity` excludes an area) with every area at 1. */
+export function createAreaCosts(fill = 1) {
+    return new Float32Array(256).fill(fill);
+}
+/** Per-area walkability (256 entries; 0 excludes an area) with every area allowed. */
+export function createAreaMask(allow = 1) {
+    return new Uint8Array(256).fill(allow);
+}
+/** Whether `(x, z)` lies inside the shape (edges included) and `y` within its height band. */
+export function areaShapeContains(shape, x, y, z) {
+    if (shape.minY !== undefined && y < shape.minY)
+        return false;
+    if (shape.maxY !== undefined && y > shape.maxY)
+        return false;
+    if ('points' in shape) {
+        const pts = shape.points;
+        const n = pts.length >> 1;
+        if (n < 3)
+            return false;
+        // Inside a convex polygon when the point is on the same side of every edge.
+        let sign = 0;
+        for (let i = 0; i < n; i++) {
+            const j = i + 1 === n ? 0 : i + 1;
+            const ax = pts[i * 2];
+            const az = pts[i * 2 + 1];
+            const bx = pts[j * 2];
+            const bz = pts[j * 2 + 1];
+            const cross = (bx - ax) * (z - az) - (bz - az) * (x - ax);
+            if (cross === 0)
+                continue;
+            const s = cross > 0 ? 1 : -1;
+            if (sign === 0)
+                sign = s;
+            else if (s !== sign)
+                return false;
+        }
+        return true;
+    }
+    return x >= shape.minX && x <= shape.maxX && z >= shape.minZ && z <= shape.maxZ;
+}
+const centre = { x: 0, y: 0, z: 0 };
+/**
+ * Sets `mesh.area[p] = area` for every polygon whose centre lies inside `shape`; polygons
+ * carrying the obstacle area (255) are left alone. Bumps `mesh.version` when any changed.
+ * Returns the number of polygons stamped. Edit-time; allocation-free.
+ */
+export function markArea(mesh, shape, area) {
+    const a = Math.max(0, Math.min(254, Math.floor(area)));
+    let minX;
+    let minZ;
+    let maxX;
+    let maxZ;
+    if ('points' in shape) {
+        minX = minZ = Number.POSITIVE_INFINITY;
+        maxX = maxZ = Number.NEGATIVE_INFINITY;
+        const pts = shape.points;
+        for (let i = 0; i + 1 < pts.length; i += 2) {
+            const x = pts[i];
+            const z = pts[i + 1];
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (z < minZ)
+                minZ = z;
+            if (z > maxZ)
+                maxZ = z;
+        }
+    }
+    else {
+        minX = shape.minX;
+        minZ = shape.minZ;
+        maxX = shape.maxX;
+        maxZ = shape.maxZ;
+    }
+    let stamped = 0;
+    let changed = false;
+    const count = mesh.polysInBox(minX, minZ, maxX, maxZ);
+    const found = mesh.polysFound;
+    for (let i = 0; i < count; i++) {
+        const p = found[i];
+        mesh.polyCenter(p, centre);
+        if (!areaShapeContains(shape, centre.x, centre.y, centre.z))
+            continue;
+        if (mesh.area[p] === OBSTACLE_AREA)
+            continue;
+        stamped++;
+        if (mesh.area[p] !== a) {
+            mesh.area[p] = a;
+            changed = true;
+        }
+    }
+    if (changed)
+        mesh.version++;
+    return stamped;
+}

package/dist/nav/mesh/bake-options.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `NavBakeOptions` defaults and validation (ws/nav-6). Every numeric option but `cellSize` has a
+ * default derived from it, and a value that would bake NaN cells (non-finite, negative, out of
+ * range) throws a `NavBakeError` naming the option instead of yielding an empty mesh. Bake-time
+ * code; `scripts/bake-nav.mjs` resolves its options through the same function.
+ */
+import type { NavBakeOptions } from './voxelize.js';
+/** Thrown by `bakeNavMesh` (and `resolveNavBakeOptions`) for an option it cannot bake with. */
+export declare class NavBakeError extends Error {
+    /** The option's name, as in `NavBakeOptions`. */
+    readonly option: string;
+    /** The value given. */
+    readonly value: unknown;
+    constructor(option: string, value: unknown, rule: string);
+}
+/** `NavBakeOptions` with every default filled in. */
+export type ResolvedNavBakeOptions = Required<NavBakeOptions>;
+/** The fixed defaults; the rest derive from `cellSize` (see `resolveNavBakeOptions`). */
+export declare const NAV_BAKE_DEFAULTS: Readonly<{
+    agentHeight: 2;
+    agentMaxSlope: 45;
+    minRegionArea: 8;
+    mergeRegionArea: 20;
+    maxVertsPerPoly: 6;
+}>;
+/**
+ * Fills the defaults and validates: `cellHeight = cellSize / 2`, `agentHeight = 2`,
+ * `agentRadius = cellSize * 2`, `agentMaxClimb = cellHeight * 2`, `agentMaxSlope = 45`,
+ * `minRegionArea = 8`, `mergeRegionArea = 20`, `maxEdgeLength = 12 * cellSize`,
+ * `maxSimplification = 1.3 * cellSize`, `maxVertsPerPoly = 6`. Throws a `NavBakeError` for a
+ * missing `cellSize` or any value that is not a finite number in range.
+ */
+export declare function resolveNavBakeOptions(opts: NavBakeOptions): ResolvedNavBakeOptions;

package/dist/nav/mesh/bake-options.js

@@ -0,0 +1,76 @@
+/** Thrown by `bakeNavMesh` (and `resolveNavBakeOptions`) for an option it cannot bake with. */
+export class NavBakeError extends Error {
+    /** The option's name, as in `NavBakeOptions`. */
+    option;
+    /** The value given. */
+    value;
+    constructor(option, value, rule) {
+        super(`bakeNavMesh: ${option} must be ${rule}, got ${showValue(value)}`);
+        this.name = 'NavBakeError';
+        this.option = option;
+        this.value = value;
+    }
+}
+/** The fixed defaults; the rest derive from `cellSize` (see `resolveNavBakeOptions`). */
+export const NAV_BAKE_DEFAULTS = Object.freeze({
+    agentHeight: 2,
+    agentMaxSlope: 45,
+    minRegionArea: 8,
+    mergeRegionArea: 20,
+    maxVertsPerPoly: 6,
+});
+function showValue(v) {
+    if (typeof v === 'string')
+        return JSON.stringify(v);
+    if (typeof v === 'number' || typeof v === 'boolean' || v == null)
+        return String(v);
+    return typeof v;
+}
+function num(opts, key, fallback, min, minOpen, max = Number.POSITIVE_INFINITY) {
+    const v = opts[key];
+    if (v === undefined)
+        return fallback;
+    const rule = max === Number.POSITIVE_INFINITY
+        ? `a finite number ${minOpen ? '>' : '>='} ${min}`
+        : `a number in ${min}..${max}`;
+    if (typeof v !== 'number' || !Number.isFinite(v))
+        throw new NavBakeError(key, v, rule);
+    if (minOpen ? v <= min : v < min)
+        throw new NavBakeError(key, v, rule);
+    if (v > max)
+        throw new NavBakeError(key, v, rule);
+    return v;
+}
+/**
+ * Fills the defaults and validates: `cellHeight = cellSize / 2`, `agentHeight = 2`,
+ * `agentRadius = cellSize * 2`, `agentMaxClimb = cellHeight * 2`, `agentMaxSlope = 45`,
+ * `minRegionArea = 8`, `mergeRegionArea = 20`, `maxEdgeLength = 12 * cellSize`,
+ * `maxSimplification = 1.3 * cellSize`, `maxVertsPerPoly = 6`. Throws a `NavBakeError` for a
+ * missing `cellSize` or any value that is not a finite number in range.
+ */
+export function resolveNavBakeOptions(opts) {
+    if (opts === null || typeof opts !== 'object') {
+        throw new NavBakeError('options', opts, 'an object with a cellSize');
+    }
+    const cs = opts.cellSize;
+    if (typeof cs !== 'number' || !Number.isFinite(cs) || cs <= 0) {
+        throw new NavBakeError('cellSize', cs, 'a finite number > 0 (it has no default)');
+    }
+    const cellHeight = num(opts, 'cellHeight', cs / 2, 0, true);
+    const nvp = num(opts, 'maxVertsPerPoly', NAV_BAKE_DEFAULTS.maxVertsPerPoly, 3, false, 6);
+    if (!Number.isInteger(nvp))
+        throw new NavBakeError('maxVertsPerPoly', nvp, 'an integer in 3..6');
+    return {
+        cellSize: cs,
+        cellHeight,
+        agentHeight: num(opts, 'agentHeight', NAV_BAKE_DEFAULTS.agentHeight, 0, true),
+        agentRadius: num(opts, 'agentRadius', cs * 2, 0, false),
+        agentMaxClimb: num(opts, 'agentMaxClimb', cellHeight * 2, 0, false),
+        agentMaxSlope: num(opts, 'agentMaxSlope', NAV_BAKE_DEFAULTS.agentMaxSlope, 0, false, 90),
+        minRegionArea: num(opts, 'minRegionArea', NAV_BAKE_DEFAULTS.minRegionArea, 0, false),
+        mergeRegionArea: num(opts, 'mergeRegionArea', NAV_BAKE_DEFAULTS.mergeRegionArea, 0, false),
+        maxEdgeLength: num(opts, 'maxEdgeLength', 12 * cs, 0, false),
+        maxSimplification: num(opts, 'maxSimplification', 1.3 * cs, 0, false),
+        maxVertsPerPoly: nvp,
+    };
+}

package/dist/nav/mesh/contour.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Navmesh bake, stage three: contours. Each region's boundary is walked cell by cell, then
+ * simplified (points where the neighbouring region changes are kept, the rest within
+ * `maxError`), and long outer edges are split. Recast `rcBuildContours`, in cells; vertices are
+ * `x, y, z, flags` with the neighbour region in the low 16 bits of `flags`.
+ */
+import { type CompactHeightfield } from './voxelize.js';
+export declare const CONTOUR_REG_MASK = 65535;
+export declare const AREA_BORDER = 131072;
+export interface Contour {
+    /** Simplified vertices, `x, y, z, flags` per vertex (cells). */
+    verts: number[];
+    reg: number;
+    area: number;
+}
+/** Twice the signed area of a contour in the XZ plane. */
+export declare function contourArea2(verts: number[]): number;
+/**
+ * Builds one simplified contour per region. `maxError` and `maxEdgeLen` are in cells. A contour
+ * that comes out as a hole (reversed winding) cannot happen with hole-free regions and is dropped.
+ */
+export declare function buildContours(chf: CompactHeightfield, maxError: number, maxEdgeLen: number): Contour[];

package/dist/nav/mesh/contour.js

@@ -0,0 +1,323 @@
+/**
+ * Navmesh bake, stage three: contours. Each region's boundary is walked cell by cell, then
+ * simplified (points where the neighbouring region changes are kept, the rest within
+ * `maxError`), and long outer edges are split. Recast `rcBuildContours`, in cells; vertices are
+ * `x, y, z, flags` with the neighbour region in the low 16 bits of `flags`.
+ */
+import { DIR_X, DIR_Z, NOT_CONNECTED, NULL_AREA } from './voxelize.js';
+export const CONTOUR_REG_MASK = 0xffff;
+export const AREA_BORDER = 0x20000;
+function cornerHeight(i, dir, chf) {
+    let ch = chf.y[i];
+    const dirp = (dir + 1) & 3;
+    const ai = chf.con[i * 4 + dir];
+    if (ai !== NOT_CONNECTED) {
+        ch = Math.max(ch, chf.y[ai]);
+        const ai2 = chf.con[ai * 4 + dirp];
+        if (ai2 !== NOT_CONNECTED)
+            ch = Math.max(ch, chf.y[ai2]);
+    }
+    const bi = chf.con[i * 4 + dirp];
+    if (bi !== NOT_CONNECTED) {
+        ch = Math.max(ch, chf.y[bi]);
+        const bi2 = chf.con[bi * 4 + dir];
+        if (bi2 !== NOT_CONNECTED)
+            ch = Math.max(ch, chf.y[bi2]);
+    }
+    return ch;
+}
+function walkContour(x0, z0, i0, chf, flags, points) {
+    let x = x0;
+    let z = z0;
+    let i = i0;
+    let dir = 0;
+    while ((flags[i] & (1 << dir)) === 0)
+        dir++;
+    const startDir = dir;
+    const area = chf.areas[i];
+    let iter = 0;
+    while (++iter < 40000) {
+        if (flags[i] & (1 << dir)) {
+            let px = x;
+            const py = cornerHeight(i, dir, chf);
+            let pz = z;
+            switch (dir) {
+                case 0:
+                    pz++;
+                    break;
+                case 1:
+                    px++;
+                    pz++;
+                    break;
+                case 2:
+                    px++;
+                    break;
+                default:
+                    break;
+            }
+            let r = 0;
+            const ai = chf.con[i * 4 + dir];
+            if (ai !== NOT_CONNECTED) {
+                r = chf.regs[ai];
+                if (area !== chf.areas[ai])
+                    r |= AREA_BORDER;
+            }
+            points.push(px, py, pz, r);
+            flags[i] = flags[i] & ~(1 << dir);
+            dir = (dir + 1) & 3;
+        }
+        else {
+            const ni = chf.con[i * 4 + dir];
+            if (ni === NOT_CONNECTED)
+                return;
+            x += DIR_X[dir];
+            z += DIR_Z[dir];
+            i = ni;
+            dir = (dir + 3) & 3;
+        }
+        if (i0 === i && startDir === dir)
+            break;
+    }
+}
+/** Squared distance from a point to a segment, in the XZ plane. */
+function distancePtSeg(x, z, px, pz, qx, qz) {
+    const pqx = qx - px;
+    const pqz = qz - pz;
+    let dx = x - px;
+    let dz = z - pz;
+    const d = pqx * pqx + pqz * pqz;
+    let t = pqx * dx + pqz * dz;
+    if (d > 0)
+        t /= d;
+    if (t < 0)
+        t = 0;
+    else if (t > 1)
+        t = 1;
+    dx = px + t * pqx - x;
+    dz = pz + t * pqz - z;
+    return dx * dx + dz * dz;
+}
+function simplifyContour(points, simplified, maxError, maxEdgeLen) {
+    const pn = points.length / 4;
+    let hasConnections = false;
+    for (let i = 0; i < pn; i++) {
+        if ((points[i * 4 + 3] & CONTOUR_REG_MASK) !== 0) {
+            hasConnections = true;
+            break;
+        }
+    }
+    if (hasConnections) {
+        for (let i = 0; i < pn; i++) {
+            const ii = (i + 1) % pn;
+            const differentRegs = (points[i * 4 + 3] & CONTOUR_REG_MASK) !== (points[ii * 4 + 3] & CONTOUR_REG_MASK);
+            const areaBorders = (points[i * 4 + 3] & AREA_BORDER) !== (points[ii * 4 + 3] & AREA_BORDER);
+            if (differentRegs || areaBorders) {
+                simplified.push(points[i * 4], points[i * 4 + 1], points[i * 4 + 2], i);
+            }
+        }
+    }
+    if (simplified.length === 0) {
+        let llx = points[0];
+        let lly = points[1];
+        let llz = points[2];
+        let lli = 0;
+        let urx = points[0];
+        let ury = points[1];
+        let urz = points[2];
+        let uri = 0;
+        for (let i = 0; i < pn; i++) {
+            const x = points[i * 4];
+            const y = points[i * 4 + 1];
+            const z = points[i * 4 + 2];
+            if (x < llx || (x === llx && z < llz)) {
+                llx = x;
+                lly = y;
+                llz = z;
+                lli = i;
+            }
+            if (x > urx || (x === urx && z > urz)) {
+                urx = x;
+                ury = y;
+                urz = z;
+                uri = i;
+            }
+        }
+        simplified.push(llx, lly, llz, lli, urx, ury, urz, uri);
+    }
+    // Add points until every raw point is within the error of the simplified shape.
+    for (let i = 0; i < simplified.length / 4;) {
+        const n = simplified.length / 4;
+        const ii = (i + 1) % n;
+        let ax = simplified[i * 4];
+        let az = simplified[i * 4 + 2];
+        const ai = simplified[i * 4 + 3];
+        let bx = simplified[ii * 4];
+        let bz = simplified[ii * 4 + 2];
+        const bi = simplified[ii * 4 + 3];
+        let maxd = 0;
+        let maxi = -1;
+        let ci;
+        let cinc;
+        let endi;
+        // Traverse in lexicographic order so opposite traversals of a shared edge agree.
+        if (bx > ax || (bx === ax && bz > az)) {
+            cinc = 1;
+            ci = (ai + cinc) % pn;
+            endi = bi;
+        }
+        else {
+            cinc = pn - 1;
+            ci = (bi + cinc) % pn;
+            endi = ai;
+            const tx = ax;
+            ax = bx;
+            bx = tx;
+            const tz = az;
+            az = bz;
+            bz = tz;
+        }
+        // Tessellate only outer edges or edges between areas.
+        if ((points[ci * 4 + 3] & CONTOUR_REG_MASK) === 0 || points[ci * 4 + 3] & AREA_BORDER) {
+            while (ci !== endi) {
+                const d = distancePtSeg(points[ci * 4], points[ci * 4 + 2], ax, az, bx, bz);
+                if (d > maxd) {
+                    maxd = d;
+                    maxi = ci;
+                }
+                ci = (ci + cinc) % pn;
+            }
+        }
+        if (maxi !== -1 && maxd > maxError * maxError) {
+            simplified.splice((i + 1) * 4, 0, points[maxi * 4], points[maxi * 4 + 1], points[maxi * 4 + 2], maxi);
+        }
+        else {
+            i++;
+        }
+    }
+    // Split too long outer edges.
+    if (maxEdgeLen > 0) {
+        for (let i = 0; i < simplified.length / 4;) {
+            const n = simplified.length / 4;
+            const ii = (i + 1) % n;
+            const ax = simplified[i * 4];
+            const az = simplified[i * 4 + 2];
+            const ai = simplified[i * 4 + 3];
+            const bx = simplified[ii * 4];
+            const bz = simplified[ii * 4 + 2];
+            const bi = simplified[ii * 4 + 3];
+            let maxi = -1;
+            const ci = (ai + 1) % pn;
+            if ((points[ci * 4 + 3] & CONTOUR_REG_MASK) === 0) {
+                const dx = bx - ax;
+                const dz = bz - az;
+                if (dx * dx + dz * dz > maxEdgeLen * maxEdgeLen) {
+                    const cnt = bi < ai ? bi + pn - ai : bi - ai;
+                    if (cnt > 1) {
+                        if (bx > ax || (bx === ax && bz > az))
+                            maxi = (ai + (cnt >> 1)) % pn;
+                        else
+                            maxi = (ai + ((cnt + 1) >> 1)) % pn;
+                    }
+                }
+            }
+            if (maxi !== -1) {
+                simplified.splice((i + 1) * 4, 0, points[maxi * 4], points[maxi * 4 + 1], points[maxi * 4 + 2], maxi);
+            }
+            else {
+                i++;
+            }
+        }
+    }
+    for (let i = 0; i < simplified.length / 4; i++) {
+        // The neighbour region of an edge comes from the raw point after the vertex.
+        const ai = (simplified[i * 4 + 3] + 1) % pn;
+        simplified[i * 4 + 3] = points[ai * 4 + 3] & (CONTOUR_REG_MASK | AREA_BORDER);
+    }
+}
+function removeDegenerateSegments(simplified) {
+    let npts = simplified.length / 4;
+    for (let i = 0; i < npts; i++) {
+        const ni = (i + 1) % npts;
+        if (simplified[i * 4] === simplified[ni * 4] &&
+            simplified[i * 4 + 2] === simplified[ni * 4 + 2]) {
+            simplified.splice(i * 4, 4);
+            npts--;
+            i--;
+        }
+    }
+}
+/** Twice the signed area of a contour in the XZ plane. */
+export function contourArea2(verts) {
+    const n = verts.length / 4;
+    let area = 0;
+    for (let i = 0, j = n - 1; i < n; j = i++) {
+        area += verts[i * 4] * verts[j * 4 + 2] - verts[j * 4] * verts[i * 4 + 2];
+    }
+    return area;
+}
+/**
+ * Builds one simplified contour per region. `maxError` and `maxEdgeLen` are in cells. A contour
+ * that comes out as a hole (reversed winding) cannot happen with hole-free regions and is dropped.
+ */
+export function buildContours(chf, maxError, maxEdgeLen) {
+    const w = chf.width;
+    const h = chf.height;
+    const flags = new Uint8Array(chf.spanCount);
+    for (let z = 0; z < h; z++) {
+        for (let x = 0; x < w; x++) {
+            const c = x + z * w;
+            const end = chf.cellIndex[c] + chf.cellCount[c];
+            for (let i = chf.cellIndex[c]; i < end; i++) {
+                let res = 0;
+                if (chf.regs[i] === 0 || chf.areas[i] === NULL_AREA) {
+                    flags[i] = 0;
+                    continue;
+                }
+                for (let dir = 0; dir < 4; dir++) {
+                    const ai = chf.con[i * 4 + dir];
+                    const r = ai !== NOT_CONNECTED ? chf.regs[ai] : 0;
+                    if (r === chf.regs[i])
+                        res |= 1 << dir;
+                }
+                flags[i] = res ^ 0xf;
+            }
+        }
+    }
+    const contours = [];
+    const verts = [];
+    const simplified = [];
+    // The sign of a region's outer boundary, from the first contour built (all share the walk order).
+    let outerSign = 0;
+    for (let z = 0; z < h; z++) {
+        for (let x = 0; x < w; x++) {
+            const c = x + z * w;
+            const end = chf.cellIndex[c] + chf.cellCount[c];
+            for (let i = chf.cellIndex[c]; i < end; i++) {
+                if (flags[i] === 0 || flags[i] === 0xf) {
+                    flags[i] = 0;
+                    continue;
+                }
+                const reg = chf.regs[i];
+                if (reg === 0)
+                    continue;
+                const area = chf.areas[i];
+                verts.length = 0;
+                simplified.length = 0;
+                walkContour(x, z, i, chf, flags, verts);
+                simplifyContour(verts, simplified, maxError, maxEdgeLen);
+                removeDegenerateSegments(simplified);
+                if (simplified.length / 4 >= 3) {
+                    const a = contourArea2(simplified);
+                    if (a === 0)
+                        continue;
+                    if (outerSign === 0)
+                        outerSign = a > 0 ? 1 : -1;
+                    if ((a > 0 ? 1 : -1) !== outerSign)
+                        continue;
+                    contours.push({ verts: simplified.slice(), reg, area });
+                }
+            }
+        }
+    }
+    return contours;
+}

package/dist/nav/mesh/flow3.d.ts

@@ -0,0 +1,35 @@
+import { type AreaQueryOptions } from './mesh-path.js';
+import type { NavMesh, NavPoint3 } from './navmesh.js';
+export interface FlowField3Options extends AreaQueryOptions {
+    /** Snap each goal to the nearest polygon within this radius. Default: unbounded. */
+    snapRadius?: number;
+}
+export interface FlowField3 {
+    readonly mesh: NavMesh;
+    /** Per polygon: cost-weighted distance to the nearest goal (`Infinity` unreachable). */
+    readonly distances: Float64Array;
+    /** Per polygon: the polygon it flows to (-1 at a goal or unreachable). */
+    readonly next: Int32Array;
+    /** Per polygon: the portal edge index into `next` (-1 at a goal or unreachable). */
+    readonly portal: Int32Array;
+    /** The mesh version the field was built from. */
+    readonly version: number;
+    /** True when the mesh changed since the build. */
+    readonly stale: boolean;
+    /** Rebuilds the field when stale (or always, with `force`); returns whether it rebuilt. */
+    update(force?: boolean): boolean;
+    /** The polygon count reached from a goal in the last build. */
+    readonly reached: number;
+    /**
+     * The unit direction to walk from `(x, y, z)` into `out` (zero at a goal, off the mesh or
+     * where no goal is reachable). Returns the polygon under the point, or -1.
+     */
+    direction3(x: number, y: number, z: number, out: NavPoint3): number;
+    /**
+     * The cost-weighted distance to the nearest goal from `(x, y, z)` along the field (through
+     * the polygon's exit portal); `Infinity` off the mesh or where no goal is reachable.
+     */
+    distanceAt(x: number, y: number, z: number): number;
+}
+/** Builds a flow field toward `goals` (points on the mesh) and keeps it current. */
+export declare function createFlowField3(mesh: NavMesh, goals: readonly Readonly<NavPoint3>[], opts?: FlowField3Options): FlowField3;