| # Unity Navigation (NavMesh, Pathfinding, AI) |
|
|
| ## Overview |
|
|
| Unity's AI Navigation package (`com.unity.ai.navigation`) bakes a |
| **NavMesh** -- a simplified walkable surface -- and provides |
| `NavMeshAgent` to move characters along it. This is the standard solution |
| for AI NPCs in the generated project. |
|
|
| ## Baking a NavMesh |
|
|
| 1. Mark static colliders as **Navigation Static** (Window > AI > |
| Navigation > Object). |
| 2. Bake the NavMesh (Window > AI > Navigation > Bake). |
| 3. At runtime, every `NavMeshAgent` on the scene automatically walks on |
| the baked NavMesh. |
|
|
| > For a procedurally generated city, baking at design time is impossible. |
| > Either: |
| > * Bake at runtime via `NavMeshSurface.BuildNavMesh()` (AI Navigation |
| > package), or |
| > * Use the simpler approach in `NPCController.cs`: pick random points via |
| > `NavMesh.SamplePosition` so the agent always lands on a valid walkable |
| > spot. |
|
|
| ## NavMeshAgent |
|
|
| ```csharp |
| [RequireComponent(typeof(NavMeshAgent))] |
| public class NPCController : MonoBehaviour |
| { |
| private NavMeshAgent _agent; |
| |
| private void Awake() => _agent = GetComponent<NavMeshAgent>(); |
| |
| private void Start() |
| { |
| PickNewDestination(); |
| } |
| |
| private void PickNewDestination() |
| { |
| Vector3 random = transform.position + Random.insideUnitSphere * 20f; |
| if (NavMesh.SamplePosition(random, out NavMeshHit hit, 20f, NavMesh.AllAreas)) |
| _agent.SetDestination(hit.position); |
| } |
| } |
| ``` |
|
|
| Key properties: |
|
|
| | Property | Meaning | |
| |---------------------|------------------------------------------------------------| |
| | `speed` | Max movement speed (m/s) | |
| | `angularSpeed` | Max turning speed (deg/s) | |
| | `acceleration` | How quickly the agent reaches `speed` | |
| | `stoppingDistance` | Distance at which the agent considers the destination reached | |
| | `autoBraking` | Whether to slow down near the destination | |
| | `isStopped` | Pause the agent without clearing the path | |
| | `remainingDistance` | Distance to the end of the current path | |
| | `pathPending` | True while a new path is still being computed | |
|
|
| ## State machines for AI |
|
|
| A common pattern is a small finite state machine: |
|
|
| ``` |
| Idle --(timer)--> Wander --(player in range)--> Chase |
| ^ | | |
| | (lost sight) +---------------------------------+ |
| +--------------------+ |
| ``` |
|
|
| The generated `NPCController.cs` implements exactly this pattern with three |
| states (`Idle`, `Wander`, `Chase`) and switch-based dispatch in `Update()`. |
|
|
| ## Pathfinding details |
|
|
| * `NavMeshAgent.SetDestination(target)` is async -- the path may not be |
| ready on the same frame. Check `!agent.pathPending` before reading |
| `remainingDistance`. |
| * `agent.pathStatus` tells you whether a path is `PathComplete`, |
| `PathPartial` or `PathInvalid`. |
| * `NavMesh.CalculatePath(source, target, mask, out path)` lets you compute a |
| path without an agent (useful for "can the NPC reach this point?" checks). |
|
|
| ## NavMeshObstacle |
|
|
| For dynamic obstacles (a car parked across a road, a door that closes), add |
| a `NavMeshObstacle` component. Set `carve = true` to actually cut a hole in |
| the NavMesh; otherwise the obstacle only pushes agents around. |
|
|
| ## Off-mesh links |
|
|
| When the walkable surface is disconnected (e.g. a gap between rooftops), |
| drop an `OffMeshLink` to let agents jump or teleport across. You can also |
| use them for ladders, climbing walls, and jumping down from ledges. |
|
|
| ## Performance |
|
|
| * Keep the agent count under ~100 simultaneous active agents on desktop. |
| * For larger crowds use the **ECS/DOTS navigation** solutions or batch |
| pathfinding across frames. |
| * Set `agent.autoRepath = false` if you do not need the agent to follow |
| moving targets, and call `SetDestination` less often (e.g. every 0.5 s). |
|
|
