[This is preliminary documentation and is subject to change.]
The first thing to understand about CAINav is that it is not a plug-and-play solution. Well, NMGen in Unity is plug-and-play. But creating the navigation mesh is just the starting point. To use the navigation mesh you'll need to implement your own code. And to do that you'll need to understand CAINav's structure.
All core features of CAINav can be used in .NET-only applications. But there are many ease-of use extensions available for use only in Unity Pro. Any library or namespace containing 'u3d' are Unity-only.
Core features: Elements (classes, interfaces, etc.) that provide the core features. They are part of the .NET API and are available for use by all users.
Common extensions: Elements that provide ease-of-use features for all users.
Unity extensions: Elements that provide ease-of-use features specific to Unity users.
The 10,000 Meter View
The below diagram shows the relationships of the core components from a construction/build perspective.
1 - Input Data
As a minimum you have to have some sort of source geometry from which you can obtain vertex and triangle data. In Unity, the source geometry is usually obtained from MeshFilters and Terrain objects. But anything that provides vertices and triangles can be used.
For more complex builds you may also need to provide other data such as off-mesh connections and custom build processors.
The Unity extensions implement a flexible and extensible input build process that helps gather everyting together for you.
Triangle wrap direction on the xz-plane is used for the detection of which face of the triangle is considered up. The y-axis is up/down. A picture is worth a thousand words. If your source geometry is wrapped differently than shown, then it will need to be translated into this format before use in the NMGen build process.
CAINav uses the OpenGL coordinate system.
2 - NMGen Configuration
Source geometry may represent exterior natural geography or interior environments in any number of different styles. The navigation clients may be human-type agents, vehicles, wheeled robots, etc.; each with its own locomotion restrictions. For these reasons NMGen supports a large variety of configuration settings that adjust how the navigation mesh data is generated.
3 - Polygon and Detail Meshes
The input data and NMGen configuration are used to create two types of meshes. The polygon mesh provides the data needed for pathfinding operations. The optional detail mesh provides extra height detail helpful for certain position queries. (Better height position at a higher memory cost.) Together, these meshes provide the core structural data for the navigation mesh.
4 - Off-Mesh Connections
In some cases there are special travel routes not based on the surface of the source geometry. For example, an agent may be able to vault over a railing. Off-mesh connections can be used to represent these routes and are connected to the navigation mesh as a single edge.
Common Extensions: ConnectionSet
5 - Navigation Mesh Tiles
Tiles contain the data that makes up the navigation mesh. A navigation mesh cannot exist without at least one tile. The ability to have multiple tiles in a navigation mesh opens up a huge variety of options. Think: Navigation meshes that cover large or complex areas, swapping tiles in and out at runtime.
As a minimum, each tile contains a polygon mesh. It can also contain optional data such as a detail mesh and off-mesh connections.
6 - Navigation Mesh
A navigation mesh may contain a single rectangle tile, or a grid of square tiles. It is compact and efficient with various methods of serializing, de-serializing, and swapping data in and out at runtime.
Core Class: Navmesh
7 - Navigation Mesh Query
The navigation mesh query is what all clients use to perform pathfinding and related queries against the navigation mesh. Even if you use the crowd manager for steering, you'll need to use a navigation mesh query for non-local pathfinding and other higher level planning.
Core Class: NavmeshQuery
8 - Query Filter
Filters allow pathfinding behavior to be altered at runtime without changing the structure of the navigation mesh. They are used in most query methods to indicate which navigation mesh polygons are considered accessible and which aren't. They also define the traversal cost of different types of polygons.
Filters can be specific to individual agents or shared between groups of agents.
Core Class: NavmeshQueryFilter
9 - Crowd Manger
The crowd manager implements local steering. You provide it with agents to manage and local targets for the agents to move to, and it handles steering the agents in order to avoid collisions with other agents.
The use of the term "local" is important. CrowdManager can't do long distance path planning.
Core Class: CrowdManager
Dependencies and Layers
CAINav consists of multiple libraries, some optional.
The plug-in and core libraries are required. The rest are technically optional.
Duplicate dependencies are not shown.
Some optional 'extras' available for Unity are not shown.