recast-navigation 0.18.2 → 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
@@ -262,9 +262,9 @@ You can use `addCylinderObstacle`, `addBoxObstacle`, and `removeObstacle` to add
 
 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.
+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. Each update call processes up to 64 tiles touched by added or removed obstacles. 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.
+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.
 
@@ -275,20 +275,22 @@ If many obstacle requests have been made and you need to avoid reaching the 64 o
 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 */
-tileCache.removeObstacle(boxObstacle);
+const removeObstacleResult = tileCache.removeObstacle(boxObstacle);
 
 /* update to reflect obstacle changes */
 // if few obstacles are added/removed between updates, you could call tileCache.update every game update
@@ -368,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
@@ -380,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.2",
+  "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.2",
-    "@recast-navigation/generators": "0.18.2",
-    "@recast-navigation/three": "0.18.2"
+    "@recast-navigation/core": "0.19.0",
+    "@recast-navigation/generators": "0.19.0",
+    "@recast-navigation/three": "0.19.0"
   },
   "devDependencies": {
     "@babel/core": "^7.23.9",
@@ -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"
 }