Methods documentation

src/Navigation/INavigationEngine.ts

@@ -10,25 +10,50 @@ import { Scene } from "../scene";
 export interface INavigationEnginePlugin {
     name: string;
 
-    /// Create a navigation mesh that will constrain a Crowd of agents
+    /**
+     * Creates a navigation mesh
+     * @param mesh of all the geometry used to compute the navigatio mesh
+     * @param parameters bunch of parameters used to filter geometry
+     */
     createMavMesh(mesh: AbstractMesh, parameters: NavMeshParameters): void;
 
-    /// Create and a to the scene a debug navmesh. Set the material to make it visible
+    /**
+     * 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
+    /**
+     * 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: Vector3): Vector3;
 
-    /// return a random position within a position centered disk
+    /**
+     * 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: Vector3, maxRadius: number): Vector3;
 
     ///
     isSupported(): boolean;
 
-    /// Create a new Crowd so you can add agents
+    /**
+     * 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;
 
-    ///
+    /**
+     * Release all resources
+     */
     dispose(): void;
 }
 
@@ -36,100 +61,175 @@ export interface INavigationEnginePlugin {
  * Crowd Interface. A Crowd is a collection of moving agents constrained by a navigation mesh
  */
 export interface ICrowd {
-    /// add a new agent to the crowd with the specified parameter a corresponding transformNode.
-    /// You can attach anything to that node. The node position is updated in the scene update tick.
+    /**
+     * Add a new agent to the crowd with the specified parameter a corresponding transformNode.
+     * You can attach anything to that node. The node position is updated in the scene update tick.
+     * @param pos world position that will be constrained by the navigation mesh
+     * @param parameters agent parameters
+     * @param transform hooked to the agent that will be update by the scene
+     * @returns agent index
+     */
     addAgent(pos: Vector3, parameters: AgentParameters, transform: TransformNode): number;
 
-    ///
+    /**
+     * Returns the agent position in world space
+     * @param index agent index returned by addAgent
+     * @returns world space position
+     */
     getAgentPosition(index: number): Vector3;
 
-    ///
+    /**
+     * Gets the agent velocity in world space
+     * @param index agent index returned by addAgent
+     * @returns world space velocity
+     */
     getAgentVelocity(index: number): Vector3;
 
-    /// remove a particular agent previously created
+    /**
+     * remove a particular agent previously created
+     * @param index agent index returned by addAgent
+     */
     removeAgent(index: number): void;
 
-    /// get the list of all agents attached to this crowd
+    /**
+     * get the list of all agents attached to this crowd
+     * @returns list of agent indices
+     */
     getAgents() : number[];
 
-    /// Tick update done by the Scene. Agent position/velocity/acceleration is updated by this function
+    /**
+     * Tick update done by the Scene. Agent position/velocity/acceleration is updated by this function
+     * @param deltaTime in seconds
+     */
     update(deltaTime: number): void;
 
-    /// Asks a particular agent to go to a destination. That destination is constrained by the navigation mesh
+    /**
+     * Asks a particular agent to go to a destination. That destination is constrained by the navigation mesh
+     * @param index agent index returned by addAgent
+     * @param destination targeted world position
+     * @returns the closest point to position constrained by the navigation mesh
+     */
     agentGoto(index: number, destination: Vector3): void;
 
-    /// dispose
+    /**
+     * Release all resources
+     */
     dispose() : void;
 }
 
+/**
+ * Configures an agent
+ */
 export class AgentParameters {
-    /// Agent radius. [Limit: >= 0]
+    /**
+     *  Agent radius. [Limit: >= 0]
+     */
     radius: number;
 
-    /// Agent height. [Limit: > 0]
+    /**
+     * Agent height. [Limit: > 0]
+     */
     height: number;
 
-    /// Maximum allowed acceleration. [Limit: >= 0]
+    /**
+     *  Maximum allowed acceleration. [Limit: >= 0]
+     */
     maxAcceleration: number;
 
-    /// Maximum allowed speed. [Limit: >= 0]
+    /**
+     * Maximum allowed speed. [Limit: >= 0]
+     */
     maxSpeed: number;
 
-    /// Defines how close a collision element must be before it is considered for steering behaviors. [Limits: > 0]
+    /**
+     * Defines how close a collision element must be before it is considered for steering behaviors. [Limits: > 0]
+     */
     collisionQueryRange: number;
 
-    /// The path visibility optimization range. [Limit: > 0]
+    /**
+     * The path visibility optimization range. [Limit: > 0]
+     */
     pathOptimizationRange: number;
 
-    /// How aggresive the agent manager should be at avoiding collisions with this agent. [Limit: >= 0]
+    /**
+     * How aggresive the agent manager should be at avoiding collisions with this agent. [Limit: >= 0]
+     */
     separationWeight: number;
 }
 
+/**
+ * Configures the navigation mesh creation
+ */
 export class NavMeshParameters {
-    /// The xz-plane cell size to use for fields. [Limit: > 0] [Units: wu]
-    cs: number;
-
-    /// The y-axis cell size to use for fields. [Limit: > 0] [Units: wu]
+    /**
+     * The xz-plane cell size to use for fields. [Limit: > 0] [Units: wu] 
+     */
+	cs: number;
+
+	/**
+     * The y-axis cell size to use for fields. [Limit: > 0] [Units: wu]
+     */
     ch: number;
-
-    //constructor(): NavMeshParameters;
-    /// The maximum slope that is considered walkable. [Limits: 0 <= value < 90] [Units: Degrees]
+    
+    /**
+     * The maximum slope that is considered walkable. [Limits: 0 <= value < 90] [Units: Degrees] 
+     */
     walkableSlopeAngle: number;
 
-    /// Minimum floor to 'ceiling' height that will still allow the floor area to
-    /// be considered walkable. [Limit: >= 3] [Units: vx]
+    /**
+     * Minimum floor to 'ceiling' height that will still allow the floor area to 
+     * be considered walkable. [Limit: >= 3] [Units: vx] 
+     */
     walkableHeight: number;
 
-    /// Maximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx]
+    /**
+     * Maximum ledge height that is considered to still be traversable. [Limit: >=0] [Units: vx] 
+     */
     walkableClimb: number;
 
-    /// The distance to erode/shrink the walkable area of the heightfield away from
-    /// obstructions.  [Limit: >=0] [Units: vx]
+    /**
+     * The distance to erode/shrink the walkable area of the heightfield away from 
+     * obstructions.  [Limit: >=0] [Units: vx] 
+     */
     walkableRadius: number;
 
-    /// The maximum allowed length for contour edges along the border of the mesh. [Limit: >=0] [Units: vx]
+    /**
+     * The maximum allowed length for contour edges along the border of the mesh. [Limit: >=0] [Units: vx] 
+     */
     maxEdgeLen: number;
 
-    /// The maximum distance a simplfied contour's border edges should deviate
-    /// the original raw contour. [Limit: >=0] [Units: vx]
+    /**
+     * The maximum distance a simplfied contour's border edges should deviate 
+     * the original raw contour. [Limit: >=0] [Units: vx]
+     */
     maxSimplificationError: number;
 
-    /// The minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx]
+    /**
+     * The minimum number of cells allowed to form isolated island areas. [Limit: >=0] [Units: vx] 
+     */
     minRegionArea: number;
 
-    /// Any regions with a span count smaller than this value will, if possible,
-    /// be merged with larger regions. [Limit: >=0] [Units: vx]
+    /**
+     * Any regions with a span count smaller than this value will, if possible, 
+     * be merged with larger regions. [Limit: >=0] [Units: vx] 
+     */
     mergeRegionArea: number;
 
-    /// The maximum number of vertices allowed for polygons generated during the
-    /// contour to polygon conversion process. [Limit: >= 3]
+    /**
+     * The maximum number of vertices allowed for polygons generated during the 
+     * contour to polygon conversion process. [Limit: >= 3] 
+     */
     maxVertsPerPoly: number;
 
-    /// Sets the sampling distance to use when generating the detail mesh.
-    /// (For height detail only.) [Limits: 0 or >= 0.9] [Units: wu]
+    /**
+     * Sets the sampling distance to use when generating the detail mesh.
+     * (For height detail only.) [Limits: 0 or >= 0.9] [Units: wu] 
+     */
     detailSampleDist: number;
 
-    /// The maximum distance the detail mesh surface should deviate from heightfield
-    /// data. (For height detail only.) [Limit: >=0] [Units: wu]
+    /**
+     * The maximum distance the detail mesh surface should deviate from heightfield
+     * data. (For height detail only.) [Limit: >=0] [Units: wu] 
+     */
     detailSampleMaxError: number;
 }

src/Navigation/Plugins/recastJSPlugin.ts

@@ -112,8 +112,9 @@ export class RecastJSPlugin implements INavigationEnginePlugin {
     }
 
     /**
-     * Get a navigation mesh constrained position, closest to the parameter position
+     * 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: Vector3, maxRadius: number): Vector3 {
@@ -124,9 +125,11 @@ export class RecastJSPlugin implements INavigationEnginePlugin {
     }
 
     /**
-     * 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
+     * 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
     {
@@ -142,6 +145,9 @@ export class RecastJSPlugin implements INavigationEnginePlugin {
 
     }
 
+    /**
+     * 
+     */
     public isSupported(): boolean {
         return this.bjsRECAST !== undefined;
     }
@@ -154,6 +160,14 @@ export class RecastJSCrowd implements ICrowd {
     public agents: number[];
     private scene: Scene;
 
+    /**
+     * Constructor
+     * @param plugin recastJS plugin
+     * @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
+     */
     public constructor(plugin: RecastJSPlugin, maxAgents: number, maxAgentRadius: number, scene: Scene) {
         this.bjsRECASTPlugin = plugin;
         this.recastCrowd = new this.bjsRECASTPlugin.bjsRECAST.Crowd(maxAgents, maxAgentRadius, this.bjsRECASTPlugin.navMesh.getNavMesh());
@@ -192,7 +206,7 @@ export class RecastJSCrowd implements ICrowd {
     }
 
     /**
-     *
+     * Returns the agent position in world space
      * @param index agent index returned by addAgent
      * @returns world space position
      */
@@ -202,7 +216,7 @@ export class RecastJSCrowd implements ICrowd {
     }
 
     /**
-     *
+     * Returns the agent velocity in world space
      * @param index agent index returned by addAgent
      * @returns world space velocity
      */
@@ -259,6 +273,9 @@ export class RecastJSCrowd implements ICrowd {
         }
     }
 
+    /**
+     * Release all resources
+     */
     dispose() : void
     {
         this.recastCrowd.destroy();