
## OffMeshConnections aka Teleports

Off-mesh connections allow agents to traverse between arbitrary points in the world, outside the standard walkable surfaces of a navmesh.  
Typical use cases include **jumping across gaps, climbing ladders, or teleporting through portals/doors**.

### OffMeshConnectionParams

| Name            | Type      | Required | Description                                                   | Default |
| --------------- | --------- | -------- | ------------------------------------------------------------- | ------- |
| `startPosition` | `Vector3` | ✔        | World-space start position of the connection.                 | –       |
| `endPosition`   | `Vector3` | ✔        | World-space end position of the connection.                   | –       |
| `radius`        | `number`  | ✔        | Radius of the connection in world units.                      | –       |
| `bidirectional` | `boolean` | ✔        | Whether the connection can be traversed in both directions.   | –       |
| `area`          | `number`  | ✖        | Area type of the connection (e.g. ground, water, door).       | `0`     |
| `flags`         | `number`  | ✖        | Flags associated with the connection (e.g. walk, swim, jump). | `1`     |
| `userId`        | `number`  | ✖        | Optional user-defined identifier for the connection.          | –       |

#### Example

The following example adds an **off-mesh jump connection** between two platforms:

```ts
const jumpConnection: OffMeshConnectionParams = {
  startPosition: new Vector3(0, 1, 0), // platform A
  endPosition: new Vector3(5, 1, 0), // platform B
  radius: 0.5, // connection width
  bidirectional: true, // can jump both ways
  area: 0, // default area type
  flags: 1, // default walkable flag
  userId: 42, // optional identifier
};

const navmeshParameters = {
  cs: 0.5,
  ch: 0.5,
  // etc
  offMeshConnections: [jumpConnection],
};

const { navMesh, navMeshQuery } = await navigationPlugin.createNavMeshAsync([staticMesh], navmeshParameters);
```



## TileCache

In short `TileCache` is an extension of the navmesh system that allows dynamic updates of the navigation mesh in smaller regions (tiles) instead of rebuilding the whole mesh.

If you alter the `TileCache`, you need to wait until it is fully updated. Use this function:

```ts
WaitForFullTileCacheUpdate(navMesh: NavMesh, tileCache: TileCache)
```

If you are altering multiple obstacles at once, set `doNotWaitForCacheUpdate = true` and call `WaitForFullTileCacheUpdate(navMesh: NavMesh, tileCache: TileCache)` at the end of the batch operation. If it is set to `false`, every obstacle operation returns only after the `TileCache` has been fully updated.

_Note: If you are not dealing with many obstacle updates, you can wait for the `TileCache` update in the render loop._

## TileCacheMeshProcess

`tileCacheMeshProcess` is a callback function used in Recast’s tile cache system.

**Its purpose:**

- During tile cache generation, each tile is processed into polygons (the navmesh).
- tileCacheMeshProcess allows you to customize each polygon’s properties, such as:
  - polyAreas → the type of area (e.g., walkable, road, stairs).
  - polyFlags → flags used by agents/queries for filtering or cost calculations.

Think of it as a hook for assigning areas and flags per polygon, giving you control over which parts of the navmesh different agents can traverse.

Using `navMeshCreateParams` you can access all information you might need about the `polys` being processed.

[Read more about TileCache and TileCacheMeshProcess, and check the list of available NavMeshCreateParams functions](../v2TileCache)

Example:

```ts
const tileCacheMeshProcess: TileCacheMeshProcess = (navMeshCreateParams: NavMeshCreateParams, polyAreas: UnsignedCharArray, polyFlags: UnsignedShortArray) => {
  const STAIRS_AREA = 1;
  const DEFAULT_AREA = 0;
  const WALK_FLAG = 1;
  const STAIRS_FLAG = 2;

  const vertsCount = navMeshCreateParams.vertCount();
  const indicesCount = navMeshCreateParams.polyCount() * 3;

  for (let i = 0; i < polyAreas.length; i++) {
    // compute average y of polygon vertices
    const idx0 = navMeshCreateParams.polys(i * 3 + 0);
    const idx1 = navMeshCreateParams.polys(i * 3 + 1);
    const idx2 = navMeshCreateParams.polys(i * 3 + 2);

    const avgY = (navMeshCreateParams.verts(idx0 * 3 + 1) + navMeshCreateParams.verts(idx1 * 3 + 1) + navMeshCreateParams.verts(idx2 * 3 + 1)) / 3;

    if (avgY > 1.5) {
      polyAreas[i] = STAIRS_AREA;
      polyFlags[i] = STAIRS_FLAG;
    } else {
      polyAreas[i] = DEFAULT_AREA;
      polyFlags[i] = WALK_FLAG;
    }
  }
};

// Use when creating navmesh
navigationPlugin.createNavMesh(meshes, {
  maxObstacles: 64,
  expectedLayersPerTile: 2,
  tileCacheMeshProcess,
});
```

