Manual
Manual
Links and areas
A link is a way across what the navmesh cannot walk: a gap to jump, a ledge to drop off or climb, a ladder. An area is a kind of floor, such as a road, mud or water, with what a meter of it costs to walk. This page covers the Nav Mesh Link 3D and its twin in 2D, how agents cross links, the areas of Project Settings ▸ Navigation and their costs, and the area masks that say which areas an agent may walk.
Nav Mesh Link 3D
A Nav Mesh Link 3D is a way from its Start to its End. It is baked into the navmesh of each surface that collects its entity, so a path is planned across it as across a floor. Bake again after you place or move a link.
| Field | What it does |
|---|---|
| Start | Where it starts, in its entity's own units: on the navmesh, or near it. A meter behind the entity at first. |
| End | Where it ends, in its entity's own units. A meter in front of the entity at first. |
| Width | How wide it is, in meters: links side by side across it, an agent's width apart, so a crowd crosses a wide gap abreast. 0 for one link. |
| Both Ways | Whether it is crossed from its end to its start too, rather than one way only. On at first. |
| Area | The area it counts as, by name: what crossing it costs, and which agents may. Walkable at first. Not Walkable leaves it out of the bake. |
Each end must lie on the navmesh, or within the agent's radius of it across and its step up or down. An end farther away joins nothing, and the link is never crossed.
Edit Link, the button in its section, gives Start and End each a Move handle in the Scene view. A picked link is drawn from its start to its end, in an arc where they differ in height, with a ring at each end the first agent type's width across, a line across each end as wide as Width, and an arrowhead at its end where it goes one way only. It is light cyan for Walkable, or its area's color. The Navigation window's Show Nav Mesh draws every link.
Nav Mesh Link 2D
A Nav Mesh Link 2D is the same for a navmesh in 2D: a way from its Start to its End on the XY plane, a unit left and right of its entity at first, across a river or through a hole in a fence. Its fields are the 3D one's; Width is in the game's units. Edit Link gives its two ends dots to drag in the Scene view, and a picked link is drawn as a line with a ring at each end. An agent in 2D crosses it straight, with OnLink and LinkProgress as below.
Crossing a link
An agent crosses a link by itself. It walks to the link's start, then across at its Speed:
- in a jump, an arc, where the ends differ in height by more than its agent type's Step Height, or where no floor lies between them. The top of the arc is above the higher end by a quarter of the distance across, between a quarter of a meter and a meter and a half;
- in a straight walk otherwise.
While it crosses, its OnLink is true and its LinkProgress goes from 0 to 1, for an animator to play a jump by. Once across, it walks on to where it was sent.
Cross a link from your own code
Turn Auto Traverse off on the agent for links your game moves it across itself, such as a ladder it climbs. As the agent comes to a link, it stops a step or two from its start and waits, with OnLink true and the link's ends in LinkStart and LinkEnd. Your system moves the entity across, then sets OnLink back to false, and the agent walks on from where its entity is.
This one climbs the agent from where it waits to the link's end, at a meter and a half a second, for an agent with no parent and a Base Offset of 0:
// In a plugin's Build:ComponentType<NavMeshAgent3D> agents = world.Component<NavMeshAgent3D>();schedule.Add("Climb ladders", [agents.Write(), world.Transform().Write()], context =>{ float climb = 1.5f * context.DeltaTime; foreach (Chunk chunk in context.Chunks) { Span<NavMeshAgent3D> walkers = chunk.GetSpan<NavMeshAgent3D>(0); Span<Transform> transforms = chunk.GetSpan<Transform>(1); for (int row = 0; row < walkers.Length; row++) { ref NavMeshAgent3D agent = ref walkers[row]; if (!agent.OnLink || agent.AutoTraverse) { continue; }
ref Transform transform = ref transforms[row]; Vector3 at = new(transform.TranslationX, transform.TranslationY, transform.TranslationZ); Vector3 left = agent.LinkEnd - at; Vector3 next = left.Length() <= climb ? agent.LinkEnd : at + (Vector3.Normalize(left) * climb); (transform.TranslationX, transform.TranslationY, transform.TranslationZ) = (next.X, next.Y, next.Z); if (next == agent.LinkEnd) { agent.OnLink = false; // across: the agent walks on from here } } }});While it waits, the agent leaves its entity where your code puts it.
Areas
Edit ▸ Project Settings ▸ Navigation lists the kinds of floor under Areas. Two are always there: Walkable, any floor flat enough, at a cost of 1 a meter; and Not Walkable, a wall however flat it is. After them come up to sixteen of the project's own, each with:
| Field | What it does |
|---|---|
| Name | What it is called, as an Area and an Area Mask list it. |
| Cost | What a meter of it costs to walk, against Walkable's 1. |
| Color | What it is drawn in on the navmesh, in the Scene view. |
Every project starts with one of its own, Jump, at a cost of 2, drawn orange, for links that are jumped.
A path takes whatever costs least. Water at a cost of 3 is crossed only where going around is more than three times as long, and a road at 0.5 draws agents onto it. A change of cost applies at once to every navmesh loaded, with no bake; a change of which floor is which area needs one.
Give a floor an area
A floor gets its area as the navmesh is baked:
- From what it is baked from: a Nav Mesh Modifier 3D gives its entity's meshes and colliders an area, and those under it.
- From a box: a Nav Mesh Modifier Volume 3D makes the floor within it an area, such as a pond on one large terrain.
- A link counts as its own Area.
Everything else is Walkable. Where a floor of one of the project's own areas and a Walkable floor meet in the same place, the project's own wins.
Area masks
An agent walks only the areas its Area Mask ticks: Everything at first. The mask lists Walkable and each of the project's own areas by name, with Nothing and Everything above them; Not Walkable is never walked, so it is not listed. An agent whose mask leaves out Water walks round the pond, while one beside it walks straight across. The mask covers links too: an agent never crosses a link of an area its mask leaves out.
In code, a mask is an int with a bit for each area: bit 0 for Walkable, bit 1 for the first of the project's own areas, bit 2 for the second, and so on; −1 is every area.
NavPath3D dry = navigation.FindPath(from, to, areaMask: 1); // Walkable aloneagent.AreaMask = 1 | (1 << 2); // Walkable and the project's second areaA mask tells sixteen areas apart: Walkable and the first fifteen of the project's own. The sixteenth of the project's own is walked or not as Walkable is, though it keeps its own cost.
In the Scripting API
- NavMeshLink3D: a way across what the navmesh cannot walk, and NavMeshLink2D in 2D.
- NavMeshAgent3D: its Area Mask, Auto Traverse and what it says as it crosses a link.
- NavigationSettings and NavArea3D: the areas and their costs.
- Navigation3D: paths found across the areas a mask ticks.
