@onerjs/addons 8.27.1 → 8.27.3

package/navigation/plugin/RecastNavigationJSPlugin.d.ts

@@ -0,0 +1,419 @@
+import type { TileCacheMeshProcess, NavMesh, QueryFilter, TileCache, NavMeshQuery } from "@recast-navigation/core";
+import type { ICrowd, INavigationEnginePlugin, IObstacle } from "@onerjs/core/Navigation/INavigationEngine.js";
+import type { Mesh } from "@onerjs/core/Meshes/mesh.js";
+import type { Scene } from "@onerjs/core/scene.js";
+import { Vector3 } from "@onerjs/core/Maths/math.js";
+import type { IVector3Like } from "@onerjs/core/Maths/math.like.js";
+import type { Nullable } from "@onerjs/core/types.js";
+import type { CreateNavMeshResult, GeneratorIntermediates, INavMeshParametersV2, RecastInjection } from "../types.js";
+/**
+ * Navigation plugin for Babylon.js. It is a simple wrapper around the recast-navigation-js library. Not all features are implemented.
+ * @remarks This plugin provides navigation mesh generation and pathfinding capabilities using the recast-navigation-js library
+ * @remarks It supports both single-threaded and multi-threaded generation of navigation meshes.
+ * @remarks The plugin can be used to create navigation meshes from meshes in a scene, compute paths, and manage crowd agents, etc.
+ * @remarks It also provides methods for creating obstacles and querying the navigation mesh.
+ * @see https://github.com/isaac-mason/recast-navigation-js
+ */
+export declare class RecastNavigationJSPluginV2 implements INavigationEnginePlugin {
+    /**
+     *  Creates a navigation mesh - will be injected by the factory
+     * @param meshes array of all the geometry used to compute the navigation mesh
+     * @param parameters bunch of parameters used to filter geometry
+     * @returns the created navmesh and navmesh query
+     */
+    createNavMeshImpl: (meshes: Array<Mesh>, parameters: INavMeshParametersV2) => CreateNavMeshResult;
+    /**
+     * Creates a navigation mesh - will be injected by the factory
+     * @param meshes array of all the geometry used to compute the navigation mesh
+     * @param parameters bunch of parameters used to filter geometry
+     * @returns the created navmesh and navmesh query
+     */
+    createNavMeshAsyncImpl: (meshes: Array<Mesh>, parameters: INavMeshParametersV2) => Promise<CreateNavMeshResult>;
+    /**
+     * recast-navigation-js injection
+     */
+    bjsRECAST: RecastInjection;
+    /**
+     * plugin name
+     */
+    name: string;
+    /**
+     * the navmesh created
+     */
+    navMesh?: NavMesh;
+    /**
+     * The navmesh query created from the navmesh
+     * @remarks This is used to query the navmesh for pathfinding and other navigation tasks
+     */
+    get navMeshQuery(): NavMeshQuery;
+    private _navMeshQuery;
+    /**
+     * Intermediates generated during the navmesh creation
+     * @remarks This is used for debugging and visualization purposes.
+     * @remarks You have access to vertices, indices and vertex colors to visusalize the navmesh creation process.
+     * @remarks This is only available if the `keepIntermediates` parameter is set
+     * @remarks to true during navmesh generation.
+     */
+    private _intermediates?;
+    /**
+     * Gets the intermediates generated during the navmesh creation
+     * @returns The generator intermediates, or undefined if not available
+     */
+    get intermediates(): GeneratorIntermediates | undefined;
+    /**
+     * Tile cache used for tiled navigation meshes
+     * @remarks This is used to store and manage tiles of the navigation mesh for efficient path and when obstacles are used.
+     */
+    private _tileCache?;
+    /**
+     * Gets the tile cache used for tiled navigation meshes
+     * @returns The tile cache instance, or undefined if not available
+     */
+    get tileCache(): TileCache | undefined;
+    private _maximumSubStepCount;
+    private _timeStep;
+    private _timeFactor;
+    private _crowd?;
+    /**
+     * Creates a RecastNavigationJSPluginV2 instance
+     * @param recastInjection The recast-navigation-js injection containing core and generators
+     */
+    constructor(recastInjection?: RecastInjection);
+    /**
+     * Set the time step of the navigation tick update.
+     * Default is 1/60.
+     * A value of 0 will disable fixed time update
+     * @param newTimeStep the new timestep to apply to this world.
+     */
+    setTimeStep(newTimeStep?: number): void;
+    /**
+     * Get the time step of the navigation tick update.
+     * @returns the current time step
+     */
+    getTimeStep(): number;
+    /**
+     * If delta time in navigation tick update is greater than the time step
+     * a number of sub iterations are done. If more iterations are need to reach deltatime
+     * they will be discarded.
+     * A value of 0 will set to no maximum and update will use as many substeps as needed
+     * @param newStepCount the maximum number of iterations
+     */
+    setMaximumSubStepCount(newStepCount?: number): void;
+    /**
+     * Get the maximum number of iterations per navigation tick update
+     * @returns the maximum number of iterations
+     */
+    getMaximumSubStepCount(): number;
+    /**
+     * Time factor applied when updating crowd agents (default 1). A value of 0 will pause crowd updates.
+     * @param value the time factor applied at update
+     */
+    set timeFactor(value: number);
+    /**
+     * Get the time factor used for crowd agent update
+     * @returns the time factor
+     */
+    get timeFactor(): number;
+    /**
+     * Creates a navigation mesh - will be injected by the factory
+     * @param meshes array of all the geometry used to compute the navigation mesh
+     * @param parameters bunch of parameters used to filter geometry
+     * @returns the created navmesh and navmesh query
+     * @throws Error if the function is not injected yet or if the navmesh is not created
+     */
+    createNavMesh(meshes: Array<Mesh>, parameters: INavMeshParametersV2): CreateNavMeshResult;
+    /**
+     * Creates a navigation mesh asynchronously - will be injected by the factory
+     * @param meshes array of all the geometry used to compute the navigation mesh
+     * @param parameters bunch of parameters used to filter geometry
+     * @returns the created navmesh and navmesh query
+     * @throws Error if the function is not injected yet or if the navmesh is not created
+     */
+    createNavMeshAsync(meshes: Array<Mesh>, parameters: INavMeshParametersV2): Promise<CreateNavMeshResult>;
+    /**
+     * Create a navigation mesh debug mesh
+     * @param scene is where the mesh will be added
+     * @returns debug display mesh
+     */
+    createDebugNavMesh(scene: Scene): Mesh;
+    /**
+     * Get a navigation mesh constrained position, closest to the parameter position
+     * @param position world position
+     * @returns the closest point to position constrained by the navigation mesh
+     */
+    getClosestPoint(position: IVector3Like, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        /**
+         * Half extents for the search box
+         */
+        halfExtents?: IVector3Like;
+    }): Vector3;
+    /**
+     * Get a navigation mesh constrained position, closest to the parameter position
+     * @param position world position
+     * @param result output the closest point to position constrained by the navigation mesh
+     */
+    getClosestPointToRef(position: IVector3Like, result: Vector3, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        /**
+         * Half extents for the search box
+         */
+        halfExtents?: IVector3Like;
+    }): void;
+    /**
+     * Get a navigation mesh constrained position, within a particular radius
+     * @param position world position
+     * @param maxRadius the maximum distance to the constrained world position
+     * @returns the closest point to position constrained by the navigation mesh
+     */
+    getRandomPointAround(position: IVector3Like, maxRadius: number, options?: {
+        startRef?: number;
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        /**
+         * Half extents for the search box
+         */
+        halfExtents?: IVector3Like;
+    }): Vector3;
+    /**
+     * Get a navigation mesh constrained position, within a particular radius
+     * @param position world position
+     * @param maxRadius the maximum distance to the constrained world position
+     * @param result output the closest point to position constrained by the navigation mesh
+     */
+    getRandomPointAroundToRef(position: IVector3Like, maxRadius: number, result: Vector3, options?: {
+        startRef?: number;
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        /**
+         * Half extents for the search box
+         */
+        halfExtents?: IVector3Like;
+    }): void;
+    /**
+     * Compute the final position from a segment made of destination-position
+     * @param position position to start from
+     * @param destination position to go to
+     * @param startRef the reference id of the start polygon
+     * @param options options for the function
+     * @returns the resulting point along the navmesh
+     */
+    moveAlong(position: IVector3Like, destination: IVector3Like, startRef?: number, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        /**
+         * The maximum number of polygons the output visited array can hold.
+         */
+        maxVisitedSize?: number;
+    }): Vector3;
+    /**
+     * Compute the final position from a segment made of destination-position
+     * @param position world position
+     * @param destination world position
+     * @param result output the resulting point along the navmesh
+     * @param startRef the reference id of the start polygon.
+     * @param options options for the function
+     */
+    moveAlongToRef(position: IVector3Like, destination: IVector3Like, result: Vector3, startRef?: number, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        maxVisitedSize?: number;
+    }): void;
+    /**
+     * Compute a navigation path from start to end. Returns an empty array if no path can be computed
+     * Path is straight.
+     * @param start world position
+     * @param end world position
+     * @param options options for the function
+     * @returns array containing world position composing the path
+     */
+    computePath(start: IVector3Like, end: IVector3Like, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        /**
+         * Half extents for the search box
+         */
+        halfExtents?: IVector3Like;
+        maxPathPolys?: number;
+        maxStraightPathPoints?: number;
+    }): Vector3[];
+    /**
+     * Creates a navigation mesh - will be injected by the factory
+     * @param start the start position of the navmesh
+     * @param end the end position of the navmesh
+     * @param options options to configure the path computation
+     * @returns array containing world position composing the path
+     */
+    computePathSmooth(start: Vector3, end: Vector3, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        /**
+         * Half extents for the search box
+         */
+        halfExtents?: IVector3Like;
+        maxPathPolys?: number;
+        maxSmoothPathPoints?: number;
+        stepSize?: number;
+        slop?: number;
+    }): Vector3[];
+    /**
+     * Create a new Crowd so you can add agents
+     * @param maxAgents the maximum agent count in the crowd
+     * @param maxAgentRadius the maximum radius an agent can have
+     * @param scene to attach the crowd to
+     * @returns the crowd you can add agents to
+     */
+    createCrowd(maxAgents: number, maxAgentRadius: number, scene: Scene): ICrowd;
+    /**
+     * Set the Bounding box extent for doing spatial queries (getClosestPoint, getRandomPointAround, ...)
+     * The queries will try to find a solution within those bounds
+     * default is (1,1,1)
+     * @param extent x,y,z value that define the extent around the queries point of reference
+     */
+    setDefaultQueryExtent(extent: IVector3Like): void;
+    /**
+     * Get the Bounding box extent specified by setDefaultQueryExtent
+     * @returns the box extent values
+     */
+    getDefaultQueryExtent(): Vector3;
+    /**
+     * Get the Bounding box extent result specified by setDefaultQueryExtent
+     * @param result output the box extent values
+     */
+    getDefaultQueryExtentToRef(result: Vector3): void;
+    /**
+     * build the navmesh from a previously saved state using getNavmeshData
+     * @param data the Uint8Array returned by getNavmeshData
+     */
+    buildFromNavmeshData(data: Uint8Array): void;
+    /**
+     * returns the navmesh data that can be used later. The navmesh must be built before retrieving the data
+     * @returns data the Uint8Array that can be saved and reused
+     */
+    getNavmeshData(): Uint8Array;
+    /**
+     * build the tile cache from a previously saved state using getTileCacheData
+     * @param tileCacheData the data returned by getTileCacheData
+     * @param tileCacheMeshProcess optional process to apply to each tile created
+     */
+    buildFromTileCacheData(tileCacheData: Uint8Array, tileCacheMeshProcess?: TileCacheMeshProcess): void;
+    /**
+     * returns the tile cache data that can be used later. The tile cache must be built before retrieving the data
+     * @returns the tile cache data that can be used later. The tile cache must be built before retrieving the data
+     * @throws Error if there is no TileCache generated
+     * @remarks The returned data can be used to rebuild the tile cache later using buildFromTileCacheData
+     */
+    getTileCacheData(): Uint8Array;
+    /**
+     * Disposes
+     */
+    dispose(): void;
+    /**
+     * Creates a cylinder obstacle and add it to the navigation
+     * @param position world position
+     * @param radius cylinder radius
+     * @param height cylinder height
+     * @param doNotWaitForCacheUpdate if true the function will not wait for the tile cache to be fully updated before returning
+     * @returns the obstacle freshly created
+     */
+    addCylinderObstacle(position: IVector3Like, radius: number, height: number, doNotWaitForCacheUpdate?: boolean): Nullable<IObstacle>;
+    /**
+     * Creates an oriented box obstacle and add it to the navigation
+     * @param position world position
+     * @param extent box size
+     * @param angle angle in radians of the box orientation on Y axis
+     * @param doNotWaitForCacheUpdate if true the function will not wait for the tile cache to be fully updated before returning
+     * @returns the obstacle freshly created
+     */
+    addBoxObstacle(position: IVector3Like, extent: IVector3Like, angle: number, doNotWaitForCacheUpdate?: boolean): Nullable<IObstacle>;
+    /**
+     * Removes an obstacle created by addCylinderObstacle or addBoxObstacle
+     * @param obstacle obstacle to remove from the navigation
+     * @param doNotWaitForCacheUpdate if true the function will not wait for the tile cache to be fully updated before returning
+     *
+     */
+    removeObstacle(obstacle: IObstacle, doNotWaitForCacheUpdate?: boolean): void;
+    /**
+     * If this plugin is supported
+     * @returns true if plugin is supported
+     */
+    isSupported(): boolean;
+    /**
+     * Returns the seed used for randomized functions like `getRandomPointAround`
+     * @returns seed number
+     */
+    getRandomSeed(): number;
+    /**
+     * Set the seed used for randomized functions like `getRandomPointAround`
+     * @param seed number used as seed for random functions
+     */
+    setRandomSeed(seed: number): void;
+    /**
+     * Perform a raycast on the navmesh
+     * @param start start position
+     * @param end end position
+     * @returns if a direct path exists between start and end, and the hit point if any
+     */
+    raycast(start: IVector3Like, end: IVector3Like): {
+        hit: boolean;
+        hitPoint?: undefined;
+    } | {
+        hit: boolean;
+        hitPoint: Vector3;
+    };
+    /**
+     * Compute the final position from a segment made of destination-position, and return the height of the polygon
+     * This is a more sophisiticated version of moveAlong that will use the height of the polygon at the end position
+     * @param position world position to start from
+     * @param velocity wvelocity of the movement
+     * @param options options for the function
+     * @returns the resulting point along the navmesh, the polygon reference id and the height of the polygon
+     */
+    moveAlongWithVelocity(position: IVector3Like, velocity: IVector3Like, options?: {
+        /**
+         * The polygon filter to apply to the query.
+         */
+        filter?: QueryFilter;
+        /**
+         * Half extents for the search box
+         */
+        halfExtents?: IVector3Like;
+        /**
+         * The maximum number of polygons the output visited array can hold.
+         */
+        maxVisitedSize?: number;
+    }): {
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        polyRef: number;
+        height: number;
+    };
+    /**
+     * Handles common post-processing and validation of navmesh creation results
+     * @param result The partial result from navmesh creation
+     * @returns The validated and complete CreateNavMeshresult
+     */
+    private _processNavMeshResult;
+    private _preprocessParameters;
+}