@recast-navigation/core 0.22.0 → 0.24.0

package/dist/nav-mesh-query.d.ts

@@ -20,7 +20,13 @@ export type NavMeshQueryParams = {
 };
 export declare class NavMeshQuery {
     raw: R.NavMeshQuery;
+    /**
+     * Default query filter.
+     */
     defaultFilter: QueryFilter;
+    /**
+     * Default search distance along each axis.
+     */
     defaultQueryHalfExtents: {
         x: number;
         y: number;
@@ -33,10 +39,12 @@ export declare class NavMeshQuery {
     findNearestPoly(position: Vector3, options?: {
         /**
          * The polygon filter to apply to the query.
+         * @default this.defaultFilter
          */
         filter?: QueryFilter;
         /**
          * The search distance along each axis. [(x, y, z)]
+         * @default this.defaultQueryHalfExtents
          */
         halfExtents?: Vector3;
     }): {
@@ -55,10 +63,20 @@ export declare class NavMeshQuery {
      * @param startRef Reference of polygon to start search from
      * @param centerPos Center of circle
      * @param radius Radius of circle
-     * @param filter The polygon filter to apply to the query
-     * @param maxResult The maximum number of polygons the result arrays can hold
+     * @param options
      */
-    findPolysAroundCircle(startRef: number, centerPos: Vector3, radius: number, filter?: QueryFilter, maxResult?: number): {
+    findPolysAroundCircle(startRef: number, centerPos: Vector3, radius: number, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         * @default this.defaultFilter
+         */
+        filter?: QueryFilter;
+        /**
+         * The maximum number of polygons the result arrays can hold.
+         * @default 256
+         */
+        maxPolys?: number;
+    }): {
         success: boolean;
         status: number;
         resultRefs: number[];
@@ -70,10 +88,20 @@ export declare class NavMeshQuery {
      * Finds polygons that overlap the search box.
      * @param center The center of the search box
      * @param halfExtents The search distance along each axis
-     * @param filter The polygon filter to apply to the query
-     * @param maxPolys The maximum number of polygons the search result can hold
+     * @param options
      */
-    queryPolygons(center: Vector3, halfExtents: Vector3, filter?: QueryFilter, maxPolys?: number): {
+    queryPolygons(center: Vector3, halfExtents: Vector3, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         * @default this.defaultFilter
+         */
+        filter?: QueryFilter;
+        /**
+         * The maximum number of polygons the search result can hold.
+         * @default 256
+         */
+        maxPolys?: number;
+    }): {
         success: boolean;
         status: number;
         polyRefs: number[];
@@ -81,6 +109,9 @@ export declare class NavMeshQuery {
     };
     /**
      * Returns the closest point on the given polygon to the given position.
+     *
+     * @param polyRef The reference of the polygon
+     * @param position The position to find the closest point to
      */
     closestPointOnPoly(polyRef: number, position: Vector3): {
         success: boolean;
@@ -93,41 +124,80 @@ export declare class NavMeshQuery {
         posOverPoly: boolean;
     };
     /**
-     * Returns the closest point on the NavMesh to the given position.
+     * Finds the closest point on the NavMesh to the given position.
+     * @param position the position to find the closest point to
+     * @param options additional options
+     * @returns the result of the find closest point operation
      */
-    getClosestPoint(position: Vector3, options?: {
+    findClosestPoint(position: Vector3, options?: {
         /**
          * The polygon filter to apply to the query.
+         * @default this.defaultFilter
          */
         filter?: QueryFilter;
         /**
          * The search distance along each axis. [(x, y, z)]
+         * @default this.defaultQueryHalfExtents
          */
         halfExtents?: Vector3;
-    }): Vector3;
+    }): {
+        success: boolean;
+        status: number;
+        polyRef: number;
+        point: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        isPointOverPoly: boolean;
+    };
     /**
      * Returns a random point on the NavMesh within the given radius of the given position.
+     *
+     * @param position the center of the search circle
+     * @param radius the radius of the search circle
+     * @param options additional options
      */
-    getRandomPointAround(position: Vector3, radius: number, options?: {
+    findRandomPointAroundCircle(position: Vector3, radius: number, options?: {
+        /**
+         * The reference id of the polygon to start the search from.
+         * If not provided, the nearest polygon to the position will be used.
+         */
+        startRef?: number;
         /**
          * The polygon filter to apply to the query.
+         * @default this.defaultFilter
          */
         filter?: QueryFilter;
         /**
          * The search distance along each axis. [(x, y, z)]
+         * @default this.defaultQueryHalfExtents
          */
         halfExtents?: Vector3;
-    }): Vector3;
+    }): {
+        success: boolean;
+        status: number;
+        randomPolyRef: number;
+        randomPoint: Vector3;
+    };
     /**
      * Moves from the start to the end position constrained to the navigation mesh.
+     *
+     * @param startRef the reference id of the start polygon.
+     * @param startPosition a position of the mover within the start polygon.
+     * @param endPosition the desired end position of the mover.
+     *
+     * @returns The result of the move along surface operation.
      */
     moveAlongSurface(startRef: number, startPosition: Vector3, endPosition: Vector3, options?: {
         /**
          * The polygon filter to apply to the query.
+         * @default this.defaultFilter
          */
         filter?: QueryFilter;
         /**
          * The maximum number of polygons the output visited array can hold.
+         * @default 256
          */
         maxVisitedSize?: number;
     }): {
@@ -141,7 +211,31 @@ export declare class NavMeshQuery {
         visited: number[];
     };
     /**
-     * Gets the height of the polygon at the provided position using the height detail
+     * Returns a random point on the navmesh.
+     * @param options additional options
+     * @returns a random point on the navmesh
+     */
+    findRandomPoint(options?: {
+        /**
+         * The polygon filter to apply to the query.
+         * @default this.defaultFilter
+         */
+        filter?: QueryFilter;
+    }): {
+        success: boolean;
+        status: number;
+        randomPolyRef: number;
+        randomPoint: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+    /**
+     * Gets the height of the polygon at the provided position using the height detail.
+     *
+     * @param polyRef the reference id of the polygon.
+     * @param position a position within the xz-bounds of the polygon.
      */
     getPolyHeight(polyRef: number, position: Vector3): {
         success: boolean;
@@ -151,22 +245,236 @@ export declare class NavMeshQuery {
     /**
      * Finds a straight path from the start position to the end position.
      *
+     * @param start the start position
+     * @param end the end position
+     * @param options additional options
+     *
      * @returns an array of Vector3 positions that make up the path, or an empty array if no path was found.
      */
     computePath(start: Vector3, end: Vector3, options?: {
         /**
          * The polygon filter to apply to the query.
+         * @default this.defaultFilter
          */
         filter?: QueryFilter;
         /**
-         * The maximum number of polygons the @p path array can hold. [Limit: >= 1]
+         * The maximum number of polygons the path array can hold. [Limit: >= 1]
+         * @default 256
          */
         maxPathPolys?: number;
         /**
-         * The maximum number of points the straight path arrays can hold.  [Limit: > 0]
+         * The maximum number of points the straight path arrays can hold. [Limit: > 0]
+         * @default 256
          */
         maxStraightPathPoints?: number;
-    }): Vector3[];
+    }): {
+        /**
+         * Whether a path was successfully computed.
+         */
+        success: boolean;
+        /**
+         * Error information if the path computation failed.
+         */
+        error?: {
+            /**
+             * Description of the error.
+             */
+            name: string;
+            /**
+             * A dtStatus status code if relevant.
+             */
+            status?: number;
+        };
+        /**
+         * The result path.
+         */
+        path: Vector3[];
+    };
+    /**
+     * Finds a path from the start polygon to the end polygon.
+     * @param startRef the reference id of the start polygon.
+     * @param endRef the reference id of the end polygon.
+     * @param startPosition position within the start polygon.
+     * @param endPosition position within the end polygon.
+     * @param options additional options
+     * @returns
+     */
+    findPath(startRef: number, endRef: number, startPosition: Vector3, endPosition: Vector3, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         * @default this.defaultFilter
+         */
+        filter?: QueryFilter;
+        /**
+         * The maximum number of polygons the path array can hold. [Limit: >= 1]
+         * @default 256
+         */
+        maxPathPolys?: number;
+    }): {
+        success: boolean;
+        status: number;
+        polys: R.UnsignedIntArray;
+    };
+    /**
+     * Finds the straight path from the start to the end position within the polygon corridor.
+     *
+     * This method peforms what is often called 'string pulling'.
+     *
+     * The start position is clamped to the first polygon in the path, and the
+     * end position is clamped to the last. So the start and end positions should
+     * normally be within or very near the first and last polygons respectively.
+     *
+     * The returned polygon references represent the reference id of the polygon
+     * that is entered at the associated path position. The reference id associated
+     * with the end point will always be zero.  This allows, for example, matching
+     * off-mesh link points to their representative polygons.
+     *
+     * If the provided result arrays are too small for the entire result set,
+     * they will be filled as far as possible from the start toward the end
+     * position.
+     *
+     * @param start path start position
+     * @param end path end position
+     * @param path an array of polygon references that represent the path corridor
+     * @param options additional options
+     * @returns the straight path result
+     */
+    findStraightPath(start: Vector3, end: Vector3, path: R.UnsignedIntArray, options?: {
+        /**
+         * The maximum number of points the straight path arrays can hold. [Limit: > 0]
+         * @default 256
+         */
+        maxStraightPathPoints?: number;
+        /**
+         * Options for dtNavMeshQuery::findStraightPath
+         *
+         * Add a vertex at every polygon edge crossing where area changes.
+         * DT_STRAIGHTPATH_AREA_CROSSINGS = 1
+         *
+         * Add a vertex at every polygon edge crossing.
+         * DT_STRAIGHTPATH_ALL_CROSSINGS = 2
+         *
+         * @default 0
+         */
+        straightPathOptions?: number;
+    }): {
+        success: boolean;
+        status: number;
+        /**
+         * The straight path points.
+         */
+        straightPath: R.FloatArray;
+        /**
+         * The straight path flags.
+         */
+        straightPathFlags: R.UnsignedCharArray;
+        /**
+         * The reference ids of the visited polygons.
+         *
+         * Raw.Module.DT_STRAIGHTPATH_START
+         * Raw.Module.DT_STRAIGHTPATH_END
+         * Raw.Module.DT_STRAIGHTPATH_OFFMESH_CONNECTION
+         */
+        straightPathRefs: R.UnsignedIntArray;
+        /**
+         * The number of points in the straight path.
+         */
+        straightPathCount: number;
+    };
+    /**
+     * Casts a 'walkability' ray along the surface of the navigation mesh from the start position toward the end position.
+     *
+     * This method is meant to be used for quick, short distance checks.
+     *
+     * If the path array is too small to hold the result, it will be filled as far as possible from the start postion toward the end position.
+     *
+     * The raycast ignores the y-value of the end position. (2D check.) This places significant limits on how it can be used.
+     *
+     * <b>Using the Hit Parameter (t)</b>
+     *
+     * If the hit parameter is a very high value, then the ray has hit
+     * the end position. In this case the path represents a valid corridor to the
+     * end position and the value of hitNormal is undefined.
+     *
+     * If the hit parameter is zero, then the start position is on the wall that
+     * was hit and the value of hitNormal is undefined.
+     *
+     * If 0 < t < 1.0 then the following applies:
+     *
+     * ```
+     * distanceToHitBorder = distanceToEndPosition * t
+     * hitPoint = startPos + (endPos - startPos) * t
+     * ```
+     *
+     * <b>Use Case Restriction</b>
+     *
+     * Consider a scene where there is a main floor with a second floor balcony that hangs over the main floor.
+     * So the first floor mesh extends below the balcony mesh.
+     * The start position is somewhere on the first floor.
+     * The end position is on the balcony.
+     *
+     * The raycast will search toward the end position along the first floor mesh.
+     * If it reaches the end position's xz-coordinates it will indicate FLT_MAX,(no wall hit), meaning it reached the end position.
+     * This is one example of why this method is meant for short distance checks.
+     *
+     * @param startRef the reference id of the start polygon.
+     * @param startPosition a position within the start polygon representing the start of the ray
+     * @param endPosition the position to cast the ray toward.
+     * @param options additional options
+     */
+    raycast(startRef: number, startPosition: Vector3, endPosition: Vector3, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         * @default this.defaultFilter
+         */
+        filter?: QueryFilter;
+        /**
+         * Determines how the raycast behaves.
+         *
+         * // Raycast should calculate movement cost along the ray and fill RaycastHit::cost
+         * DT_RAYCAST_USE_COSTS = 1
+         *
+         * @default 0
+         */
+        raycastOptions?: number;
+        /**
+         * Optional parent of start ref. Used during for cost calculation.
+         */
+        prevRef?: number;
+    }): {
+        /**
+         * Whether the raycast was successful.
+         */
+        success: boolean;
+        /**
+         * The status of the raycast.
+         */
+        status: number;
+        /**
+         * The hit parameter.
+         */
+        t: number;
+        /**
+         * The normal of the nearest wall hit.
+         */
+        hitNormal: Vector3;
+        /**
+         * The index of the edge on the final polygon where the wall was hit.
+         */
+        hitEdgeIndex: number;
+        /**
+         * The reference ids of the visited polygons.
+         */
+        path: number[];
+        /**
+         * The maximum number of polygons the path can contain.
+         */
+        maxPath: number;
+        /**
+         * The cost of the path until hit.
+         */
+        pathCost: number;
+    };
     /**
      * Destroys the NavMeshQuery instance
      */

package/package.json

@@ -6,7 +6,7 @@
     "email": "isaac@isaacmason.com",
     "url": "https://isaacmason.com/"
   },
-  "version": "0.22.0",
+  "version": "0.24.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.22.0"
+    "@recast-navigation/wasm": "0.24.0"
   },
   "devDependencies": {
     "@babel/core": "^7.24.4",