---
name: ferret-ai-navigation
description: Use for NPC movement and behaviour in Ferret: NavService (NavMesh build or load, path and point queries), NavAgent in the crowd, Roam, Follow, Attention, BehaviorTree. Read when NPCs do not path, get stuck, or must stop and face the player.
---

# AI and navigation

## When to use
Walking NPCs, following the player, stopping to talk, behaviour trees.

## The model
`NavService` builds or loads a NavMesh (recast-navigation as WebAssembly, loaded once by `initNavigation`) and answers path and point queries. `NavAgent` moves an entity over it in the crowd. Ready behaviours: `Roam` (random points near home), `Follow`, `Attention` (stop and face a player who comes near). `BehaviorTree` (`bt`, `BTNode`, `Blackboard`) is there for more.

## Steps
1. `await initNavigation()` once, then create `NavService` with the level's geometry (`collectGeometry`) or `navmesh.bin`.
2. Give the level's manifest a `navmesh` file or `navBuild` settings; rebuild with the editor command `edit.navmesh.rebuild` after geometry changes.
3. Add `NavAgent` plus a behaviour to the entity (by name in the manifest).
4. Over a ledge or an explosion impulse the agent switches to a falling mode and lands back on the mesh.

## Check afterwards
A path query between two spawn points is non-empty; agents reach targets headless in a few simulated seconds; `Attention` stops an NPC when the player is near.

## What usually goes wrong
- No NavMesh: `navmesh.bin` missing and no `navBuild`.
- Agent radius or height in `navBuild` too big for doorways.
- Calling queries before `initNavigation` finished.
- Terrain that changes (digging): the mesh must follow, see `ferret-physics-terrain`.

## Files

- `reference/packages.md` — Characters, animation graphs, NPC navigation, interactables, zones and transformations.
- `reference/api-ai.md` — every export of `@ferret/ai` with signature and doc comment