@vgai/engine 0.5.36 → 0.5.37

package/dist/ai/navigation.d.ts

@@ -12,7 +12,8 @@
 import { NavMeshHelper } from '@recast-navigation/three';
 import type { CrowdAgent } from 'recast-navigation';
 import { Crowd } from 'recast-navigation';
-import type { Mesh, Scene } from 'three';
+import type { Scene } from 'three';
+import { Mesh } from 'three';
 export type { CrowdAgent };
 export interface Vector3Like {
     x: number;
@@ -39,6 +40,12 @@ export interface CrowdAgentSnapshot {
     corners: Vector3Like[];
 }
 export interface NavMeshBuildParams {
+    /** Force bounded tiled generation for imported large-world scenes whose instanced render
+     * census cannot be inferred from the source BufferGeometry counts alone. */
+    tiled?: boolean | undefined;
+    /** Recast tile width/height in voxels. Unity's NavMeshSurface default is 256; keeping tiles at
+     * that scale also avoids thousands of empty-tile allocations across sparse imported worlds. */
+    tileSize?: number | undefined;
     cellSize?: number | undefined;
     cellHeight?: number | undefined;
     walkableSlopeAngle?: number | undefined;

package/dist/ai/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/ai/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAoD,MAAM,mBAAmB,CAAC;AAC5F,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAGzC,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;iEACiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf;;8EAE0E;IAC1E,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC;+EAC2E;IAC3E,MAAM,EAAE,WAAW,CAAC;IACpB;;mEAE+D;IAC/D,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAKD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAID,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAA8B;IAE5C,2EAA2E;IAC3E,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO;IA4BrE;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAoBrB,iFAAiF;IACjF,UAAU,IAAI,OAAO;IAIrB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,WAAW,EAAE;IAkB7D,kDAAkD;IAClD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK;IAMrC,sDAAsD;IACtD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,cAAc,IAAI,kBAAkB,EAAE;IAwBtC,iGAAiG;IACjG,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI;IAShD,sDAAsD;IACtD,UAAU,IAAI,UAAU;IAKxB,6DAA6D;IAC7D,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQpC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAM5B"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/ai/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAA2C,MAAM,0BAA0B,CAAC;AAClG,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAoD,MAAM,mBAAmB,CAAC;AAC5F,OAAO,KAAK,EAAkB,KAAK,EAAE,MAAM,OAAO,CAAC;AACnD,OAAO,EAA0B,IAAI,EAAE,MAAM,OAAO,CAAC;AAGrD,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,WAAW;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;iEACiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf;;8EAE0E;IAC1E,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC;+EAC2E;IAC3E,MAAM,EAAE,WAAW,CAAC;IACpB;;mEAE+D;IAC/D,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAKD,MAAM,WAAW,kBAAkB;IACjC;gFAC4E;IAC5E,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B;mGAC+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAID,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AA2ED,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAA8B;IAE5C,2EAA2E;IAC3E,eAAe,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO;IA+CrE;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAoBrB,iFAAiF;IACjF,UAAU,IAAI,OAAO;IAIrB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,WAAW,GAAG,WAAW,EAAE;IAkB7D,kDAAkD;IAClD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,KAAK;IAMrC,sDAAsD;IACtD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,cAAc,IAAI,kBAAkB,EAAE;IAwBtC,iGAAiG;IACjG,YAAY,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,IAAI;IAShD,sDAAsD;IACtD,UAAU,IAAI,UAAU;IAKxB,6DAA6D;IAC7D,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAQpC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;CAM5B"}

package/dist/ai/navigation.js

@@ -9,8 +9,9 @@
  *   const crowd = nav.createCrowd(10);
  *   // In game loop: nav.updateCrowd(dt);
  */
-import { NavMeshHelper, threeToSoloNavMesh } from '@recast-navigation/three';
+import { NavMeshHelper, threeToSoloNavMesh, threeToTiledNavMesh } from '@recast-navigation/three';
 import { Crowd, exportNavMesh, importNavMesh, init, NavMeshQuery } from 'recast-navigation';
+import { InstancedMesh, Matrix4, Mesh } from 'three';
 import { DEFAULTS } from '../defaults';
 /** Detour `CrowdAgentState` values, named. */
 const AGENT_STATES = ['invalid', 'walking', 'offmesh'];
@@ -21,6 +22,74 @@ export async function initNavigation() {
     await init();
     wasmInitialized = true;
 }
+/**
+ * `@recast-navigation/three` applies each mesh's world matrix to its positions but copies the
+ * source indices unchanged. A mirrored world matrix therefore reverses every triangle and can
+ * make a visibly upward floor entirely unwalkable. Seat a winding-corrected geometry on an
+ * equivalent root mesh for the bake; the game keeps its own native mesh untouched.
+ */
+function reverseTriangleWinding(geometry) {
+    const index = geometry.getIndex();
+    if (index === null) {
+        const position = geometry.getAttribute('position').clone();
+        for (let vertex = 0; vertex + 2 < position.count; vertex += 3) {
+            for (let component = 0; component < position.itemSize; component += 1) {
+                const middle = position.getComponent(vertex + 1, component);
+                position.setComponent(vertex + 1, component, position.getComponent(vertex + 2, component));
+                position.setComponent(vertex + 2, component, middle);
+            }
+        }
+        geometry.setAttribute('position', position);
+        return;
+    }
+    for (let triangle = 0; triangle + 2 < index.count; triangle += 3) {
+        const middle = index.getX(triangle + 1);
+        index.setX(triangle + 1, index.getX(triangle + 2));
+        index.setX(triangle + 2, middle);
+    }
+    index.needsUpdate = true;
+}
+function recastInputMeshes(meshes) {
+    const temporaryGeometries = [];
+    const mirroredGeometries = new WeakMap();
+    const geometryForMatrix = (source, matrix) => {
+        if (matrix.determinant() >= 0)
+            return source;
+        const cached = mirroredGeometries.get(source);
+        if (cached !== undefined)
+            return cached;
+        const geometry = source.clone();
+        reverseTriangleWinding(geometry);
+        mirroredGeometries.set(source, geometry);
+        temporaryGeometries.push(geometry);
+        return geometry;
+    };
+    const proxyAt = (geometry, matrix) => {
+        const proxy = new Mesh(geometryForMatrix(geometry, matrix));
+        // The proxy has no parent, so its local matrix is the source mesh's complete world matrix.
+        // The recast bridge calls updateMatrixWorld() itself; disabling auto-update preserves it.
+        proxy.matrixAutoUpdate = false;
+        proxy.matrix.copy(matrix);
+        proxy.matrixWorldNeedsUpdate = true;
+        return proxy;
+    };
+    const corrected = [];
+    const instanceMatrix = new Matrix4();
+    const worldMatrix = new Matrix4();
+    for (const mesh of meshes) {
+        mesh.updateWorldMatrix(true, false);
+        if (mesh instanceof InstancedMesh) {
+            for (let instance = 0; instance < mesh.count; instance += 1) {
+                mesh.getMatrixAt(instance, instanceMatrix);
+                worldMatrix.multiplyMatrices(mesh.matrixWorld, instanceMatrix);
+                corrected.push(proxyAt(mesh.geometry, worldMatrix));
+            }
+            continue;
+        }
+        corrected.push(mesh.matrixWorld.determinant() >= 0 ? mesh : proxyAt(mesh.geometry, mesh.matrixWorld));
+    }
+    return { meshes: corrected, temporaryGeometries };
+}
 export class NavMeshManager {
     navMesh = null;
     query = null;
@@ -29,7 +98,13 @@ export class NavMeshManager {
     /** Build navmesh from Three.js Mesh objects (grounds, obstacles, etc.). */
     buildFromMeshes(meshes, params) {
         const d = DEFAULTS.navigation;
-        const result = threeToSoloNavMesh(meshes, {
+        const input = recastInputMeshes(meshes);
+        const triangleCount = input.meshes.reduce((total, mesh) => {
+            const index = mesh.geometry.getIndex();
+            const vertices = mesh.geometry.getAttribute('position').count;
+            return total + Math.floor((index?.count ?? vertices) / 3);
+        }, 0);
+        const config = {
             cs: params?.cellSize ?? d.cellSize,
             ch: params?.cellHeight ?? d.cellHeight,
             walkableSlopeAngle: params?.walkableSlopeAngle ?? d.walkableSlopeAngle,
@@ -44,7 +119,22 @@ export class NavMeshManager {
             maxVertsPerPoly: 6,
             detailSampleDist: 6,
             detailSampleMaxError: 1,
-        });
+        };
+        // A solo heightfield allocates for the whole scene at once. Large imported Unity scenes can
+        // exceed Recast's WASM address space during rasterization even though every individual mesh
+        // is ordinary-sized. Tiled generation is the library's native large-world path and keeps the
+        // same NavMesh result/API while bounding each rasterization allocation.
+        let result;
+        try {
+            result =
+                params?.tiled === true || input.meshes.length > 256 || triangleCount > 10_000
+                    ? threeToTiledNavMesh(input.meshes, { ...config, tileSize: params?.tileSize ?? 256 })
+                    : threeToSoloNavMesh(input.meshes, config);
+        }
+        finally {
+            for (const geometry of input.temporaryGeometries)
+                geometry.dispose();
+        }
         if (!result.success || !result.navMesh)
             return false;
         // Free the previous recast objects before replacing them (WASM heap leak).

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.36",
+  "version": "0.5.37",
   "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
   "keywords": [
     "game-engine",

package/src/ai/navigation.ts

@@ -10,10 +10,11 @@
  *   // In game loop: nav.updateCrowd(dt);
  */
 
-import { NavMeshHelper, threeToSoloNavMesh } from '@recast-navigation/three';
+import { NavMeshHelper, threeToSoloNavMesh, threeToTiledNavMesh } from '@recast-navigation/three';
 import type { CrowdAgent, NavMesh } from 'recast-navigation';
 import { Crowd, exportNavMesh, importNavMesh, init, NavMeshQuery } from 'recast-navigation';
-import type { Mesh, Scene } from 'three';
+import type { BufferGeometry, Scene } from 'three';
+import { InstancedMesh, Matrix4, Mesh } from 'three';
 import { DEFAULTS } from '../defaults';
 
 export type { CrowdAgent };
@@ -48,6 +49,12 @@ export interface CrowdAgentSnapshot {
 const AGENT_STATES = ['invalid', 'walking', 'offmesh'] as const;
 
 export interface NavMeshBuildParams {
+  /** Force bounded tiled generation for imported large-world scenes whose instanced render
+   * census cannot be inferred from the source BufferGeometry counts alone. */
+  tiled?: boolean | undefined;
+  /** Recast tile width/height in voxels. Unity's NavMeshSurface default is 256; keeping tiles at
+   * that scale also avoids thousands of empty-tile allocations across sparse imported worlds. */
+  tileSize?: number | undefined;
   cellSize?: number | undefined;
   cellHeight?: number | undefined;
   walkableSlopeAngle?: number | undefined;
@@ -68,6 +75,79 @@ export async function initNavigation(): Promise<void> {
   wasmInitialized = true;
 }
 
+/**
+ * `@recast-navigation/three` applies each mesh's world matrix to its positions but copies the
+ * source indices unchanged. A mirrored world matrix therefore reverses every triangle and can
+ * make a visibly upward floor entirely unwalkable. Seat a winding-corrected geometry on an
+ * equivalent root mesh for the bake; the game keeps its own native mesh untouched.
+ */
+function reverseTriangleWinding(geometry: BufferGeometry): void {
+  const index = geometry.getIndex();
+  if (index === null) {
+    const position = geometry.getAttribute('position').clone();
+    for (let vertex = 0; vertex + 2 < position.count; vertex += 3) {
+      for (let component = 0; component < position.itemSize; component += 1) {
+        const middle = position.getComponent(vertex + 1, component);
+        position.setComponent(vertex + 1, component, position.getComponent(vertex + 2, component));
+        position.setComponent(vertex + 2, component, middle);
+      }
+    }
+    geometry.setAttribute('position', position);
+    return;
+  }
+  for (let triangle = 0; triangle + 2 < index.count; triangle += 3) {
+    const middle = index.getX(triangle + 1);
+    index.setX(triangle + 1, index.getX(triangle + 2));
+    index.setX(triangle + 2, middle);
+  }
+  index.needsUpdate = true;
+}
+
+function recastInputMeshes(meshes: Mesh[]): {
+  readonly meshes: Mesh[];
+  readonly temporaryGeometries: BufferGeometry[];
+} {
+  const temporaryGeometries: BufferGeometry[] = [];
+  const mirroredGeometries = new WeakMap<BufferGeometry, BufferGeometry>();
+  const geometryForMatrix = (source: BufferGeometry, matrix: Matrix4): BufferGeometry => {
+    if (matrix.determinant() >= 0) return source;
+    const cached = mirroredGeometries.get(source);
+    if (cached !== undefined) return cached;
+    const geometry = source.clone();
+    reverseTriangleWinding(geometry);
+    mirroredGeometries.set(source, geometry);
+    temporaryGeometries.push(geometry);
+    return geometry;
+  };
+  const proxyAt = (geometry: BufferGeometry, matrix: Matrix4): Mesh => {
+    const proxy = new Mesh(geometryForMatrix(geometry, matrix));
+    // The proxy has no parent, so its local matrix is the source mesh's complete world matrix.
+    // The recast bridge calls updateMatrixWorld() itself; disabling auto-update preserves it.
+    proxy.matrixAutoUpdate = false;
+    proxy.matrix.copy(matrix);
+    proxy.matrixWorldNeedsUpdate = true;
+    return proxy;
+  };
+  const corrected: Mesh[] = [];
+  const instanceMatrix = new Matrix4();
+  const worldMatrix = new Matrix4();
+  for (const mesh of meshes) {
+    mesh.updateWorldMatrix(true, false);
+    if (mesh instanceof InstancedMesh) {
+      for (let instance = 0; instance < mesh.count; instance += 1) {
+        mesh.getMatrixAt(instance, instanceMatrix);
+        worldMatrix.multiplyMatrices(mesh.matrixWorld, instanceMatrix);
+        corrected.push(proxyAt(mesh.geometry, worldMatrix));
+      }
+      continue;
+    }
+    corrected.push(
+      mesh.matrixWorld.determinant() >= 0 ? mesh : proxyAt(mesh.geometry, mesh.matrixWorld),
+    );
+  }
+  return { meshes: corrected, temporaryGeometries };
+}
+
 export class NavMeshManager {
   private navMesh: NavMesh | null = null;
   private query: NavMeshQuery | null = null;
@@ -77,7 +157,13 @@ export class NavMeshManager {
   /** Build navmesh from Three.js Mesh objects (grounds, obstacles, etc.). */
   buildFromMeshes(meshes: Mesh[], params?: NavMeshBuildParams): boolean {
     const d = DEFAULTS.navigation;
-    const result = threeToSoloNavMesh(meshes, {
+    const input = recastInputMeshes(meshes);
+    const triangleCount = input.meshes.reduce((total, mesh) => {
+      const index = mesh.geometry.getIndex();
+      const vertices = mesh.geometry.getAttribute('position').count;
+      return total + Math.floor((index?.count ?? vertices) / 3);
+    }, 0);
+    const config = {
       cs: params?.cellSize ?? d.cellSize,
       ch: params?.cellHeight ?? d.cellHeight,
       walkableSlopeAngle: params?.walkableSlopeAngle ?? d.walkableSlopeAngle,
@@ -92,7 +178,20 @@ export class NavMeshManager {
       maxVertsPerPoly: 6,
       detailSampleDist: 6,
       detailSampleMaxError: 1,
-    });
+    };
+    // A solo heightfield allocates for the whole scene at once. Large imported Unity scenes can
+    // exceed Recast's WASM address space during rasterization even though every individual mesh
+    // is ordinary-sized. Tiled generation is the library's native large-world path and keeps the
+    // same NavMesh result/API while bounding each rasterization allocation.
+    let result: ReturnType<typeof threeToSoloNavMesh> | ReturnType<typeof threeToTiledNavMesh>;
+    try {
+      result =
+        params?.tiled === true || input.meshes.length > 256 || triangleCount > 10_000
+          ? threeToTiledNavMesh(input.meshes, { ...config, tileSize: params?.tileSize ?? 256 })
+          : threeToSoloNavMesh(input.meshes, config);
+    } finally {
+      for (const geometry of input.temporaryGeometries) geometry.dispose();
+    }
 
     if (!result.success || !result.navMesh) return false;