Manual
Manual
Navmeshes
A navmesh is where agents can walk: the floors of a level, kept the agent's width from walls, with the steps it can climb and the slopes it can walk. This page covers the Nav Mesh Surface 3D, its twin for games seen from above in 2D, the Nav Mesh Surface 2D, agent types, baking a navmesh in the editor, shaping the bake with modifiers and volumes, and the .abynav file a bake writes.
Navigation
Navigation is the official package abyss.navigation, built on Recast & Detour 1.6.0. Install it from Window ▸ Package Manager (see Using packages).
It works in three steps:
- A Nav Mesh Surface 3D, or a Nav Mesh Surface 2D in 2D, says what a navmesh is made of, and for which kind of agent.
- You bake it in the editor, which writes the navmesh to a file beside the scene.
- While the game plays, agents walk it, and your code asks it for paths.
Navigation does not need Physics 3D or Physics 2D. With Physics 3D installed, a navmesh can also be baked from colliders; with Physics 2D, a navmesh in 2D leaves out what its colliders cover.
Nav Mesh Surface 3D
A Nav Mesh Surface 3D is baked into one navmesh, for one agent type, from what it collects. Put it on the entity at the top of a level, or on any entity in its scene.
| Field | What it does |
|---|---|
| Agent Type | Which agent type it is baked for, by name, as Project Settings ▸ Navigation lists them. Humanoid at first. |
| Geometry | What it is baked from: Meshes, what is drawn; Colliders, the colliders that stand still; or Both. Meshes at first. |
| Collect | Which entities: Children, this one and every one under it; or Scene, every entity of its scene. Children at first. |
| Layers | Only entities on these layers are baked. Every layer at first. |
| Baked | The navmesh file it was baked as. Bake fills it. |
Only active entities are baked, each where it is placed now. A navmesh for another agent type, such as a larger creature, is a second Nav Mesh Surface 3D, on another entity.
Baked from colliders
With Geometry on Colliders or Both, the bake asks Physics 3D for the colliders that stand still: those that are ground, and those on a Static body. Each box, sphere, capsule and mesh collider is taken as triangles, where its entity puts it. Triggers, and colliders on bodies that move, are left out.
Without Physics 3D installed, a surface baked from colliders says in the Logs panel that its colliders were left out.
Nav Mesh Surface 2D
A Nav Mesh Surface 2D is the navmesh of a game seen from above in 2D: its floor lies on the XY plane, and its agents walk across X and Y. Put it on the entity at the top of a level, such as the one that holds its Tilemaps.
| Field | What it does |
|---|---|
| Agent Type | Which agent type it is baked for, by name. Humanoid at first. |
| Collect | Which entities: Children, this one and every one under it; or Scene, every entity of its scene. Children at first. |
| Layers | Only entities on these layers are baked. Every layer at first. |
| Size | The floor's width and height about its entity, in the entity's units, where it collects no Tilemap. 10 by 10 at first. |
| Baked | The navmesh file it was baked as. Bake fills it. |
A bake in 2D makes the floor, then cuts out what stands on it:
- The floor is every cell painted on the Tilemaps it collects, whatever the tile. Where it collects no Tilemap, the floor is the rectangle of its Size about its entity, so a level drawn with sprites alone has a floor too.
- Walls from tiles: where a Tilemap has a Tilemap Collider 2D that stands still and is no trigger, its Solid tiles are cut out of the floor as the collider meets them, each by its shape: the whole cell, its traced art, or the shapes drawn on it. Its None and One-Way tiles stay floor.
- Other colliders: each box, circle, capsule, polygon and edge collider that stands still, as ground or on a Static body, cuts its shape out of the floor. Triggers, and colliders on bodies that move, are left out.
So a level is usually a floor Tilemap painted under everything and a walls Tilemap with a Tilemap Collider 2D. Without Physics 2D installed nothing is cut out, and every cell painted is floor.
Agent types are the same in 2D, in the game's units: where a tile is a unit across, a Humanoid keeps half a tile from each wall. Give a 2D game an agent type of its own sizes in Project Settings ▸ Navigation. A navmesh in 2D is drawn flat on the XY plane, see-through over the level's tiles and sprites.
Agent types
Edit ▸ Project Settings ▸ Navigation lists the kinds of agent navmeshes are baked for, up to eight, under Agent Types. Each is what decides where an agent of that kind can go.
| Field | What it does |
|---|---|
| Name | What it is called, as a surface's and an agent's Agent Type list it. |
| Radius | How far from a wall it keeps, in meters: half its width. |
| Height | How tall it is, in meters: the room it needs above the floor. |
| Step Height | The tallest step it walks up, in meters. |
| Max Slope | The steepest slope it walks, in degrees, up to 89. |
Every project starts with Humanoid: a radius of 0.5, a height of 2, a step of 0.4 and a slope of 45 degrees. The settings are saved in settings/navigation.json, beside the areas of floor.
Bake a navmesh
Save the scene first: the navmesh is written beside it. Then bake in either of two places:
- Right-click the Nav Mesh Surface 3D's or 2D's header in the Inspector and choose Bake.
- Window ▸ Navigation ▸ Navigation opens the Navigation window, which lists every surface. Bake All bakes them all, and Bake Selected the ones picked.
The Logs panel says what each bake made, such as Navigation: Ground baked for Humanoid, 30 polygons from 260 triangles, in scenes/Level1/Ground.abynav., or why it could not bake: a scene never saved, a scene outside the project's assets, or nothing to walk on, no mesh or collider on the surface's layers. A surface in 2D says how many Tilemaps it was baked from, or that it was baked from its Size.
Each bake is one step of the undo. Bake again whenever the level changes: the navmesh does not follow the scene by itself.
The Navigation window
| Part | What it does |
|---|---|
| Show Nav Mesh | Draws every navmesh in the Scene view while the window is open, with every link and volume. On at first. |
| Show Agents | Draws every agent, with the path it walks, and every obstacle. Off at first. |
| Surfaces | A row for each Nav Mesh Surface 3D and 2D in the open scenes: its name, its agent type, and how many polygons it was baked as, or not baked. Click a row to pick the surface. |
| Bake Selected | Bakes the surfaces picked. Shown while one of them is. |
| Bake All | Bakes every surface. |
| Clear All | Has every surface name no bake. |
The window remembers Show Nav Mesh and Show Agents for you. A picked surface's navmesh is drawn either way, see-through blue with the edges of its polygons, a little above the floor it lies on, and each area of floor in its own color.
The navmesh file
A bake writes an .abynav file in a folder beside the scene, named as the scene is, under the surface's name: the surface Ground of scenes/Level1.scene is baked as scenes/Level1/Ground.abynav. When another surface's file has that name already, the new one is Ground 2.abynav.
Baking again writes the same file in its place, so it keeps its identity. The surface's Baked names the file; that is the step the undo takes back, while the file stays as it was written.
Clear, on the surface's right-click menu, has the surface name no bake. The file stays among your assets, and the next bake writes it again.
A navmesh is loaded as its surface appears, both while you edit and while the game plays, and let go of as the surface goes or is cleared. A built game carries each file a scene's surface names, and loads it the same way.
A navmesh is made of tiles, 64 cells across. A cell is a third of the agent's radius, so a Humanoid's tile is about 10.7 meters across. A level hundreds of meters across is baked whole, and an obstacle that cuts into the navmesh rebuilds only the tiles it covers. A file from an older version of Navigation, made before navmeshes were tiles, says in the Logs panel that it needs baking again.
Islands of floor smaller than two square meters, such as the top of a table, are left out of a bake.
Nav Mesh Modifier 3D
A Nav Mesh Modifier 3D changes how its entity's meshes and colliders are baked, and those under it.
| Field | What it does |
|---|---|
| Leave Out | Leaves its meshes and colliders out of the bake: neither floor nor wall, as a bush agents walk through. |
| Area | The area their floor is baked as, by name. Walkable at first. Not Walkable makes them a wall however flat they are. |
| Apply To Children | Whether the entities under it are changed too, rather than its own alone. On at first. |
The nearest one counts: an entity's own, or else the nearest above it that applies to its children. Use it to make a road cheaper to walk, a swamp dearer, or a flat roof no agent should stand on Not Walkable.
Nav Mesh Modifier Volume 3D
A Nav Mesh Modifier Volume 3D is a box whose floor is an area when the navmesh is baked: a pond painted onto one large terrain, a strip of mud, a spot no agent goes. It is turned and scaled as its entity is, and is baked into the navmesh of each surface that collects its entity.
| Field | What it does |
|---|---|
| Center | Its middle, in its entity's own units. |
| Size | How big it is along each of its entity's axes. 2 each way at first. |
| Area | The area the floor within it is baked as, by name. Not Walkable at first, which cuts the floor out. |
The box counts as seen from above: a box tipped over makes an area of whatever it covers from above. Where boxes overlap, Not Walkable wins, then the one baked later. A Not Walkable box keeps agents its radius away, as a wall does.
Edit Volume, the button in its section, puts a dot in the middle of each face in the Scene view. Drag one to move that face while the far one stays, or hold Alt to keep the middle where it is; hold Ctrl to snap it to the Move tool's step. A picked box is drawn as its edges in its area's color, red for Not Walkable.
Things to know
- A navmesh stays where it was baked. It is in the world's units, so a surface moved, turned, or placed elsewhere in a prefab still answers for where it was. Bake again after moving it.
- Navmeshes are baked in the editor only. A level your game generates as it plays has no navmesh for its agents.
In the Scripting API
- NavMeshSurface3D: what a navmesh is baked from, with NavMeshGeometry3D and NavMeshCollect3D.
- NavMeshModifier3D and NavMeshModifierVolume3D: areas, and what the bake leaves out.
- NavigationSettings and NavAgentType3D: the agent types navmeshes are baked for.
- Navigation3D: the navmeshes loaded, asked for paths.
- NavMeshSurface2D, with NavMeshCollect2D, and Navigation2D: the same in 2D.
- IStaticGeometry2D: what a physics package gives a bake in 2D of the colliders that stand still.
- NavMeshFile: the
.abynavfile.
