@jgengine/navbake 0.18.0 → 0.19.0

package/README.md

@@ -1,3 +1,13 @@
 # @jgengine/navbake
 
-Deterministic navigation-mesh baking for authored JGengine geometry.
+Deterministic navigation-mesh baking for authored JGengine geometry, backed by [recast-navigation](https://github.com/isaac-mason/recast-navigation-js).
+
+```ts
+import { bakeNavMesh, initNavBake } from "@jgengine/navbake";
+import { createNavMeshQuery } from "@jgengine/core/nav/navMesh";
+
+await initNavBake();
+const mesh = bakeNavMesh({ positions, indices, agentRadius: 0.4, agentHeight: 1.8, maxSlope: 45, maxClimb: 0.4 });
+```
+
+Walkable triangles wind counter-clockwise seen from above (three.js front faces up). The result is plain `NavMeshData`: store it as an editor `nav` bake and route on it with `@jgengine/core/nav/navMesh`.

package/dist/index.d.ts

@@ -1,11 +1,29 @@
 import type { NavMeshData } from "@jgengine/core/nav/navMesh";
+/** Walkable geometry and agent dimensions for {@link bakeNavMesh}. */
 export interface BakeNavMeshOptions {
+    /** Flat xyz triples. */
     positions: readonly number[];
+    /** Triangle vertex indices, counter-clockwise seen from above for walkable faces (three.js front faces up). */
     indices: readonly number[];
     agentRadius: number;
     agentHeight: number;
+    /** Steepest walkable slope in degrees. */
     maxSlope: number;
+    /** Tallest ledge the agent steps up. */
     maxClimb: number;
+    /** Voxel size on XZ; defaults to half the agent radius. Smaller is more exact and slower. */
+    cellSize?: number;
+    /** Voxel size on Y; defaults to half the cell size. */
+    cellHeight?: number;
 }
-/** Bake indexed walkable triangles into the engine's serializable nav-mesh format. */
+/** Load the recast WebAssembly module once; await before the first {@link bakeNavMesh}. */
+export declare function initNavBake(): Promise<void>;
+/** Whether {@link initNavBake} has finished and {@link bakeNavMesh} can run synchronously. */
+export declare function navBakeReady(): boolean;
+/**
+ * Voxelize indexed triangles with recast and return the walkable surface as convex polygons in the engine's
+ * serializable nav-mesh format: eroded by `agentRadius`, cut where clearance is under `agentHeight`, and split
+ * at slopes over `maxSlope` or steps over `maxClimb`. Requires {@link initNavBake}.
+ * @capability navmesh-bake voxelize scene triangles into an agent-sized polygon nav mesh
+ */
 export declare function bakeNavMesh(options: BakeNavMeshOptions): NavMeshData;

package/dist/index.js

@@ -1,27 +1,103 @@
-function triangleSlope(positions, a, b, c) {
-    const ax = positions[a * 3], ay = positions[a * 3 + 1], az = positions[a * 3 + 2];
-    const bx = positions[b * 3], by = positions[b * 3 + 1], bz = positions[b * 3 + 2];
-    const cx = positions[c * 3], cy = positions[c * 3 + 1], cz = positions[c * 3 + 2];
-    const ux = bx - ax, uy = by - ay, uz = bz - az;
-    const vx = cx - ax, vy = cy - ay, vz = cz - az;
-    const ny = ux * vz - uz * vx;
-    const nx = uy * vz - uz * vy;
-    const nz = ux * vy - uy * vx;
-    return Math.atan2(Math.hypot(nx, nz), Math.abs(ny)) * 180 / Math.PI;
+import { freeCompactHeightfield, freeContourSet, freeHeightfield, freePolyMesh, freePolyMeshDetail, init } from "recast-navigation";
+import { generateSoloNavMesh } from "recast-navigation/generators";
+let ready = false;
+let loading = null;
+/** Load the recast WebAssembly module once; await before the first {@link bakeNavMesh}. */
+export function initNavBake() {
+    loading ??= init().then(() => {
+        ready = true;
+    }, (error) => {
+        loading = null;
+        throw error;
+    });
+    return loading;
 }
-/** Bake indexed walkable triangles into the engine's serializable nav-mesh format. */
+/** Whether {@link initNavBake} has finished and {@link bakeNavMesh} can run synchronously. */
+export function navBakeReady() {
+    return ready;
+}
+function freeIntermediates(intermediates) {
+    if (intermediates.heightfield)
+        freeHeightfield(intermediates.heightfield);
+    if (intermediates.compactHeightfield)
+        freeCompactHeightfield(intermediates.compactHeightfield);
+    if (intermediates.contourSet)
+        freeContourSet(intermediates.contourSet);
+    if (intermediates.polyMesh)
+        freePolyMesh(intermediates.polyMesh);
+    if (intermediates.polyMeshDetail)
+        freePolyMeshDetail(intermediates.polyMeshDetail);
+}
+function round(value) {
+    return Math.round(value * 1e4) / 1e4;
+}
+/**
+ * Voxelize indexed triangles with recast and return the walkable surface as convex polygons in the engine's
+ * serializable nav-mesh format: eroded by `agentRadius`, cut where clearance is under `agentHeight`, and split
+ * at slopes over `maxSlope` or steps over `maxClimb`. Requires {@link initNavBake}.
+ * @capability navmesh-bake voxelize scene triangles into an agent-sized polygon nav mesh
+ */
 export function bakeNavMesh(options) {
+    if (!ready)
+        throw new Error("bakeNavMesh: await initNavBake() before baking");
     if (options.positions.length % 3 !== 0)
         throw new Error("positions must contain xyz triples");
     if (options.indices.length % 3 !== 0)
         throw new Error("indices must contain triangle triples");
-    const polys = [];
-    for (let i = 0; i < options.indices.length; i += 3) {
-        const a = options.indices[i], b = options.indices[i + 1], c = options.indices[i + 2];
-        if (a < 0 || b < 0 || c < 0 || a * 3 + 2 >= options.positions.length || b * 3 + 2 >= options.positions.length || c * 3 + 2 >= options.positions.length)
-            continue;
-        if (triangleSlope(options.positions, a, b, c) <= Math.max(0, options.maxSlope))
-            polys.push([a, b, c]);
+    if (!(options.agentRadius >= 0) || !(options.agentHeight > 0) || !(options.maxClimb >= 0)) {
+        throw new Error("agentRadius and maxClimb must be non-negative and agentHeight positive");
+    }
+    const vertexCount = options.positions.length / 3;
+    for (const index of options.indices) {
+        if (!Number.isInteger(index) || index < 0 || index >= vertexCount)
+            throw new Error(`index ${index} is out of range`);
+    }
+    if (options.indices.length === 0)
+        return { verts: [], polys: [], links: [] };
+    const cs = options.cellSize ?? Math.max(0.05, options.agentRadius / 2);
+    const ch = options.cellHeight ?? cs / 2;
+    const result = generateSoloNavMesh(options.positions, options.indices, {
+        cs,
+        ch,
+        walkableRadius: Math.ceil(options.agentRadius / cs),
+        walkableHeight: Math.ceil(options.agentHeight / ch),
+        walkableClimb: Math.floor(options.maxClimb / ch),
+        walkableSlopeAngle: Math.min(90, Math.max(0, options.maxSlope)),
+        maxVertsPerPoly: 6,
+    }, true);
+    // Detour refuses to build from zero polygons, so an all-unwalkable input is told apart from a real failure here.
+    const walkable = (result.intermediates.polyMesh?.npolys() ?? 0) > 0;
+    freeIntermediates(result.intermediates);
+    if (!result.success) {
+        if (!walkable)
+            return { verts: [], polys: [], links: [] };
+        throw new Error(`bakeNavMesh: ${result.error}`);
+    }
+    const navMesh = result.navMesh;
+    try {
+        const verts = [];
+        const polys = [];
+        for (let t = 0; t < navMesh.getMaxTiles(); t += 1) {
+            const tile = navMesh.getTile(t);
+            const header = tile.header();
+            if (header === null)
+                continue;
+            const base = verts.length / 3;
+            for (let i = 0; i < header.vertCount() * 3; i += 1)
+                verts.push(round(tile.verts(i)));
+            for (let p = 0; p < header.polyCount(); p += 1) {
+                const poly = tile.polys(p);
+                if (poly.getType() !== 0)
+                    continue;
+                const ring = [];
+                for (let k = 0; k < poly.vertCount(); k += 1)
+                    ring.push(base + poly.verts(k));
+                polys.push(ring);
+            }
+        }
+        return { verts, polys, links: [] };
+    }
+    finally {
+        navMesh.destroy();
     }
-    return { verts: Array.from(options.positions), polys, links: [] };
 }

package/package.json

@@ -1,14 +1,41 @@
 {
   "name": "@jgengine/navbake",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Deterministic navigation-mesh baking for JGengine scenes.",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
-  "repository": { "type": "git", "url": "git+https://github.com/Noisemaker111/jgengine.git", "directory": "packages/navbake" },
-  "files": ["dist", "README.md", "LICENSE", "NOTICE"],
-  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }, "./*": { "types": "./dist/*.d.ts", "default": "./dist/*.js" } },
-  "scripts": { "build": "tsgo -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist", "check-types": "bun ../../scripts/check-types-preflight.ts && tsgo --noEmit -p tsconfig.json", "test": "bun test src" },
-  "dependencies": { "@jgengine/core": "^0.18.0", "recast-navigation": "^0.34.0" },
-  "publishConfig": { "access": "public" }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Noisemaker111/jgengine.git",
+    "directory": "packages/navbake"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json && bun ../../scripts/fix-extensions.ts dist",
+    "check-types": "bun ../../scripts/check-types-preflight.ts && tsgo --noEmit -p tsconfig.json",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@jgengine/core": "^0.19.0",
+    "recast-navigation": "^0.34.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }