
## How to use the navigation mesh?

There are many cases to use a navigation mesh: AI and path finding, replace physics for collision detection (only allow player to go where it's possible instead of using collision detection) and many more cases the BabylonJS users will find.

First, create the navigation plugin
```
let navigationPlugin = new BABYLON.RecastJSPlugin();
```
Prepare some parameters for the agent constraints (described below)

```
var parameters = {
        cs: 0.2,
        ch: 0.2,
        walkableSlopeAngle: 35,
        walkableHeight: 1,
        walkableClimb: 1,
        walkableRadius: 1,
        maxEdgeLen: 12.,
        maxSimplificationError: 1.3,
        minRegionArea: 8,
        mergeRegionArea: 20,
        maxVertsPerPoly: 6,
        detailSampleDist: 6,
        detailSampleMaxError: 1,
        };
```

Call the navigation mesh generation with the parameters and the list of meshes

```
navigationPlugin.createNavMesh([groundMesh, wallMesh1, wallMesh2, stair1, stair2], parameters);
```

And that's it! you can now use the navigation mesh with the crowd system or make queries.

Optionaly, you can get a display of the navmesh to ensure it corresponds to your space constraints

```
navmeshdebug = navigationPlugin.createDebugNavMesh(scene);
var matdebug = new BABYLON.StandardMaterial('matdebug', scene);
matdebug.diffuseColor = new BABYLON.Color3(0.1, 0.2, 1);
matdebug.alpha = 0.2;
navmeshdebug.material = matdebug;
```    

## Parameters

cs - The meshes are voxelized in order to compute walkable navmesh. This parameter in world unit define the widthand depth of 1 voxel.

ch - Same as cs but for height of the voxel.

walkableSlopeAngle - Angle in degree for the maximum walkable slop.

walkableHeight - The height in voxel units that is allowd to walk in.

walkableClimb - The delta in voxel units that can be climbed.

walkableRadius - the radius in voxel units of the agents.

maxEdgeLen - The maximum allowed length for contour edges along the border of the mesh. Voxel units.

maxSimplificationError - The maximum distance a simplified contour's border edges should deviate  the original raw contour. Voxel units.

minRegionArea -  The minimum number of cells allowed to form isolated island areas. Voxel units.

mergeRegionArea - Any regions with a span count smaller than this value will, if possible, be merged with larger regions. Voxel units.

maxVertsPerPoly - The maximum number of vertices allowed for polygons generated during the contour to polygon conversion process. Must be > 3.

detailSampleDist - Sets the sampling distance to use when generating the detail mesh. World units.

detailSampleMaxError - The maximum distance the detail mesh surface should deviate from heightfield data. World Units.

## Queries

Basically, query functions help at getting constraint point and vector by the navigation mesh.

```
getClosestPoint(position: Vector3): Vector3;
getRandomPointAround(position: Vector3, maxRadius: number): Vector3;
moveAlong(position: Vector3, destination: Vector3): Vector3;
```

Respectively: 
- get a point on the navmesh close to a world position parameter
- get a random world position, on the navmesh, inside a circle of maxRadius.
- constraint a segment by the navmesh and returns the ending world position. Like walking on the navmesh and stopping at the edge.

When the query can't find a valid solution, the value (0,0,0) is returned.

Those functions use a bounding box for querying the world. The solution returned is within that bound. To properly set the default box extent to get a finer or broader result, call:

```
setDefaultQueryExtent(extent: Vector3): void;
```

If your query returns a point too far from the expected result, use a smaller extent. 

It's possible to get a path built for navigation as a point array. It's up to the user to use this array for drawing prediction path, trigger events,...

```
var pathPoints = navigationPlugin.computePath(crowd.getAgentPosition(agent), navigationPlugin.getClosestPoint(destinationPoint));
pathLine = BABYLON.MeshBuilder.CreateDashedLines("ribbon", {points: pathPoints, updatable: true, instance: pathLine}, scene);
```

## Baking result

Building a navigation mesh can take a lot of cpu and network resources. In order to lower the download size and cpu needed, it's possible to bake the result of the navigation mesh computation to a byte stream. That byte stream can later be restored to get the navigation mesh back.

To retrieve the binary representation of the computed navigation mesh:

``` 
var binaryData = navigationPlugin.getNavmeshData();
```

binaryData is an Uint8Array that you can save to a file for example.
To restore an UInt8Array to a navigation mesh:

```
navigationPlugin.buildFromNavmeshData(uint8array);
```


## Crowds and navigation agents

![a crowd ](/img/extensions/navigation/CrowdExample.png)

Now we have a navmesh, we can create autonomous agents and make them navigate within that navmesh constraint.
The agents will find the best path to that destination while avoinding other crowd agents.
An agent is attach to a Transform. That means that you have to attach a mesh to see them but also that you can attach pretty much anything.

A demo can be found at: <Playground id="#X5XCVT#240" title="Crowd and Navigation Agents" description="Crowd and navigation agents." image=""/>

Click anywhere on the navmesh to make the agents go to that location.

## How to use it?

First thing is to create a crowd that all agents will belong to. Parameters are the maximum number of agents in the crowd, the maximum agent radius and the scene.

```
var crowd = navigationPlugin.createCrowd(10, 0.1, scene);
```

Then to create an agent and attach it to a transform, call:

```
var agentIndex = crowd.addAgent(position, agentParameters, transform);
```

And that's it! You will get a non moving agent. We now want to move it.

```
crowd.agentGoto(agentIndex, navigationPlugin.getClosestPoint(endPoint));
```
This code will get the closest position on the navmesh to endPoint. Then it asks the agent to go to that position.
Depending on your agent parameters, it will get there faster of slower.

## Agent Parameters

radius - Radius of the agent. World Unit.

height - Heigh in World Unit.

maxAcceleration - Acceleration max in World Unit per second per second

maxSpeed - Max speed in World Unit per second.

collisionQueryRange - The agent collision system will take care of others within that radius in World Unit.

pathOptimizationRange - How the path will be optimized and made more straight.

separationWeight - How hard the system will try to separate the agent. A Value of 0 means it will not try and agents might collide.

You can update any of these parameters, per agent, by calling :

```
// change speed and max speed
crowd.updateAgentParameters(agentIndex, {maxSpeed:10, maxAcceleration:200});
```

## Teleport

You can teleport an agent to any position using this call:

```
crowd.agentTeleport(agentIndex, navigationPlugin.getClosestPoint(destinationPoint));
```

Please note the navigation state is reseted when teleporting. You'll have to call ```agentGoto``` to choose a new destination.

## Agent orientation and next path target

Recastjs crowd system does not handle agent orientation. But the velocity is available and it's possible to orient the geometry toward it.
To do so, you will need to use Math.atan2 like in the following example. Please take care of the length of the velocity vector. If it's not big enough, you may encounter jittering.

```
let velocity = crowd.getAgentVelocity(agentIndex);
if (velocity.length() > 0.2)
{
    var desiredRotation = Math.atan2(velocity.x, velocity.z);
    // interpolate the rotation on Y to get a smoother orientation change
    ag.mesh.rotation.y = ag.mesh.rotation.y + (desiredRotation - ag.mesh.rotation.y) * 0.05;
}
```
In this PG <Playground id="#6AE0RP" title="Agent Orientation and Next Path Targeting" description="Example of agent orientation and next path targeting." image=""/>

The agent's cube is oriented by the velocity and a grey little box is placed at the position of the next path corner.


Generate letters in BABYLON meshes.

## Basic-Usage

	Writer = BABYLON.MeshWriter(scene, {scale:scale});
	text1  = new Writer( 
	                "ABC",
	                {
	                    "anchor": "center",
	                    "letter-height": 50,
	                    "color": "#1C3870",
	                    "position": {
	                        "z": 20
	                    }
	                }
	            );

PG: <Playground id="#PL752W#150" title="Mesh Writer Example 1" description="" image=""/>

## Getting the code

Copy https://github.com/BabylonJS/Extensions/blob/master/MeshWriter/meshwriter.min.js or https://github.com/BabylonJS/Extensions/blob/master/MeshWriter/meshwriter.js and build it into your load sequence.

## If you prefer npm 

> ### npm i meshwriter

 Import in your React/Angular component:

> import { MeshWriter } from "meshwriter";

With __meshwriter__ you can use MeshWriter directly like this:

	  let Writer = MeshWriter(this.scene, { scale: .25, defaultFont: "Arial" });
	    let textMesh = new Writer("Hello World", {
	      "font-family": "Arial",
	      "letter-height": 30,
	      "letter-thickness": 12,
	      color: "#1C3870",
	      anchor: "center",
	      colors: {
		diffuse: "#F0F0F0",
		specular: "#000000",
		ambient: "#F0F0F0",
		emissive: "#ff00f0"
	      },
	      position: {
		x: 0,
		y: 10,
		z: 0
	      }
	    });


## Superconstructor - BABYLON.MeshWriter()

After MeshWriter is loaded, BABYLON.MeshWriter is defined.  It is called with one or two parameters.
- **scene** &nbsp; required
- **preferences** &nbsp; optional &nbsp; The preferences object may specify up to three values

	      FIELD                 DEFAULT
	    default-font           Helvetica
	    scale                      1
	    letter-origin         "letter-center"

The call to BABYLON.MeshWriter returns a constructor.  Call it "**Writer**".

## Constructor - new Writer()

new Writer() is called with a string and an (optional) options parameter.&nbsp; The options object conforms to normal BabylonJS structures and terminology.

	      FIELD                 DEFAULT
	    font-family             default-font
	    anchor                  left
	    letter-height           100
	    letter-thickness        1
	    color                   #808080              # hits emissive only
	    alpha                   1
	    position
	        x                   0
	        y                   0
	        z                   0
	    colors                                       # if you need to control more than just emissive
	        diffuse             #F0F0F0
	        specular            #000000
	        ambient             #F0F0F0
	        emissive            color                # from option field 'color' above


**new Writer()** builds a mesh with material that is inserted into the scene.&nbsp; This is a multi-step process with interim meshes and holes per letter.&nbsp;  These meshes are sucked into an SPS and then disposed.&nbsp; At the end, one mesh, one material and one SPS have been added to the scene.

**new Writer()** also returns a **writer** instance with useful methods.&nbsp; See below.

## Instance

Each **writer** instance has methods to allow one to retrieve the BabylonJS objects or to get/set attributes of the SPS.

	   getSPS
	   getMesh
	   getMaterial
	   color                   # sets or gets color but no change to material
	   alpha                   # sets or gets alpha but no change to material
	   setColor                # set emissive color and change color value
	   setAlpha                # change value and material
	   overrideOpac            # change material but not value
	   resetOpac               # sets material to current value
	   dispose      

## Usage Hints

If you wish to do extensive things with position, rotation or animation, retrieve the meshes and materials from the instance using the methods shown above.&nbsp; The output from **new Writer()** is an SPS with one particle for each character.

Example:
PG: <Playground id="#PL752W#151" title="Mesh Writer Example 2" description="" image=""/>

	    const SCALE =.25 
	    const TEXT_SIZE = 35
	    const TEXT_THICKNESS =10

	    Writer = BABYLON.MeshWriter(scene, {scale:SCALE,defaultFont:"Arial"});
	    textMesh  = new Writer( 
			    "BABYLON JS",{
				"font-family":"Arial",
				anchor: "center",
				"letter-height": TEXT_SIZE,
				    "letter-thickness": TEXT_THICKNESS,
				    color: "#1C3870",
				    colors:{
				    diffuse  :"#F0F0F0",
				    specular :"#000000",
				    ambient  :"#F0F0F0",
				    emissive :"#ff00f0"   
				    },
				    position: {
					x:0,
					y:5,
					z: 70
				}
			    }
			);

	    //Text Writer create SPS with Particle for each letter
	    SPS =  textMesh.getSPS()    

	    //Update animation
	    SPS.updateParticle =  (particle)=> {
		    particle.rotation.x -= 0.06;
	    };

	    scene.registerBeforeRender( ()=> {
		SPS.setParticles();
		//sps.mesh.rotation.y = k;
	    });  


Colors:&nbsp; With most lighting, it is enough just to use the "color" field to specify the letter coloring.&nbsp; However, programmers may specify all four color types by putting a "colors" object in the options object.

Unless you have a specific need, do not specify a font.&nbsp; The default font, Helvetica, has the most extensive characters and the fewest faces; it will be the most efficient if you have a lot of text.&nbsp; Jura was added because the author likes it for numbers.




Crowd Navigation System

Coming next

Creating A Navigation Mesh

Learn how to create a mesh as a confinment system for crowd agents.

Crowd Agents

Learn how to create crowd agents that follow a path along a navigation mesh.