AI and navigation

Skill ferret-ai-navigation · download all skills · SKILL.md

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