Determine what the user needs and guide them through navigation setup. See navigation-system.md for expanded component details, API notes, code recipes, and troubleshooting.
Passing C# to eval
eval compiles a statement block, not a file. Two consequences, both of which cause a
compile error rather than a warning:
- No
using directives. The compiler reads using UnityEngine; as a resource-disposal
statement and rejects it (CS0210).
- Types must be fully qualified. A bare
AssetDatabase or Volume does not resolve
(CS0246 / CS0103), and a bare Object is ambiguous with object (CS0104).
Where a snippet below is written as a file — with usings, for readability, or because it is
meant to be saved into the project — qualify the types before passing it to eval.
Routing Logic
| User Says |
Interpretation |
| "add navigation" / "set up nav" |
Full setup: NavMeshSurface + bake + NavMeshAgent |
| "make this character navigate" |
Add NavMeshAgent, ensure NavMesh exists |
| "add pathfinding" |
NavMeshAgent + movement script |
| "agent won't move" / "path not found" |
Troubleshoot — see Troubleshooting Decision Tree in reference |
| "avoid obstacles" |
NavMeshObstacle with carving or avoidance |
| "connect two areas" / "jump across" |
NavMeshLink between areas |
| "patrol between points" |
NavMeshAgent + patrol script |
| "click to move" |
NavMeshAgent + raycast click-to-move script |
| "animate the character while navigating" |
Couple Animator with NavMeshAgent |
| "different agent sizes" |
Configure agent types in Navigation window |
| "areas and costs" / "restrict areas" |
NavMesh area types, modifiers, and agent area masks |
Workflow
0. Package Installation Check
Before doing anything else, verify that com.unity.ai.navigation is installed. If it's missing,
add it to Packages/manifest.json under dependencies — Unity resolves it when the Editor next
regains focus, and this needs no Editor connection:
"com.unity.ai.navigation": "<current 2.x version>"
Don't invent the version string. Read the current one from the Unity registry —
https://packages.unity.com/com.unity.ai.navigation lists every published version — or copy the version an
adjacent Unity package in this manifest already uses. A version that doesn't exist makes
Unity fail resolution silently, so a wrong guess looks like nothing happened.
Proceed only once it's confirmed installed. If you have a live Editor to run C# in, see
navigation-system.md for the Client.Add equivalent.
1. Pre-Flight: Assess Current Navigation Setup
Before making changes, inspect what already exists:
- Find the existing navigation components. With a connected Editor, query the live scene for
NavMeshSurface, NavMeshAgent, NavMeshObstacle, NavMeshLink and NavMeshModifier — see
the unity-cli skill for driving a running Editor. Without one, search the scene and prefab
files for those component names.
- Check configured agent types via Window > AI > Navigation > Agents tab.
- Summarize ALL detected navigation components before proposing changes.
2. Gather Missing Information
Before creating components, ensure the user has specified: walkable surfaces, agent type/size, agent behavior, obstacles, links, and area/cost requirements. Ask if anything is unclear. See the Information Gathering Checklist in the reference for full details.
3. Planning & Execution
Follow this general order. See the Component Setup Guide in the reference for detailed step-by-step instructions per component:
- NavMesh Surface — create the walkable mesh (bake it)
- NavMesh Agent — add pathfinding characters
- NavMesh Obstacle — add dynamic obstacles
- NavMesh Link — connect disconnected NavMesh areas
- NavMesh Modifier / Modifier Volume — fine-tune area types
- Scripts — movement, patrol, click-to-move, animation coupling (see Common Recipes in reference)
4. Validation
After setup, confirm:
- NavMesh is baked and visible (blue overlay)
- NavMeshSurface agent type matches NavMeshAgent agent type
- Agents have a valid path to their destination
- Obstacles carve or obstruct correctly
- Links have both ends connected and Activated is enabled
- Area masks allow the intended movement
- No conflicting components (see Mixing Components Guide in reference)
- If using Rigidbody with NavMeshAgent, Is Kinematic is enabled
5. Final Confirmation
Summarize what was created or changed:
- NavMesh Surfaces: which GameObject, agent type, geometry mode, bake status
- NavMesh Agent(s): which GameObject, speed, stopping distance, area mask
- NavMesh Obstacle(s): which GameObject, shape, carve on/off
- NavMesh Link(s): start/end, bidirectional, area type
- Scripts: which scripts attached to which GameObjects
- Any manual steps required (adjust waypoints, re-bake after scene changes, etc.)
1---
2name: initialize-ai-navigation
3description: Sets up and configures the Unity AI Navigation system — NavMesh surfaces, NavMesh agents, obstacles, links, modifiers, areas and costs. Use when creating walkable navigation meshes, adding pathfinding agents, setting up patrol routes, configuring obstacle avoidance and carving, connecting separate NavMeshes with links, coupling navigation with animation, or troubleshooting navigation issues.
4metadata:
5 source: https://skillmd.com/skills/gabrielmoreira/initialize-ai-navigation
6---
7
8Determine what the user needs and guide them through navigation setup. See [navigation-system.md](references/navigation-system.md) for expanded component details, API notes, code recipes, and troubleshooting.
9
10### Passing C# to `eval`
11
12`eval` compiles a **statement block, not a file**. Two consequences, both of which cause a
13compile error rather than a warning:
14
15- **No `using` directives.** The compiler reads `using UnityEngine;` as a resource-disposal
16 statement and rejects it (`CS0210`).
17- **Types must be fully qualified.** A bare `AssetDatabase` or `Volume` does not resolve
18 (`CS0246` / `CS0103`), and a bare `Object` is ambiguous with `object` (`CS0104`).
19
20Where a snippet below is written as a file — with usings, for readability, or because it is
21meant to be saved into the project — qualify the types before passing it to `eval`.
22
23## Routing Logic
24
25| User Says | Interpretation |
26|-----------|---------------|
27| "add navigation" / "set up nav" | Full setup: NavMeshSurface + bake + NavMeshAgent |
28| "make this character navigate" | Add NavMeshAgent, ensure NavMesh exists |
29| "add pathfinding" | NavMeshAgent + movement script |
30| "agent won't move" / "path not found" | Troubleshoot — see Troubleshooting Decision Tree in reference |
31| "avoid obstacles" | NavMeshObstacle with carving or avoidance |
32| "connect two areas" / "jump across" | NavMeshLink between areas |
33| "patrol between points" | NavMeshAgent + patrol script |
34| "click to move" | NavMeshAgent + raycast click-to-move script |
35| "animate the character while navigating" | Couple Animator with NavMeshAgent |
36| "different agent sizes" | Configure agent types in Navigation window |
37| "areas and costs" / "restrict areas" | NavMesh area types, modifiers, and agent area masks |
38
39## Workflow
40
41### 0. Package Installation Check
42Before doing anything else, verify that `com.unity.ai.navigation` is installed. If it's missing,
43add it to `Packages/manifest.json` under `dependencies` — Unity resolves it when the Editor next
44regains focus, and this needs no Editor connection:
45
46```json
47"com.unity.ai.navigation": "<current 2.x version>"
48```
49
50Don't invent the version string. Read the current one from the Unity registry —
51`https://packages.unity.com/com.unity.ai.navigation` lists every published version — or copy the version an
52adjacent Unity package in this manifest already uses. A version that doesn't exist makes
53Unity fail resolution **silently**, so a wrong guess looks like nothing happened.
54
55Proceed only once it's confirmed installed. If you have a live Editor to run C# in, see
56[navigation-system.md](references/navigation-system.md) for the `Client.Add` equivalent.
57
58### 1. Pre-Flight: Assess Current Navigation Setup
59Before making changes, inspect what already exists:
601. Find the existing navigation components. With a connected Editor, query the live scene for
61 `NavMeshSurface`, `NavMeshAgent`, `NavMeshObstacle`, `NavMeshLink` and `NavMeshModifier` — see
62 the `unity-cli` skill for driving a running Editor. Without one, search the scene and prefab
63 files for those component names.
642. Check configured agent types via **Window > AI > Navigation > Agents tab**.
653. Summarize ALL detected navigation components before proposing changes.
66
67### 2. Gather Missing Information
68Before creating components, ensure the user has specified: walkable surfaces, agent type/size, agent behavior, obstacles, links, and area/cost requirements. Ask if anything is unclear. See the Information Gathering Checklist in the reference for full details.
69
70### 3. Planning & Execution
71Follow this general order. See the Component Setup Guide in the reference for detailed step-by-step instructions per component:
721. **NavMesh Surface** — create the walkable mesh (bake it)
732. **NavMesh Agent** — add pathfinding characters
743. **NavMesh Obstacle** — add dynamic obstacles
754. **NavMesh Link** — connect disconnected NavMesh areas
765. **NavMesh Modifier / Modifier Volume** — fine-tune area types
776. **Scripts** — movement, patrol, click-to-move, animation coupling (see Common Recipes in reference)
78
79### 4. Validation
80After setup, confirm:
81- NavMesh is baked and visible (blue overlay)
82- NavMeshSurface agent type matches NavMeshAgent agent type
83- Agents have a valid path to their destination
84- Obstacles carve or obstruct correctly
85- Links have both ends connected and Activated is enabled
86- Area masks allow the intended movement
87- No conflicting components (see Mixing Components Guide in reference)
88- If using Rigidbody with NavMeshAgent, Is Kinematic is enabled
89
90### 5. Final Confirmation
91Summarize what was created or changed:
92- NavMesh Surfaces: which GameObject, agent type, geometry mode, bake status
93- NavMesh Agent(s): which GameObject, speed, stopping distance, area mask
94- NavMesh Obstacle(s): which GameObject, shape, carve on/off
95- NavMesh Link(s): start/end, bidirectional, area type
96- Scripts: which scripts attached to which GameObjects
97- Any manual steps required (adjust waypoints, re-bake after scene changes, etc.)