recast-navigation 0.39.0 → 0.41.0

package/README.md

@@ -22,6 +22,34 @@
 
 This library provides high level APIs that make it easy to get started creating navigation meshes, querying them, and simulating crowds. It also provides lower-level APIs that give you fine-grained control over the navmesh generation process.
 
+### Usage
+
+There are a few common ways you can make use of recast-navigation-js, depending on your needs:
+
+#### 1. **Runtime NavMesh Generation, NavMesh querying with Detour APIs**
+
+You can use this library to generate a navigation mesh at runtime for procedurally generated or frequently changing environments, and use Detour APIs for pathfinding and spatial reasoning on the navigation mesh.
+
+#### 2. **Offline NavMesh Generation (Recast Format), NavMesh querying with Detour APIs**
+
+If your environment is largely static, you can generate a navigation mesh offline and import it at runtime. This is useful for larger environments where runtime generation would be too slow, or if you want to avoid the overhead of runtime generation.
+
+The TileCache Detour API provides support for temporary obstacles, which can be used to create semi-dynamic environments.
+
+#### 3. **Offline NavMesh Generation (GLTF or Custom Format), external NavMesh querying solution**
+
+You can opt to only use the navigation mesh generation capabilities of this library, and export the generated navigation mesh in a GLTF or custom format. You can then use an external pathfinding solution (for example, [three-pathfinding](https://github.com/donmccurdy/three-pathfinding)) for querying the generated navigation mesh. ([See recast-navigation-js & three-pathfinding example](https://github.com/isaac-mason/recast-navigation-js/blob/main/packages/recast-navigation/.storybook/stories/external-use/three-pathfinding.stories.tsx))
+
+This is worth considering if:
+  - you need more flexibility than the detour WASM API affords
+  - you do have a dynamic environment
+  - you don't require more complex functionality in detour such as temporary obstacles and crowd simulation
+  - minimising your bundle size is important, and the WASM library file size doesn't fit within your budget
+
+For simpler projects your navigation mesh generation needs may be entirely served by the [NavMesh Generator](https://navmesh.isaacmason.com/) website, which allows you to generate a navigation mesh from an uploaded model and export it in a GLTF format.
+
+If you want to integrate navigation mesh generation into your project's asset pipeline, see this demonstration of how to create a custom config file for the glTF Transform CLI, and implement navmesh generation as a custom command: https://github.com/donmccurdy/glTF-Transform-Recast-Config
+
 ## Examples
 
 Go to the [examples website](https://recast-navigation-js.isaacmason.com) to see the project in action:
@@ -49,17 +77,19 @@ export default defineConfig(() => ({
 )}
 ```
 
-If you are planning to use the library with three.js, install the `@recast-navigation/three` package for three.js helpers:
+You can also install individual packages from the `@recast-navigation` npm organization:
+- [`@recast-navigation/core`](https://www.npmjs.com/package/@recast-navigation/core) - The core library that provides the main functionality.
+- [`@recast-navigation/generators`](https://www.npmjs.com/package/@recast-navigation/generators) - High level NavMesh generator functions.
+- [`@recast-navigation/wasm`](https://www.npmjs.com/package/@recast-navigation/wasm) - The WebAssembly build of the Recast and Detour libraries, used internally by `@recast-navigation/core`.
 
-```sh
-npm install @recast-navigation/three
-```
+The `@recast-navigation` npm organization contains some packages that simplify integration with other libraries and frameworks:
 
-If you are planning to use the library with playcanvas, install the `@recast-navigation/playcanvas` package for playcanvas helpers:
+- [`@recast-navigation/three`](https://www.npmjs.com/package/@recast-navigation/three) - Helpers for integrating with three.js.
+- [`@recast-navigation/playcanvas`](https://www.npmjs.com/package/@recast-navigation/playcanvas) - Helpers for integrating with playcanvas.
 
-```sh
-npm install @recast-navigation/playcanvas
-```
+There are also some community maintained packages that provide integrations with other libraries:
+
+- [`babylonjs-recast-navigation-js`](https://github.com/RolandCsibrei/babylonjs-recast-navigation-js) - A drop-in implementation for the Babylon.js navigation interface implemented with recast-navigation-js.
 
 **Usage without bundlers**
 
@@ -101,20 +131,17 @@ API Documentation can be found at [https://docs.recast-navigation-js.isaacmason.
 
 For information on changes between versions, see [CHANGELOG.md](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation/CHANGELOG.md)
 
-To get the most out of this library, you should have some familiarity with the Recast and Detour libraries. These are some good resources to get started:
-
+These are useful resources for understanding the recast navmesh generation process, which will help you understand how to use this library effectively:
 - https://recastnav.com/md_Docs__1_Introducation.html
 - https://www.unrealdoc.com/p/navigation-mesh
 
-Documentation for the Recast and Detour c++ libraries can be found here:
+Documentation and resources for the Recast and Detour c++ libraries can be found here:
 
 - [Recast Navigation Website](http://recastnav.com/)
 - [Recast Navigation GitHub](https://github.com/recastnavigation/recastnavigation)
 - [Recast Navigation Google Discussions](https://groups.google.com/g/recastnavigation)
 
-The GitHub issues and Google Discussions are great resources for learning about the library and getting guidance on common issues.
-
-## Usage
+## Getting Started
 
 ### Initialization
 
@@ -171,7 +198,7 @@ See the docs for more information on generator options: https://docs.recast-navi
 
 It's possible to build a NavMesh in a Web Worker. This can be useful for offloading heavy computation from the main thread.
 
-The library doesn't include a web worker, but it's straightforward to create your own. An example of solo nav mesh generation in a web worker can be found here: https://github.com/isaac-mason/recast-navigation-js/tree/next/examples/three-vite-worker-example
+The library doesn't include a web worker, but it's straightforward to create your own. An example of solo nav mesh generation in a web worker can be found here: https://github.com/isaac-mason/recast-navigation-js/tree/main/examples/three-vite-worker-example
 
 The example uses `importNavMesh` and `exportNavMesh` to serialize and deserialize a NavMesh for transfer between the main thread and the web worker.
 
@@ -596,91 +623,12 @@ const { navMesh, tileCache, allocator, compressor } = importTileCache(
 );
 ```
 
-## Packages
-
-Functionality is spread across packages in the `@recast-navigation/*` organization.
-
-The `recast-navigation` package is the umbrella package for core packages, and has entrypoints for `@recast-navigation/core` and `@recast-navigation/generators`.
-
-All packages ship as ECMAScript modules, and are compatible with Node.js and browser environments.
-
-### [**`recast-navigation`**](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation)
-
-[![Version](https://img.shields.io/npm/v/recast-navigation)](https://www.npmjs.com/package/recast-navigation)
-
-The umbrella package for `recast-navigation`.
-
-```bash
-> npm install recast-navigation
-```
-
-```ts
-import { init } from 'recast-navigation';
-import { generateSoloNavMesh } from 'recast-navigation/generators';
-```
-
-### [**`@recast-navigation/core`**](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation-core)
-
-[![Version](https://img.shields.io/npm/v/@recast-navigation/core)](https://www.npmjs.com/package/@recast-navigation/core)
-
-The core library!
-
-```bash
-> npm install @recast-navigation/core
-```
-
-### [**`@recast-navigation/generators`**](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation-generators)
-
-[![Version](https://img.shields.io/npm/v/@recast-navigation/generators)](https://www.npmjs.com/package/@recast-navigation/generators)
-
-NavMesh generator implementations. Use these to get started, and as a basis for your own NavMesh generator.
-
-```bash
-> npm install @recast-navigation/generators
-```
-
-### [**`@recast-navigation/three`**](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation-three)
-
-[![Version](https://img.shields.io/npm/v/@recast-navigation/three)](https://www.npmjs.com/package/@recast-navigation/three)
-
-Helpers for three.js.
-
-```bash
-> npm install @recast-navigation/three
-```
-
-### [**`@recast-navigation/playcanvas`**](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation-playcanvas)
-
-[![Version](https://img.shields.io/npm/v/@recast-navigation/playcanvas)](https://www.npmjs.com/package/@recast-navigation/playcanvas)
-
-Helpers for playcanvas.
-
-```bash
-> npm install @recast-navigation/playcanvas
-```
-
-### [**`@recast-navigation/wasm`**](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation-wasm)
-
-[![Version](https://img.shields.io/npm/v/@recast-navigation/wasm)](https://www.npmjs.com/package/@recast-navigation/wasm)
-
-The WebAssembly build of the Recast and Detour libraries.
-
-You regularly won't need to use this package directly, `@recast-navigation/core` uses it internally.
-
-```bash
-> npm install @recast-navigation/wasm
-```
-
-## Apps
-
-### [NavMesh Generator](https://navmesh.isaacmason.com/)
-
-A website for generating navmeshes for your game. Drag 'n' drop your GLTF, fine tune your settings, and download your navmesh!
-
-([source](./apps/navmesh-website/))
-
 ## Acknowledgements
 
 - This would not exist without [Recast Navigation](https://github.com/recastnavigation/recastnavigation) itself!
 - The demos use recastnavigation's level mesh
 - The WASM build was based on the [Babylon.js Recast Extension](https://github.com/BabylonJS/Extensions/tree/master/recastjs)
+
+## LICENSE
+
+This project is licensed under the MIT License. See: [LICENSE](./LICENSE).

package/package.json

@@ -18,7 +18,7 @@
     "email": "isaac@isaacmason.com",
     "url": "https://isaacmason.com/"
   },
-  "version": "0.39.0",
+  "version": "0.41.0",
   "license": "MIT",
   "homepage": "https://github.com/isaac-mason/recast-navigation-js",
   "bugs": {
@@ -55,52 +55,45 @@
     "build": "yarn clean && rollup --config rollup.config.js --bundleConfigAsCjs",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
-    "test": "tsc && vitest run",
-    "lint": "eslint src"
+    "test": "tsc && vitest run"
   },
   "dependencies": {
-    "@recast-navigation/core": "0.39.0",
-    "@recast-navigation/generators": "0.39.0"
+    "@recast-navigation/core": "0.41.0",
+    "@recast-navigation/generators": "0.41.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.24.5",
-    "@babel/preset-env": "^7.24.5",
-    "@babel/preset-typescript": "^7.24.1",
-    "@isaac-mason/eslint-config-typescript": "^0.0.9",
-    "@mdx-js/react": "^2.3.0",
+    "@babel/core": "^7.28.0",
+    "@babel/preset-env": "^7.28.0",
+    "@babel/preset-typescript": "^7.27.1",
+    "@mdx-js/react": "^3.1.0",
     "@pmndrs/assets": "^1.6.0",
-    "@react-three/drei": "^9.105.4",
-    "@react-three/fiber": "^8.16.3",
+    "@react-three/drei": "^10.4.2",
+    "@react-three/fiber": "^9.2.0",
     "@rollup/plugin-babel": "^6.0.4",
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.0.1",
-    "@rollup/plugin-typescript": "^11.1.6",
-    "@storybook/addon-actions": "^8.0.9",
-    "@storybook/addon-essentials": "^8.0.9",
-    "@storybook/addon-interactions": "^8.0.9",
-    "@storybook/addon-links": "^8.0.9",
-    "@storybook/addon-mdx-gfm": "^8.0.9",
-    "@storybook/react": "^8.0.9",
-    "@storybook/react-vite": "^8.0.9",
-    "@types/react": "^18.3.1",
-    "@types/react-dom": "^18.2.8",
-    "@types/three": "^0.172.0",
-    "@vitejs/plugin-react": "^4.2.1",
-    "eslint": "^9.6.0",
-    "leva": "^0.9.35",
-    "react": "^18.3.1",
-    "react-dom": "^18.2.0",
-    "rollup": "^4.14.0",
-    "rollup-plugin-copy": "^3.4.0",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.4",
+    "@storybook/addon-docs": "^9.0.15",
+    "@storybook/addon-links": "^9.0.15",
+    "@storybook/react-vite": "^9.0.15",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@types/three": "^0.178.0",
+    "@vitejs/plugin-react": "^4.6.0",
+    "leva": "^0.10.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "rollup": "^4.44.2",
+    "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-filesize": "^10.0.0",
-    "storybook": "^8.0.9",
+    "storybook": "^9.0.15",
     "suspend-react": "^0.1.3",
-    "three": "^0.172.0",
-    "three-pathfinding": "^1.2.0",
-    "typescript": "^5.4.3",
-    "vite": "^5.4.8",
-    "vitest": "^2.1.2",
-    "zustand": "^4.5.2"
+    "three": "^0.178.0",
+    "three-pathfinding": "^1.3.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.0.2",
+    "vitest": "^3.2.4",
+    "zustand": "^5.0.6"
   },
   "packageManager": "yarn@3.2.2"
 }