recast-navigation 0.18.1 → 0.19.0

package/README.md

@@ -7,7 +7,7 @@
 
 # recast-navigation-js
 
-### [Try the NavMesh Generator Website!](https://navmesh.isaacmason.com/)
+### [Examples](https://recast-navigation-js.isaacmason.com) | [NavMesh Generator Website](https://navmesh.isaacmason.com/)
 
 - 📐 ‎ NavMesh generation
 - 🧭 ‎ Pathfinding
@@ -256,29 +256,52 @@ const { success, navMesh, tileCache } = generateTileCache(positions, indices, {
   /* ... */
   tileSize: 16,
 });
+```
+
+You can use `addCylinderObstacle`, `addBoxObstacle`, and `removeObstacle` to add and remove obstacles from the TileCache. 
+
+After adding or removing obstacles you can call `tileCache.update(navMesh)` to rebuild navmesh tiles.
+
+Adding or removing an obstacle will internally create an "obstacle request". TileCache supports queuing up to 64 obstacle requests. If the requests queue is full, calls to `addCylinderObstacle` and `addBoxObstacle` will fail and return a `dtStatus` status code `DT_BUFFER_TOO_SMALL`.
+
+The `tileCache.update` method returns `upToDate`, whether the tile cache is fully up to date with obstacle requests and tile rebuilds. If the tile cache isn't up to date another call will continue processing obstacle requests and tile rebuilds; otherwise it will have no effect.
+
+If not many obstacle requests occur between updates, an easy pattern is to call `tileCache.update` periodically, such as every game update.
+
+If many obstacle requests have been made and you need to avoid reaching the 64 obstacle request limit, you can call `tileCache.update` multiple times, bailing out when `upToDate` is true or after a maximum number of updates.
 
+```ts
 /* add a Box obstacle to the NavMesh */
 const position = { x: 0, y: 0, z: 0 };
 const extent = { x: 1, y: 1, z: 1 };
 const angle = 0;
-const boxObstacle = tileCache.addBoxObstacle(position, extent, angle);
+const addBoxObstacleResult = tileCache.addBoxObstacle(position, extent, angle);
+const boxObstacle = addBoxObstacleResult.obstacle;
 
 /* add a Cylinder obstacle to the NavMesh */
 const radius = 1;
 const height = 1;
-const cylinderObstacle = tileCache.addCylinderObstacle(
+const addCylinderObstacleResult = tileCache.addCylinderObstacle(
   position,
   radius,
   height,
   angle
 );
+const cylinderObstacle = addCylinderObstacleResult.obstacle;
+
+/* remove the obstacles from the NavMesh */
+const removeObstacleResult = tileCache.removeObstacle(boxObstacle);
 
-/* update the NavMesh to reflect obstacle changes */
+/* update to reflect obstacle changes */
+// if few obstacles are added/removed between updates, you could call tileCache.update every game update
 tileCache.update(navMesh);
 
-/* remove the obstacles from the NavMesh */
-tileCache.removeObstacle(boxObstacle);
-tileCache.removeObstacle(cylinderObstacle);
+// if your obstacle requests affect many tiles, you may need to call update multiple times
+const maxTileCacheUpdates = 5
+for (let i = 0; i < maxTileCacheUpdates; i++) {
+  const { upToDate } = tileCache.update(navMesh);
+  if (upToDate) break;
+}
 ```
 
 ### Off Mesh Connections
@@ -347,6 +370,8 @@ const { success, navMesh, tileCache } = generateTileCache(
 
 ### Debugging
 
+#### Debug Nav Mesh
+
 You can use `getDebugNavMesh` to get a debug representation of the NavMesh.
 
 ```ts
@@ -359,6 +384,45 @@ If you are using three.js, you can use `NavMeshHelper` and `CrowdHelper` to visu
 
 See the [`@recast-navigation/three` package README](https://github.com/isaac-mason/recast-navigation-js/tree/main/packages/recast-navigation-three/README.md) for usage information.
 
+#### Detour Status Codes
+
+Many Detour APIs return a `status` property. This is a `dtStatus` enum, which is a number representing the status of the operation.
+
+You can use the `dtStatusToReadableString` function to convert a `dtStatus` to a human-readable string.
+
+```ts
+import { dtStatusToReadableString } from 'recast-navigation';
+
+console.log(dtStatusToReadableString(status));
+```
+
+If you need to work with status codes programmatically, you can use these utilities:
+
+```ts
+import { Raw } from 'recast-navigation';
+
+// returns true if the status is a success
+Raw.Detour.statusSucceed(status);
+
+// returns true if the status is in progress
+Raw.Detour.statusInProgress(status);
+
+// returns true if the status is a failure
+Raw.Detour.statusFailed(status);
+
+// get the detail of the status
+const detail = Raw.Detour.statusDetail(status);
+
+// Raw.Detour.WRONG_MAGIC;
+// Raw.Detour.WRONG_VERSION;
+// Raw.Detour.OUT_OF_MEMORY;
+// Raw.Detour.INVALID_PARAM;
+// Raw.Detour.BUFFER_TOO_SMALL;
+// Raw.Detour.OUT_OF_NODES;
+// Raw.Detour.PARTIAL_RESULT;
+// Raw.Detour.ALREADY_OCCUPIED;
+```
+
 ### Importing and Exporting
 
 A NavMesh and TileCache can be imported and exported as a Uint8Array.

package/package.json

@@ -18,7 +18,7 @@
     "email": "isaac@isaacmason.com",
     "url": "https://isaacmason.com/"
   },
-  "version": "0.18.1",
+  "version": "0.19.0",
   "license": "MIT",
   "homepage": "https://github.com/isaac-mason/recast-navigation-js",
   "bugs": {
@@ -66,9 +66,9 @@
     "lint": "eslint --ext .ts src"
   },
   "dependencies": {
-    "@recast-navigation/core": "0.18.1",
-    "@recast-navigation/generators": "0.18.1",
-    "@recast-navigation/three": "0.18.1"
+    "@recast-navigation/core": "0.19.0",
+    "@recast-navigation/generators": "0.19.0",
+    "@recast-navigation/three": "0.19.0"
   },
   "devDependencies": {
     "@babel/core": "^7.23.9",
@@ -88,14 +88,14 @@
     "@storybook/addon-mdx-gfm": "^8.0.1",
     "@storybook/react": "^8.0.1",
     "@storybook/react-vite": "^8.0.1",
-    "@types/react": "^18.2.69",
+    "@types/react": "^18.2.73",
     "@types/react-dom": "^18.2.8",
     "@types/three": "^0.160.0",
     "eslint": "^8.56.0",
     "leva": "^0.9.35",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "rollup": "^4.9.2",
+    "rollup": "^4.14.0",
     "rollup-plugin-copy": "^3.4.0",
     "rollup-plugin-filesize": "^10.0.0",
     "storybook": "^8.0.1",
@@ -103,7 +103,7 @@
     "three": "^0.160.0",
     "three-pathfinding": "^1.2.0",
     "typescript": "^5.4.3",
-    "vitest": "^1.2.0"
+    "vitest": "^1.4.0"
   },
   "packageManager": "yarn@3.2.2"
 }