
## Prerequisites

Internaly, navigation mesh with support for obstacles differs from 'standard' use case with one static navigation mesh.
Obstacles mark tiles as dirty. Those tiles need to be reprocessed to compute a portion of the navigation mesh.
To do so, Recast introduces the concept of tiles. Each tile is a square portion of the nav mesh. Tiles a processed each frame.
Making huge changes processed of a couple of frames.

In order to build a Tiled nav mesh instead of a single mesh, add the following lines to the nav mesh creation parameters:

```
var navmeshParameters = {
    cs: 0.2,
    ch: 0.2,
    walkableSlopeAngle: 0,
    walkableHeight: 0.0,
    walkableClimb: 0,
    walkableRadius: 1,
    maxEdgeLen: 12.,
    maxSimplificationError: 1.3,
    minRegionArea: 8,
    mergeRegionArea: 20,
    maxVertsPerPoly: 6,
    detailSampleDist: 6,
    detailSampleMaxError: 15,
    borderSize: 1,
    tileSize:20
    };
```

Note the addition of `tileSize`. It's the world unit size of each tile. If it's not present or has a value a zero, it falls back to the standard use and obstacles won't work.
Also, depending on your use case, this value must be carrefully chosen to trade between too many tiles and too much cpu intensive updates.

## Obstacles API

Once the navigation mesh is updated to take tiles into account, obstacles are accessible thru 3 simple functions:
```
addCylinderObstacle(position: Vector3, radius: number, height: number): IObstacle;
addBoxObstacle(position: Vector3, extent: Vector3, angle: number): IObstacle;
removeObstacle(obstacle: IObstacle): void;
```

Keep a list of added obstacles in order to remove them later. An obstacle that's not colliding with the navigation mesh will have no influence.

<Playground id="#WCSDE1" title="Adding a door to a navigation mesh" description="Example of door simulation using nav mesh obstacles."/>


Generate letters in BABYLON meshes.

## Basic-Usage

```javascript
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=""/>

## Getting the code

Copy https://github.com/BabylonJS/features/extensions/blob/master/MeshWriter/meshwriter.min.js or https://github.com/BabylonJS/features/extensions/blob/master/MeshWriter/meshwriter.js and build it into your load sequence.  
Maintenance of Mesh Writer is the responsibility of the author.

## 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:

```javascript
let Writer = MeshWriter(this.scene, { scale: 0.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 normalBabylon.js 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 theBabylon.js 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=""/>

```javascript
const SCALE = 0.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.



## Crowds and navigation agents

![a crowd ](/img/features/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."/>

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."/>

The agent's cube is oriented by the velocity and a grey little box is placed at the position of the next path corner.

## Agent reaching target Observer

An observable automaticaly fires when an agent reaches the destination (ie, is within radius of destination). The radius is by default the agent radius but it can be changed using `reachRadius` number propery in the `IAgentParameters` object.
If there are too many agents in the crowd trying to reach the same destination, a bottleneck can happen and few agents will reach destination. Be sure to properly set those values.
To add an observable, simply add your function:
```
var crowd = navigationPlugin.createCrowd(10, 0.1, scene);
...
crowd.onReachTargetObservable.add((agentInfos) => {
    console.log("agent reach destination: ", agentInfos.agentIndex);
});
```


Adding and removing obstacles

Prerequisites

Obstacles API