@recast-navigation/three 0.0.0-canary-20261030-064e4acc

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright © 2025 Isaac Mason
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# @recast-navigation/three
+
+Three.js nav mesh generation and visualisation helpers for [`recast-navigation`](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation).
+
+## Installation
+
+```bash
+> npm install @recast-navigation/three recast-navigation
+```
+
+## Usage
+
+### Importing
+
+To import the three.js glue, you can either use the `three` entrypoint in `recast-navigation`:
+
+```ts
+import { init } from 'recast-navigation'
+import { ... } from '@recast-navigation/three';
+```
+
+Or you can use the packages directly:
+
+```ts
+import { init } from '@recast-navigation/core'
+import { ... } from '@recast-navigation/three';
+```
+
+### Initialization
+
+Before you can use the library, you must initialize it. This is an asynchronous operation.
+
+Calling `init()` after the library has already been initialized will return a promise that resolves immediately.
+
+```ts
+import { init } from 'recast-navigation';
+
+await init();
+```
+
+### Generating a NavMesh
+
+This package provides convenience functions for generating nav meshes from THREE.Mesh objects.
+
+```ts
+import { init } from 'recast-navigation';
+import { threeToSoloNavMesh, threeToTiledNavMesh, threeToTileCache } from '@recast-navigation/three';
+import * as THREE from 'three';
+
+/* initialize the library */
+await init();
+
+/* create your scene */
+const scene = new THREE.Scene();
+// ...
+
+/* get meshes to generate the navmesh from */
+const meshes: THREE.Mesh[] = [];
+scene.traverse((child) => {
+  if (child instanceof THREE.Mesh) {
+    meshes.push(child);
+  }
+});
+
+/* generate a solo navmesh */
+const { success, navMesh } = threeToSoloNavMesh(meshes, {
+  // ... nav mesh generation config ...
+}});
+
+/* generate a tiled navmesh */
+const { success, navMesh } = threeToTiledNavMesh(meshes, {
+  tileSize: 16,
+  // ... nav mesh generation config ...
+}});
+
+/* generate a tile cache with support for temporary obstacles */
+const { success, navMesh, tileCache } = threeToTileCache(meshes, {
+  tileSize: 16,
+  // ... nav mesh generation config ...
+}});
+```
+
+### Interacting with a NavMesh
+
+You can documentation for interacting with the generated navmesh in the core library README:
+
+https://github.com/isaac-mason/recast-navigation-js
+
+This library provides helpers that are used in conjunction with the core library.
+
+### Debug Drawer
+
+This package provides a `DebugDrawer` utility that can visualise a navmesh and other generation intermediates.
+
+```ts
+import { DebugDrawer } from '@recast-navigation/three';
+
+const debugDrawer = new DebugDrawer();
+
+// draw a navmesh
+debugDrawer.drawNavMesh(navMesh);
+
+// clear the debug drawer
+debugDrawer.reset();
+
+// dispose of threejs and wasm resources
+debugDrawer.dispose();
+```
+
+See the debug examples for more: https://recast-navigation-js.isaacmason.com/examples/#example-debug-navmesh
+
+### Helpers
+
+This package provides helpers for visualizing various recast-navigation objects in three.js.
+
+#### `NavMeshHelper`
+
+```ts
+import { NavMeshHelper } from '@recast-navigation/three';
+
+const navMeshHelper = new NavMeshHelper(navMesh);
+
+scene.add(navMeshHelper);
+
+// update the helper when the navmesh changes
+navMeshHelper.update();
+```
+
+#### `TileCacheHelper`
+
+Visualises obstacles in a `TileCache`.
+
+```ts
+import { TileCacheHelper } from '@recast-navigation/three';
+
+const tileCacheHelper = new TileCacheHelper(tileCache);
+
+scene.add(tileCacheHelper);
+
+// update the helper after adding or removing obstacles
+tileCacheHelper.update();
+```
+
+#### `CrowdHelper`
+
+Visualises agents in a `Crowd`.
+
+```ts
+import { CrowdHelper } from '@recast-navigation/three';
+
+const crowdHelper = new CrowdHelper(crowd);
+
+scene.add(crowdHelper);
+
+// update the helper after updating the crowd
+crowdHelper.update();
+```
+
+#### Custom Materials
+
+You can optionally provide custom materials to the helpers.
+
+```ts
+// NavMeshHelper
+const navMeshMaterial = new THREE.MeshBasicMaterial({ color: 'red' });
+const navMeshHelper = new NavMeshHelper(navMesh, {
+  navMeshMaterial,
+});
+
+// TileCacheHelper
+const obstacleMaterial = new THREE.MeshBasicMaterial({ color: 'blue' });
+const tileCacheHelper = new TileCacheHelper(tileCache, {
+  obstacleMaterial,
+});
+
+// CrowdHelper
+const agentMaterial = new THREE.MeshBasicMaterial({ color: 'red' });
+const crowdHelper = new CrowdHelper(crowd, {
+  agentMaterial,
+});
+```