## List of available functions in NavMeshCreateParams used with TileCacheMeshProcess

```ts
setPolyMeshCreateParams(polyMesh: RecastPolyMesh): void;
setPolyMeshDetailCreateParams(polyMeshDetail: RecastPolyMeshDetail): void;
setOffMeshConnections(offMeshConnections: OffMeshConnectionParams[]): void;
verts(index: number): number;
setVerts(index: number, value: number): void;
vertCount(): number;
polys(index: number): number;
setPolys(index: number, value: number): void;
polyAreas(index: number): number;
setPolyAreas(index: number, value: number): void;
polyFlags(index: number): number;
setPolyFlags(index: number, value: number): void;
polyCount(): number;
nvp(): number;
setNvp(value: number): void;
detailMeshes(index: number): number;
setDetailMeshes(index: number, value: number): void;
detailVerts(index: number): number;
setDetailVerts(index: number, value: number): void;
detailVertsCount(): number;
detailTris(index: number): number;
setDetailTris(index: number, value: number): void;
detailTriCount(): number;
offMeshConVerts(index: number): number;
offMeshConRad(index: number): number;
offMeshConDir(index: number): number;
offMeshConAreas(index: number): number;
offMeshConFlags(index: number): number;
offMeshConUserID(index: number): number;
offMeshConCount(): number;
userId(): number;
tileX(): number;
setTileX(value: number): void;
tileY(): number;
setTileY(value: number): void;
tileLayer(): number;
setTileLayer(value: number): void;
boundsMin(): Vector3Tuple;
setBoundsMin(value: Vector3Tuple): void;
boundsMax(): Vector3Tuple;
setBoundsMax(value: Vector3Tuple): void;
walkableHeight(): number;
setWalkableHeight(value: number): void;
walkableRadius(): number;
setWalkableRadius(value: number): void;
walkableClimb(): number;
setWalkableClimb(value: number): void;
cellSize(): number;
setCellSize(value: number): void;
cellHeight(): number;
setCellHeight(value: number): void;
buildBvTree(): boolean;
setBuildBvTree(value: boolean): void;
```

_For detailed information, refer to the `recast-navigation-js` docs._



## The options Parameter (per-query)

Most plugin query functions accept an optional options object to pass query-specific settings down to Recast/Detour. Common properties include:

```ts
options?: {
filter?: QueryFilter;
halfExtents?: IVector3Like;
// optionally other request-specific params depending on the function
}
```

Use this to apply different filter rules per agent or query and to control search-area extents.

### QueryFilter

`QueryFilter` controls which polygons on the navmesh are considered during a path query. It's the primary tool for customizing walkability per agent or per situation.

**Common properties**

```ts
interface QueryFilter {
  includeFlags?: number; // bitmask: polygons that must include at least one of these flags
  excludeFlags?: number; // bitmask: polygons that must NOT include any of these flags
  areaCost?: number[]; // areaCost[areaId] = traversal cost multiplier for that area
}
```

**How it works**

`includeFlags`/`excludeFlags` filter polygons by flag bits assigned when the navmesh was generated (via `tileCacheMeshProcess` or default config).

`areaCost` adjusts the traversal cost for polygons with a given area id — higher cost discourages the pathfinder from using that area unless needed.

## Examples

Pedestrian who avoids roads and prefers sidewalks:

```ts
const pedestrianFilter: QueryFilter = {
  includeFlags: 0x0001, // only polygons flagged as "walkable_for_pedestrian"
  excludeFlags: 0x0004, // exclude "road" polygons
  areaCost: [1.0, 2.0, 5.0], // index = area id; higher = more expensive
};

const path = navigationPlugin.findPath(start, end, { filter: pedestrianFilter });
```

Vehicle that only uses "road" polygons:

```ts
const vehicleFilter: QueryFilter = {
  includeFlags: 0x0004, // road flag
  areaCost: [1.0, 1.0, 1.0],
};

const drivePath = navigationPlugin.findPath(vehicleStart, vehicleEnd, { filter: vehicleFilter });
```

### Notes

`areaCost` length should cover the highest area id used in your mesh. Missing entries are treated as cost `1.0`.

Flags and areas are assigned when mesh polygons are processed during build time — use `tileCacheMeshProcess` to control those assignments.


Name	Type	Required	Description	Default
`startPosition`	`Vector3`	✔	World-space start position of the connection.	–
`endPosition`	`Vector3`	✔	World-space end position of the connection.	–
`radius`	`number`	✔	Radius of the connection in world units.	–
`bidirectional`	`boolean`	✔	Whether the connection can be traversed in both directions.	–
`area`	`number`	✖	Area type of the connection (e.g. ground, water, door).	`0`
`flags`	`number`	✖	Flags associated with the connection (e.g. walk, swim, jump).	`1`
`userId`	`number`	✖	Optional user-defined identifier for the connection.	–