@recast-navigation/core 0.18.1 → 0.19.0

package/dist/tile-cache.d.ts

@@ -17,6 +17,19 @@ export type CylinderObstacle = {
     radius: number;
     height: number;
 };
+export type AddObstacleResult<T> = {
+    success: true;
+    status: number;
+    obstacle: T;
+} | {
+    success: false;
+    status: number;
+    obstacle?: T;
+};
+export type RemoveObstacleResult = {
+    success: boolean;
+    status: number;
+};
 export type Obstacle = BoxObstacle | CylinderObstacle;
 export type TileCacheParamsType = {
     orig: ReadonlyArray<number>;
@@ -37,6 +50,7 @@ export declare class DetourTileCacheParams {
     static create(config: TileCacheParamsType): DetourTileCacheParams;
 }
 export type TileCacheUpdateResult = {
+    success: boolean;
     status: number;
     upToDate: boolean;
 };
@@ -51,21 +65,37 @@ export declare class TileCache {
     init(params: DetourTileCacheParams, alloc: R.RecastLinearAllocator, compressor: R.RecastFastLZCompressor, meshProcess: TileCacheMeshProcess): boolean;
     /**
      * Updates the tile cache by rebuilding tiles touched by unfinished obstacle requests.
-     * This should be called after adding or removing obstacles.
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const { success, status, upToDate } = tileCache.update(navMesh);
+     * ```
      */
     update(navMesh: NavMesh): TileCacheUpdateResult;
     /**
      * Creates a cylinder obstacle and adds it to the navigation mesh.
      */
-    addCylinderObstacle(position: Vector3, radius: number, height: number): CylinderObstacle;
+    addCylinderObstacle(position: Vector3, radius: number, height: number): AddObstacleResult<CylinderObstacle>;
     /**
      * Creates a box obstacle and adds it to the navigation mesh.
      */
-    addBoxObstacle(position: Vector3, extent: Vector3, angle: number): BoxObstacle;
+    addBoxObstacle(position: Vector3, extent: Vector3, angle: number): AddObstacleResult<BoxObstacle>;
     /**
      * Removes an obstacle from the navigation mesh.
      */
-    removeObstacle(obstacle: Obstacle | ObstacleRef): void;
+    removeObstacle(obstacle: Obstacle | ObstacleRef): RemoveObstacleResult;
     addTile(data: R.UnsignedCharArray, flags?: number): R.TileCacheAddTileResult;
     buildNavMeshTile(ref: R.dtCompressedTileRef, navMesh: NavMesh): number;
     buildNavMeshTilesAt(tx: number, ty: number, navMesh: NavMesh): number;

package/package.json

@@ -6,7 +6,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": {
@@ -26,7 +26,7 @@
     "lint": "eslint --ext .ts src"
   },
   "dependencies": {
-    "@recast-navigation/wasm": "0.18.1"
+    "@recast-navigation/wasm": "0.19.0"
   },
   "devDependencies": {
     "@babel/core": "^7.23.9",
@@ -39,7 +39,7 @@
     "babel-loader": "^9.1.3",
     "eslint": "^8.56.0",
     "prettier": "^3.1.0",
-    "rollup": "^4.9.2",
+    "rollup": "^4.14.0",
     "rollup-plugin-copy": "^3.4.0",
     "rollup-plugin-filesize": "^10.0.0",
     "typescript": "^5.4.3"