package/dist/debug/debug-drawer.d.ts

@@ -0,0 +1,48 @@
+import { type DebugDrawerPrimitive, type NavMesh, type NavMeshQuery, type RecastCompactHeightfield, type RecastContourSet, type RecastHeightfield, type RecastHeightfieldLayer, type RecastHeightfieldLayerSet, type RecastPolyMesh, type RecastPolyMeshDetail } from '@recast-navigation/core';
+import * as THREE from 'three';
+import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
+export type DebugDrawerParams = {
+    triMaterial?: THREE.Material;
+    pointMaterial?: THREE.Material;
+    lineMaterial?: LineMaterial;
+};
+export declare class DebugDrawer extends THREE.Group {
+    triMaterial: THREE.Material;
+    pointMaterial: THREE.Material;
+    pointGeometry: THREE.SphereGeometry;
+    lineMaterial: LineMaterial;
+    private debugDrawerUtils;
+    constructor({ triMaterial, pointMaterial, lineMaterial, }?: DebugDrawerParams);
+    drawPrimitives(primitives: DebugDrawerPrimitive[]): void;
+    drawHeightfieldSolid(hf: RecastHeightfield): void;
+    drawHeightfieldWalkable(hf: RecastHeightfield): void;
+    drawCompactHeightfieldSolid(chf: RecastCompactHeightfield): void;
+    drawCompactHeightfieldRegions(chf: RecastCompactHeightfield): void;
+    drawCompactHeightfieldDistance(chf: RecastCompactHeightfield): void;
+    drawHeightfieldLayer(layer: RecastHeightfieldLayer, idx: number): void;
+    drawHeightfieldLayers(lset: RecastHeightfieldLayerSet): void;
+    drawRegionConnections(cset: RecastContourSet, alpha?: number): void;
+    drawRawContours(cset: RecastContourSet, alpha?: number): void;
+    drawContours(cset: RecastContourSet, alpha?: number): void;
+    drawPolyMesh(mesh: RecastPolyMesh): void;
+    drawPolyMeshDetail(dmesh: RecastPolyMeshDetail): void;
+    drawNavMesh(mesh: NavMesh, flags?: number): void;
+    drawNavMeshWithClosedList(mesh: NavMesh, query: NavMeshQuery, flags?: number): void;
+    drawNavMeshNodes(query: NavMeshQuery): void;
+    drawNavMeshBVTree(mesh: NavMesh): void;
+    drawNavMeshPortals(mesh: NavMesh): void;
+    /**
+     * @param col color in 0xRRGGBBAA format
+     */
+    drawNavMeshPolysWithFlags(mesh: NavMesh, flags: number, col: number): void;
+    /**
+     * @param col color in 0xRRGGBBAA format
+     */
+    drawNavMeshPoly(mesh: NavMesh, ref: number, col: number): void;
+    reset(): void;
+    dispose(): void;
+    private drawPoints;
+    private drawLines;
+    private drawTris;
+    private drawQuads;
+}

package/dist/debug/index.d.ts

@@ -0,0 +1 @@
+export * from './debug-drawer';

package/dist/helpers/crowd-helper.d.ts

@@ -0,0 +1,19 @@
+import type { Crowd } from '@recast-navigation/core';
+import { type Material, Mesh, Object3D } from 'three';
+export type CrowdHelperParams = {
+    agentMaterial?: Material;
+};
+export declare class CrowdHelper extends Object3D {
+    agentMeshes: Map<number, Mesh>;
+    recastCrowd: Crowd;
+    agentMaterial: Material;
+    constructor(crowd: Crowd, params?: CrowdHelperParams);
+    /**
+     * Update the three debug view of the crowd agents.
+     *
+     * This should be called after updating the crowd.
+     */
+    update(): void;
+    private createAgentMesh;
+    private updateAgentGeometry;
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './crowd-helper';
+export * from './nav-mesh-helper';
+export * from './tile-cache-helper';

package/dist/helpers/nav-mesh-helper.d.ts

@@ -0,0 +1,18 @@
+import { type NavMesh } from '@recast-navigation/core';
+import { BufferGeometry, type Material, Mesh, Object3D } from 'three';
+export type NavMeshHelperParams = {
+    navMeshMaterial?: Material;
+};
+export declare class NavMeshHelper extends Object3D {
+    navMesh: NavMesh;
+    mesh: Mesh;
+    navMeshMaterial: Material;
+    navMeshGeometry: BufferGeometry;
+    constructor(navMesh: NavMesh, params?: NavMeshHelperParams);
+    /**
+     * Update the three debug nav mesh.
+     *
+     * This should be called after updating the nav mesh.
+     */
+    update(): void;
+}

package/dist/helpers/tile-cache-helper.d.ts

@@ -0,0 +1,17 @@
+import type { Obstacle, TileCache } from '@recast-navigation/core';
+import { type Material, Mesh, Object3D } from 'three';
+export type TileCacheHelperParams = {
+    obstacleMaterial?: Material;
+};
+export declare class TileCacheHelper extends Object3D {
+    tileCache: TileCache;
+    obstacleMeshes: Map<Obstacle, Mesh>;
+    obstacleMaterial: Material;
+    constructor(tileCache: TileCache, params?: TileCacheHelperParams);
+    /**
+     * Update the obstacle meshes.
+     *
+     * This should be called after adding or removing obstacles.
+     */
+    update(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './debug';
+export * from './helpers';
+export * from './utils';

package/dist/index.mjs

@@ -0,0 +1,430 @@
+import { DebugDrawerUtils, getNavMeshPositionsAndIndices } from '@recast-navigation/core';
+import * as THREE from 'three';
+import { Object3D, MeshBasicMaterial, Vector3, Mesh, CylinderGeometry, BufferGeometry, BufferAttribute, BoxGeometry } from 'three';
+import { LineMaterial } from 'three/addons/lines/LineMaterial.js';
+import { LineSegments2 } from 'three/addons/lines/LineSegments2.js';
+import { LineSegmentsGeometry } from 'three/addons/lines/LineSegmentsGeometry.js';
+import { mergePositionsAndIndices, generateSoloNavMesh, generateTileCache, generateTiledNavMesh } from '@recast-navigation/generators';
+
+const _color = new THREE.Color();
+class DebugDrawer extends THREE.Group {
+  triMaterial;
+  pointMaterial;
+  pointGeometry = new THREE.SphereGeometry(0.02, 32, 32);
+  lineMaterial;
+  debugDrawerUtils;
+  constructor({
+    triMaterial,
+    pointMaterial,
+    lineMaterial
+  } = {}) {
+    super();
+    this.debugDrawerUtils = new DebugDrawerUtils();
+    this.triMaterial = triMaterial ?? new THREE.MeshBasicMaterial({
+      vertexColors: true,
+      transparent: true,
+      opacity: 0.4,
+      depthWrite: false
+    });
+    this.pointMaterial = pointMaterial ?? new THREE.MeshBasicMaterial();
+    this.lineMaterial = lineMaterial ?? new LineMaterial({
+      color: 0xffffff,
+      linewidth: 2,
+      vertexColors: true,
+      polygonOffset: true,
+      polygonOffsetFactor: -4,
+      polygonOffsetUnits: -10
+    });
+  }
+  drawPrimitives(primitives) {
+    for (const primitive of primitives) {
+      switch (primitive.type) {
+        case 'points':
+          this.drawPoints(primitive);
+          break;
+        case 'lines':
+          this.drawLines(primitive);
+          break;
+        case 'tris':
+          this.drawTris(primitive);
+          break;
+        case 'quads':
+          this.drawQuads(primitive);
+          break;
+      }
+    }
+  }
+  drawHeightfieldSolid(hf) {
+    const primitives = this.debugDrawerUtils.drawHeightfieldSolid(hf);
+    this.drawPrimitives(primitives);
+  }
+  drawHeightfieldWalkable(hf) {
+    const primitives = this.debugDrawerUtils.drawHeightfieldWalkable(hf);
+    this.drawPrimitives(primitives);
+  }
+  drawCompactHeightfieldSolid(chf) {
+    const primitives = this.debugDrawerUtils.drawCompactHeightfieldSolid(chf);
+    this.drawPrimitives(primitives);
+  }
+  drawCompactHeightfieldRegions(chf) {
+    const primitives = this.debugDrawerUtils.drawCompactHeightfieldRegions(chf);
+    this.drawPrimitives(primitives);
+  }
+  drawCompactHeightfieldDistance(chf) {
+    const primitives = this.debugDrawerUtils.drawCompactHeightfieldDistance(chf);
+    this.drawPrimitives(primitives);
+  }
+  drawHeightfieldLayer(layer, idx) {
+    const primitives = this.debugDrawerUtils.drawHeightfieldLayer(layer, idx);
+    this.drawPrimitives(primitives);
+  }
+  drawHeightfieldLayers(lset) {
+    const primitives = this.debugDrawerUtils.drawHeightfieldLayers(lset);
+    this.drawPrimitives(primitives);
+  }
+  drawRegionConnections(cset, alpha = 1) {
+    const primitives = this.debugDrawerUtils.drawRegionConnections(cset, alpha);
+    this.drawPrimitives(primitives);
+  }
+  drawRawContours(cset, alpha = 1) {
+    const primitives = this.debugDrawerUtils.drawRawContours(cset, alpha);
+    this.drawPrimitives(primitives);
+  }
+  drawContours(cset, alpha = 1) {
+    const primitives = this.debugDrawerUtils.drawContours(cset, alpha);
+    this.drawPrimitives(primitives);
+  }
+  drawPolyMesh(mesh) {
+    const primitives = this.debugDrawerUtils.drawPolyMesh(mesh);
+    this.drawPrimitives(primitives);
+  }
+  drawPolyMeshDetail(dmesh) {
+    const primitives = this.debugDrawerUtils.drawPolyMeshDetail(dmesh);
+    this.drawPrimitives(primitives);
+  }
+  drawNavMesh(mesh, flags = 0) {
+    const primitives = this.debugDrawerUtils.drawNavMesh(mesh, flags);
+    this.drawPrimitives(primitives);
+  }
+  drawNavMeshWithClosedList(mesh, query, flags = 0) {
+    const primitives = this.debugDrawerUtils.drawNavMeshWithClosedList(mesh, query, flags);
+    this.drawPrimitives(primitives);
+  }
+  drawNavMeshNodes(query) {
+    const primitives = this.debugDrawerUtils.drawNavMeshNodes(query);
+    this.drawPrimitives(primitives);
+  }
+  drawNavMeshBVTree(mesh) {
+    const primitives = this.debugDrawerUtils.drawNavMeshBVTree(mesh);
+    this.drawPrimitives(primitives);
+  }
+  drawNavMeshPortals(mesh) {
+    const primitives = this.debugDrawerUtils.drawNavMeshPortals(mesh);
+    this.drawPrimitives(primitives);
+  }
+  /**
+   * @param col color in 0xRRGGBBAA format
+   */
+  drawNavMeshPolysWithFlags(mesh, flags, col) {
+    const primitives = this.debugDrawerUtils.drawNavMeshPolysWithFlags(mesh, flags, col);
+    this.drawPrimitives(primitives);
+  }
+  /**
+   * @param col color in 0xRRGGBBAA format
+   */
+  drawNavMeshPoly(mesh, ref, col) {
+    const primitives = this.debugDrawerUtils.drawNavMeshPoly(mesh, ref, col);
+    this.drawPrimitives(primitives);
+  }
+  // todo:
+  // - drawTileCacheLayerAreas
+  // - drawTileCacheLayerRegions
+  // - drawTileCacheContours
+  // - drawTileCachePolyMesh
+  reset() {
+    for (const child of this.children) {
+      if (child instanceof THREE.Mesh || child instanceof LineSegments2) {
+        child.geometry.dispose();
+      }
+    }
+    this.clear();
+  }
+  dispose() {
+    this.debugDrawerUtils.dispose();
+    this.reset();
+    this.pointGeometry.dispose();
+    this.triMaterial.dispose();
+    this.pointMaterial.dispose();
+    this.lineMaterial.dispose();
+  }
+  drawPoints(primitive) {
+    const geometry = this.pointGeometry;
+    const instancedMesh = new THREE.InstancedMesh(geometry, this.pointMaterial, primitive.vertices.length / 3);
+    for (let point = 0; point < primitive.vertices.length / 7; point++) {
+      const [x, y, z, r, g, b] = primitive.vertices[point];
+      instancedMesh.setMatrixAt(point, new THREE.Matrix4().setPosition(x, y, z));
+      instancedMesh.setColorAt(point, _color.setRGB(r, g, b));
+    }
+    instancedMesh.instanceMatrix.needsUpdate = true;
+    this.add(instancedMesh);
+  }
+  drawLines(primitive) {
+    const lineSegmentsGeometry = new LineSegmentsGeometry();
+    const positions = [];
+    const colors = [];
+    for (let i = 0; i < primitive.vertices.length; i += 2) {
+      const [x1, y1, z1, r1, g1, b1] = primitive.vertices[i];
+      const [x2, y2, z2, r2, g2, b2] = primitive.vertices[i + 1];
+      positions.push(x1, y1, z1);
+      positions.push(x2, y2, z2);
+      colors.push(r1, g1, b1);
+      colors.push(r2, g2, b2);
+    }
+    lineSegmentsGeometry.setPositions(positions);
+    lineSegmentsGeometry.setColors(colors);
+    const lineSegments = new LineSegments2(lineSegmentsGeometry, this.lineMaterial);
+    this.add(lineSegments);
+  }
+  drawTris(primitive) {
+    const geometry = new THREE.BufferGeometry();
+    const positions = new Float32Array(primitive.vertices.length * 3);
+    const colors = new Float32Array(primitive.vertices.length * 3);
+    for (let i = 0; i < primitive.vertices.length; i++) {
+      const [x, y, z, r, g, b] = primitive.vertices[i];
+      positions[i * 3 + 0] = x;
+      positions[i * 3 + 1] = y;
+      positions[i * 3 + 2] = z;
+      colors[i * 3 + 0] = r;
+      colors[i * 3 + 1] = g;
+      colors[i * 3 + 2] = b;
+    }
+    geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+    geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+    const material = this.triMaterial;
+    const mesh = new THREE.Mesh(geometry, material);
+    this.add(mesh);
+  }
+  drawQuads(primitive) {
+    const positions = [];
+    const colors = [];
+    for (let i = 0; i < primitive.vertices.length; i += 4) {
+      const vertices = [primitive.vertices[i], primitive.vertices[i + 1], primitive.vertices[i + 2], primitive.vertices[i], primitive.vertices[i + 2], primitive.vertices[i + 3]];
+      for (const [x, y, z, r, g, b] of vertices) {
+        positions.push(x, y, z);
+        colors.push(r, g, b);
+      }
+    }
+    const geometry = new THREE.BufferGeometry();
+    geometry.setAttribute('position', new THREE.BufferAttribute(new Float32Array(positions), 3));
+    geometry.setAttribute('color', new THREE.BufferAttribute(new Float32Array(colors), 3));
+    const material = this.triMaterial;
+    const mesh = new THREE.Mesh(geometry, material);
+    this.add(mesh);
+  }
+}
+
+class CrowdHelper extends Object3D {
+  agentMeshes = new Map();
+  recastCrowd;
+  agentMaterial;
+  constructor(crowd, params) {
+    super();
+    this.recastCrowd = crowd;
+    this.agentMaterial = params?.agentMaterial ?? new MeshBasicMaterial({
+      color: 'red'
+    });
+    this.update();
+  }
+  /**
+   * Update the three debug view of the crowd agents.
+   *
+   * This should be called after updating the crowd.
+   */
+  update() {
+    const agents = this.recastCrowd.getAgents();
+    const unseen = new Set(this.agentMeshes.keys());
+    for (const agent of agents) {
+      unseen.delete(agent.agentIndex);
+      const position = agent.position();
+      const velocity = agent.velocity();
+      let agentMesh = this.agentMeshes.get(agent.agentIndex);
+      if (agentMesh === undefined) {
+        agentMesh = this.createAgentMesh(agent);
+        this.add(agentMesh);
+        this.agentMeshes.set(agent.agentIndex, agentMesh);
+      } else {
+        this.updateAgentGeometry(agentMesh, agent);
+      }
+      agentMesh.position.set(position.x, position.y + agent.height / 2, position.z);
+      agentMesh.lookAt(new Vector3().copy(agentMesh.position).add(velocity));
+    }
+    for (const agentId of unseen) {
+      const agentMesh = this.agentMeshes.get(agentId);
+      if (agentMesh) {
+        this.remove(agentMesh);
+        this.agentMeshes.delete(agentId);
+      }
+    }
+  }
+  createAgentMesh(agent) {
+    const mesh = new Mesh();
+    mesh.material = this.agentMaterial;
+    this.updateAgentGeometry(mesh, agent);
+    mesh.userData = {
+      radius: agent.radius,
+      height: agent.height
+    };
+    return mesh;
+  }
+  updateAgentGeometry(agentMesh, agentParams) {
+    if (agentMesh.userData.radius !== agentParams.radius || agentMesh.userData.height !== agentParams.height) {
+      const geometry = new CylinderGeometry(agentParams.radius, agentParams.radius, agentParams.height);
+      agentMesh.geometry.dispose();
+      agentMesh.geometry = geometry;
+      agentMesh.userData.radius = agentParams.radius;
+      agentMesh.userData.height = agentParams.height;
+    }
+  }
+}
+
+class NavMeshHelper extends Object3D {
+  navMesh;
+  mesh;
+  navMeshMaterial;
+  navMeshGeometry;
+  constructor(navMesh, params) {
+    super();
+    this.navMesh = navMesh;
+    this.navMeshGeometry = new BufferGeometry();
+    this.navMeshMaterial = params?.navMeshMaterial ? params.navMeshMaterial : new MeshBasicMaterial({
+      color: 'orange',
+      transparent: true,
+      opacity: 0.7,
+      depthWrite: false
+    });
+    this.update();
+    this.mesh = new Mesh(this.navMeshGeometry, this.navMeshMaterial);
+    this.add(this.mesh);
+  }
+  /**
+   * Update the three debug nav mesh.
+   *
+   * This should be called after updating the nav mesh.
+   */
+  update() {
+    const [positions, indices] = getNavMeshPositionsAndIndices(this.navMesh);
+    this.navMeshGeometry.setAttribute('position', new BufferAttribute(Float32Array.from(positions), 3));
+    this.navMeshGeometry.setIndex(new BufferAttribute(Uint32Array.from(indices), 1));
+    this.navMeshGeometry.computeVertexNormals();
+  }
+}
+
+class TileCacheHelper extends Object3D {
+  tileCache;
+  obstacleMeshes = new Map();
+  obstacleMaterial;
+  constructor(tileCache, params) {
+    super();
+    this.tileCache = tileCache;
+    this.obstacleMaterial = params?.obstacleMaterial ? params.obstacleMaterial : new MeshBasicMaterial({
+      color: 'red',
+      wireframe: true,
+      wireframeLinewidth: 2
+    });
+    this.update();
+  }
+  /**
+   * Update the obstacle meshes.
+   *
+   * This should be called after adding or removing obstacles.
+   */
+  update() {
+    const unseen = new Set(this.obstacleMeshes.keys());
+    for (const [, obstacle] of this.tileCache.obstacles) {
+      const obstacleMesh = this.obstacleMeshes.get(obstacle);
+      unseen.delete(obstacle);
+      if (!obstacleMesh) {
+        const {
+          position
+        } = obstacle;
+        const mesh = new Mesh(undefined, this.obstacleMaterial);
+        mesh.position.copy(position);
+        if (obstacle.type === 'box') {
+          const {
+            halfExtents,
+            angle
+          } = obstacle;
+          mesh.geometry = new BoxGeometry(halfExtents.x * 2, halfExtents.y * 2, halfExtents.z * 2);
+          mesh.rotation.y = angle;
+        } else if (obstacle.type === 'cylinder') {
+          const {
+            radius,
+            height
+          } = obstacle;
+          mesh.geometry = new CylinderGeometry(radius, radius, height, 16);
+          mesh.position.y += height / 2;
+        } else {
+          throw new Error(`Unknown obstacle type: ${obstacle}`);
+        }
+        this.add(mesh);
+        this.obstacleMeshes.set(obstacle, mesh);
+      }
+    }
+    for (const obstacle of unseen) {
+      const obstacleMesh = this.obstacleMeshes.get(obstacle);
+      if (obstacleMesh) {
+        this.remove(obstacleMesh);
+        this.obstacleMeshes.delete(obstacle);
+      }
+    }
+  }
+}
+
+const _position = new Vector3();
+const getPositionsAndIndices = meshes => {
+  const toMerge = [];
+  for (const mesh of meshes) {
+    const positionAttribute = mesh.geometry.attributes.position;
+    if (!positionAttribute || positionAttribute.itemSize !== 3) {
+      continue;
+    }
+    mesh.updateMatrixWorld();
+    const positions = new Float32Array(positionAttribute.array);
+    for (let i = 0; i < positions.length; i += 3) {
+      const pos = _position.set(positions[i], positions[i + 1], positions[i + 2]);
+      mesh.localToWorld(pos);
+      positions[i] = pos.x;
+      positions[i + 1] = pos.y;
+      positions[i + 2] = pos.z;
+    }
+    let indices = mesh.geometry.getIndex()?.array;
+    if (indices === undefined) {
+      // this will become indexed when merging with other meshes
+      const ascendingIndex = [];
+      for (let i = 0; i < positionAttribute.count; i++) {
+        ascendingIndex.push(i);
+      }
+      indices = ascendingIndex;
+    }
+    toMerge.push({
+      positions,
+      indices
+    });
+  }
+  return mergePositionsAndIndices(toMerge);
+};
+
+const threeToSoloNavMesh = (meshes, navMeshGeneratorConfig = {}, keepIntermediates = false) => {
+  const [positions, indices] = getPositionsAndIndices(meshes);
+  return generateSoloNavMesh(positions, indices, navMeshGeneratorConfig, keepIntermediates);
+};
+const threeToTiledNavMesh = (meshes, navMeshGeneratorConfig = {}, keepIntermediates = false) => {
+  const [positions, indices] = getPositionsAndIndices(meshes);
+  return generateTiledNavMesh(positions, indices, navMeshGeneratorConfig, keepIntermediates);
+};
+const threeToTileCache = (meshes, navMeshGeneratorConfig = {}, keepIntermediates = false) => {
+  const [positions, indices] = getPositionsAndIndices(meshes);
+  return generateTileCache(positions, indices, navMeshGeneratorConfig, keepIntermediates);
+};
+
+export { CrowdHelper, DebugDrawer, NavMeshHelper, TileCacheHelper, getPositionsAndIndices, threeToSoloNavMesh, threeToTileCache, threeToTiledNavMesh };

package/dist/utils/generators.d.ts

@@ -0,0 +1,5 @@
+import { type SoloNavMeshGeneratorConfig, type TileCacheGeneratorConfig, type TiledNavMeshGeneratorConfig } from '@recast-navigation/generators';
+import type { Mesh } from 'three';
+export declare const threeToSoloNavMesh: (meshes: Mesh[], navMeshGeneratorConfig?: Partial<SoloNavMeshGeneratorConfig>, keepIntermediates?: boolean) => import("@recast-navigation/generators").GenerateSoloNavMeshResult;
+export declare const threeToTiledNavMesh: (meshes: Mesh[], navMeshGeneratorConfig?: Partial<TiledNavMeshGeneratorConfig>, keepIntermediates?: boolean) => import("@recast-navigation/generators").GenerateTiledNavMeshResult;
+export declare const threeToTileCache: (meshes: Mesh[], navMeshGeneratorConfig?: Partial<TileCacheGeneratorConfig>, keepIntermediates?: boolean) => import("@recast-navigation/generators").TileCacheGeneratorResult;

package/dist/utils/get-positions-and-indices.d.ts

@@ -0,0 +1,2 @@
+import { type Mesh } from 'three';
+export declare const getPositionsAndIndices: (meshes: Mesh[]) => [positions: Float32Array, indices: Uint32Array];

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './generators';
+export * from './get-positions-and-indices';

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@recast-navigation/three",
+  "description": "Utilities for using recast-navigation with Three.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isaac-mason/recast-navigation-js.git",
+    "directory": "packages/recast-navigation-three"
+  },
+  "author": {
+    "name": "Isaac Mason",
+    "email": "isaac@isaacmason.com",
+    "url": "https://isaacmason.com/"
+  },
+  "version": "0.0.0-canary-20261030-064e4acc",
+  "license": "MIT",
+  "homepage": "https://github.com/isaac-mason/recast-navigation-js",
+  "bugs": {
+    "url": "https://github.com/isaac-mason/recast-navigation-js/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@recast-navigation/core": "0.0.0-canary-20261030-064e4acc",
+    "@recast-navigation/generators": "0.0.0-canary-20261030-064e4acc"
+  },
+  "peerDependencies": {
+    "@types/three": "0.x.x",
+    "three": "0.x.x"
+  },
+  "devDependencies": {
+    "@babel/core": "^8.0.10",
+    "@babel/preset-env": "^8.0.7",
+    "@babel/preset-typescript": "^8.0.7",
+    "@rollup/plugin-babel": "^7.1.0",
+    "@rollup/plugin-commonjs": "^29.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^12.3.1",
+    "@types/three": "^0.186.0",
+    "rollup": "^4.66.0",
+    "rollup-plugin-copy": "^3.5.0",
+    "rollup-plugin-filesize": "^10.0.0",
+    "three": "^0.186.1",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "rollup --config rollup.config.js --bundleConfigAsCjs",
+    "test": "tsc"
+  }
+}