A navigation map is created using one or more existing mesh(es) placed within your scene. After a pre-processing phase, the output map allows you to query runtime navigation paths (MapPath) and execute ray casting in real-time.

Each navigation map is built for a specific size of an agent since the walkable surfaces for each of them might be quite different. This will form multi-layered navigation maps that can be re-used by one or multiple characters.

Once a map is created multiple types of components can then be added on top to reflect the current condition of your scene. Obstacle can be placed manually or generated at runtime to tell the system that an area is now blocked.

You can also specify Zone; which allows you to modify the cost of a specific area making it more or less costly to pass; and or only allow its passage if a targeted character can perform a specific type of Ability.

To connect one location to another on the map; either to represent a teleport or simply to tell the system that the agent can jump (assuming that the agent can do such Ability) over you will be using a Connection. Connections can be either uni or bi-directional (allowing the agent to go back if possible).

Finally, it is also possible to connect navigation paths (aka. MapPath) through multiple maps. This scenario will happen frequently if you are loading and unloading dynamically Scene. The map query function allows you to try to expand the path on other maps available which share the same characteristics as the one the query was emitted on.

Static Variables

Name	Description
`navigation`	Reference to the global Navigation associated to your project where the active Map is stored.
Declaration Navigation *navigation
`cap`	Unique bit id use to identify the Map within the Navigation and during queries and placements.
Declaration int cap
`zone_count`	Total amount of Zone available.
Declaration unsigned char zone_count
`connection_count`	Current amount of Connection associated contained in the active Map.
Declaration unsigned int connection_count
`uid`	Unique identifier set by the system to internally identify the Map globally.
Declaration unsigned int uid
`zone_revision`	Increase everytime a Zone is added, removed or updated.
Declaration unsigned int zone_revision
`obstacle_revision`	Updated everytime an Obstacle is added, removed or updated.
Declaration unsigned int obstacle_revision
`connection_revision`	Revision number incremented everytime a Connection is added, removed or updated.
Declaration unsigned int connection_revision

Variables

Name	Description
`name`	A unique name to identify the Map within its parent Navigation.
Declaration char *name
`color`	An arbitrary color to identify the Map while debugging navigation inside the View3d.
Declaration vec4 color
`flags`	Bit mask built using the current options assigned to the active Map (see MapOptions).
Declaration int flags
`tile_size`	The width / height size of a tile on the xy-plane.
Declaration unsigned char tile_size Range 8 to 128
`tile_border`	The size of the non-navigable border around the heightfield.
Declaration unsigned char tile_border Range 0 to 16
`walkable_height`	Specify the height of the agent that will be navigating the Map.
Declaration float walkable_height Range 0.1 to 10.0
`walkable_radius`	Control the size (in term of radius) of the agent navigating the active Map.
Declaration float walkable_radius Range 0.1 to 10.0
`walkable_ledge_height`	The maximum height of the ledge an agent can climb.
Declaration float walkable_ledge_height Range 0.1 to 10.0
`min_region_area`	The minimum number of cells allowed to form an isolated island area.
Declaration int min_region_area Range 0 to 128
`merge_region_area`	Regions with a span count smaller than this value will be merged into larger region(s).
Declaration int merge_region_area Range 0 to 128
`max_edge_length`	Maximum allowed length for contour edges along the border of the navigation mesh.
Declaration int max_edge_length Range 0 to 64
`max_simplification_error`	Maximum distance of a simplfied contour border edge that deviate from the original raw contour.
Declaration float max_simplification_error Range 0.1 to 8.0
`max_verts_per_poly`	Maximum number of vertices allowed for polygons generated during the contour to polygon conversion process.
Declaration int max_verts_per_poly Range 3 to 12
`detail_sample_dist`	Sampling distance to use when generating the detail mesh (height details only).
Declaration float detail_sample_dist Range 0.0 to 16.0
`detail_sample_max_error`	Maximum distance the detail mesh surface can deviate from the heightfield data.
Declaration float detail_sample_max_error Range 0.0 to 16.0

Functions

Name	Description
`Build`	Build the active Map.
Declaration void Build( void )
`IsBuilt`	Helper to verify that the active Map has been built.
Declaration bool IsBuilt( void ) Return Value `true` if the Map is already built; else `false`.
`Update`	Manually trigger a Map update.
Declaration void Update( void ) Note This action is usually handled automatically by the internal system. You can still call this function to force updating Zone, sectors, Connection and Obstacle.
`Clear`	Clear out all internal Map data and restart fresh.
Declaration void Clear( void )
`AddZone`	Add a new Zone to the active Map.
Declaration Zone AddZone( const char name, unsigned char type, int ability_mask ) Parameters `name`: Unique name to identify the Zone within the Map. `type`: Zone type identifier, use `0` to let the system assign a new one. `ability_mask`: Bit mask of Ability cap values that determine the requirement to cross the Zone. Return Value A new Zone reference.
`GetZone`	Retrieve an existing Zone using its name as key.
Declaration Zone GetZone( const char name ) Return Value A valid Zone reference; `nil` if the name received in parameter does not match any zone contained in the active Map.
`GetZoneAt`	Get a specific Zone using its index as key.
Declaration Zone GetZoneAt( unsigned char index ) Parameters* `index`: Index of the Zone to retrieve. Return Value A valid Zone reference; `nil` if the index is out of bounds.
`GetZoneAtLocation`	Retrieve a Zone using a specific world space location.
Declaration Zone GetZoneAtLocation( const vec3 location ) `location`: The world position to use retrieve a Zone. Return Value* A valid Zone reference; `nil` if there is no Zone at the current location received in parameter.
`GetZoneByType`	Retrieve a Zone using its internal type.
Declaration Zone GetZoneByType( unsigned char type ) Parameters* `type`: The Zone type to retrieve. Return Value A valid Zone reference; `nil` if the type does not match any Zone that belongs to the active Map.
`GetZoneIndex`	Retrive the list index of a specific Zone.
Declaration int GetZoneIndex( const Zone zone ) Parameters* `zone`: A valid Zone reference pointer. Return Value `-1` if the `zone` does not belong to the active Map; else return a valid Zone reference pointer.
`RemoveZone`	Retrieve a Zone using its internal type.
Declaration bool RemoveZone( Zone zone ) Parameters* `zone`: A valid Zone reference pointe Return Value `true` if the `zone` have been removed; else return `false`.
`RemoveZoneAt`	Remove a Zone using its list index as key.
Declaration bool RemoveZoneAt( int index ) Parameters `index`: The index of the Zone to remove. Return Value `true` if removed successfully; else return `false` if the index is out of bounds.
`AddTile`	Add a new Tile at specific world space location.
Declaration bool AddTile( const vec3 location ) Parameters `location`: The position where to create the new Tile. Return Value `true` if a Tile have been created; `false` if the location was not on the Map or if a Tile already exists at that location.
`RemoveTile`	Remove a Tile from the grid.
Declaration bool RemoveTile( int x, int y, int layer ) Parameters `x`: The tile position on the X axis. `y`: The tile position on the Y axis. `layer_index`: The tile layer index (Z axis). Return Value `true` if removed successfully; else return `false` if the is inexistent.
`GetTileAt`	Retrieve a Tile using its grid coordinate.
Declaration Tile GetTileAt( int x, int y, int layer ) Parameters `x`: The tile position on the X axis. `y`: The tile position on the Y axis. `layer_index`: The tile layer index (Z axis). Return Value An empty Tile structure if the tile does not exist; else a fully filled Tile structure. Note To verify that the query was successful compare the tile XY and layer index with the ones returned by the function structure.
`GetTileAtLocation`	Retrieve a Tile at a world position.
Declaration Tile GetTileAtLocation( const vec3 location ) Parameters `location`: The location to test if a Tile is present. Return Value An empty Tile structure if the tile does not exist; else a fully filled Tile structure. Note To verify that the query was successful compare the tile XY and layer index with the ones returned by the function structure.
`UpdateTile`	Rebuild a specific Tile.
Declaration bool UpdateTile( int x, int y, int layer ) Parameters `x`: The tile position on the X axis. `y`: The tile position on the Y axis. `layer_index`: The tile layer index (Z axis). Return Value `true` if the Tile have been updated successfully; else return `false`.
`AddConnection`	Create a new Connection.
Declaration Connection AddConnection( const char name, const vec3 start_point, const vec3 end_point, float radius, bool bidirectional, int ability_mask ) Parameters `name`: A unique name to identify the Connection within its parent Map. `start_point`: Starting location point of the Connection in world space. `end_point`: End point of the Connection in world space. `radius`: The Connection radius which will be use by navigation query to evaluate the best path. `bidirectional: Determine wether or not the Connection should be uni-directional or bidirectional. Return Value A new Connection reference.
`GetConnection`	Retrieve an existing Connection using its name as key.
Declaration Connection GetConnection( const char name ) Parameters `name`: The name of the Connection to retrieve. Return Value Upon success, returns the Connection reference; else return `nil`.
`GetConnectionAt`	Retrieve an existing Connection using its index as key.
Declaration Connection GetConnectionAt( unsigned int index ) Parameters* `index`: Index of the Connection to retrieve. Return Value Upon success, returns the Connection reference; else return `nil` if the index is out of bounds.
`GetConnectionAtLocation`	Evaluate if a Connection resides at a specific location in world space.
Declaration Connection GetConnectionAtLocation( const vec3 location ) Parameters* `name`: The name of the Connection to retrieve. Return Value Upon success, returns the Connection located at the location specified; else return `nil`. Note The location received in parameter have to be inside the Connection radius (either start or endpoint) for the function to return a reference.
`GetConnectionIndex`	Return the index of an existing Connection.
Declaration int GetConnectionIndex( const Connection connection ) Parameters* `connection`: A valid Connection reference. Return Value `-1` if the Connection does not belong to the current Map; else the function will return its index.
`RemoveConnection`	Remove an existing Connection from the Map.
Declaration bool RemoveConnection( Connection connection ) Parameters* `connection`: The Connection reference to remove. Return Value `true` on success else return `false`.
`RemoveConnectionAt`	Remove a Connection using its index as key.
Declaration bool RemoveConnectionAt( int index ) Parameters `index`: Index of the Connection to remove. Return Value `true` on success else return `false`.
`Raycast`	Launch a ray to look for the intersection on the current Map.
Declaration MapRay Raycast( const vec3 ray_from, const vec3 ray_to, bool cull_face ) Parameters `ray_from`: The starting position of the ray. `ray_end`: The end location of the ray. `cull_face`: Determine if back-face should be culled or not. Return Value A fully filled MapRay structure; else an empty structure. Note To verify the hit evaluate if the `hit` variable of the MapRay structure is set to `true`. If not, not hit have been detected.
`GetInfo`	Return generic information about the active Map construction.
Declaration MapInfo GetInfo( void ) Return Value A valid MapInfo structure.
`GetPath`	Query the active Map for the shortest path an agent should take to reach an arbitrary destination
Declaration MapPath GetPath( const vec3 start_point, const vec3 end_point, int ability_mask, unsigned short max_points, const MapPathOption option, bool stitch ) Parameters `start_point`: Starting world space location of the agent. `end_point`: The destination point (in world space) the agent is trying to reach. `ability_mask`: A bit mask created from Ability caps that will determine the necessary abilities an agent should be able to perform to reach the destination point. `option`: Specify the MapPathOption mask that will affect the calculation of control points returned by the function. `stitch`: Force the system to extend the path by looking for existing junctions (see Zone) to allow the agent to reach its destination. As a result the MapPath returned can be extended on multiple maps. Return Value A valid MapPath structure that contains the controls points calculated during the navigation query. Note Upon a successful query the `point_count` variable of the MapPath structure will be greater than `0`. A `point_count` of `0` will indicate that the query has failed, and no path is available.
`GetNearestPoint`	Return the closest point on the Map from the location received in parameter.
Declaration vec4 GetNearestPoint( const vec3 point ) Return Value The closest point on the Map; the `w` component of the vector determine wether or not there was a hit.
`GetHit`	A more flexible and precise variant of the `RayCast` function.
Declaration MapHit GetHit( const vec3 start_point, const vec3 end_point, int ability_mask, unsigned short max_points ) `start_point`: Starting world space location of the agent. `end_point`: The destination point (in world space) the agent is trying to reach. `ability_mask`: A bit mask created from one of more Ability caps that will determine the necessary abilities to perform the ray cast operation. `max_points`: Stop the operation after finding a specific amount of control points. Return Value A valid MapHit structure; to ensure that there is an actual intersection evaluate the `hit` variable (make sure it is set to `true`).
`GetWallHit`	Look for a wall hit against the active Map within a specific radius.
Declaration MapHit GetWallHit( const vec3 location, float radius, int ability_mask ) `location`: The location to test. `radius`: The radius around the location parameter. `ability_mask`: Ability bit mask to widen or narrow down the query. Return Value A valid MapHit structure; check the `hit` value to insure an actual hit has occurred.
`FindRandomPoints`	Find a sepcific amount of random around the active Map.
Declaration vec3 FindRandomPoints( const int ability_mask, const unsigned short max_points ) `ability_mask`: Bit mask of Ability caps to prune points. `max_points`: The maximum amount of points to generate. Return Value* An array of tri-dimensional vector that contains the random points found on the navigation Map.
`FindRandomPointsAround`	Find a serie of random point around a specific location based on a custom radius.
Declaration vec3 FindRandomPointsAround( const vec3 location, const float radius, const int ability_mask, const unsigned short max_points ) `location`: The center point to use as reference to generate the random points. `radius`: Define the maximum distance of the points around the `location` provided. `ability_mask`: Bit mask of Ability caps to discard valid polys. `max_points`: The maximum amount of points to generate. Return Value* An array (or table) of vector that contains each point generated that are located in proximity of the `location` received in parameter.

MapOptions

Options that can be applied on a Map to improve its construction at the cost of most processing time.

The option allowing you to get more information from a navigation query by adding extra control points. Arbitrary tests can be executed during agent navigation evaluating active crossing.

fNavMapVisible: Show/Hide the Map in edit mode.
fBuildBVH: Build a binary volume hierarchy to improve MapPath computation time.
fFilterLowHangingWalkableObstacles: Marks non-walkable spans as walkable only if their maximum height is within the range of the walkable height.
fFilterLedgeSpans: Marks spans that are ledges as not-walkable.
fFilterWalkableLowHeightSpans: Marks walkable spans as not walkable if the clearence above the span is less than the specified height.
fErodeWalkableAreas: Erodes the walkable area within the heightfield by the walkable radius.

MapPathOption

Options available allowing you to get more information from a navigation query by adding extra control points. Arbitrary tests can be executed during agent navigation to evaluate the active crossing.

kStandard: Do not modify the MapPath control points.
kAreaCrossing: Add a control point at all area (Zone) crossing.
kAllCrossing: Add a control point at all crossing (Zone and Tile).

Tile

The data structure used to store the data information of a single Tile on the navigation grid.

Static Variables

Name	Description
`header`	The TileHeader which represents its coordinates on the navigation mesh grid.
Declaration TileHeader header
`min`	The lower bound of the Tile AABB.
Declaration vec3 min
`max`	The upper bound of the Tile AABB.
Declaration vec3 max
`vertex_count`	The amount of vertex the Tile contains.
Declaration int vertex_count
`polygon_count`	Total amount of polygon that are used to create the Tile.
Declaration int polygon_count
`walkable_height`	The Tile walkable height.
Declaration float walkable_height
`walkable_radius`	The Tile walkable radius.
Declaration float walkable_radius
`walkable_ledge_height`	The Tile walkable ledge height.
Declaration float walkable_ledge_height
`mem_usage`	Amount of memory (in bytes) the Tile is currently using.
Declaration unsigned int mem_usage

MapPointFlag

Flags that can be accessed via each point returned by the MapPath structure. They determine the properties associated with a MapPoint.

fStart: Specify that the control point is the starting point of the MapPath.
fFinish: Specify that the point is the ending point of the MapPath.
fConnection: Determine whether or not the control point refers to an existing Connection.

MapPoint

Store the data for each MapPath control point.

Static Variables

Name	Description
`location`	The control point location on the Map.
Declaration vec3 location
`flags`	MapPointFlag set for the active MapPoint.
Declaration MapPointFlags flags
`ability_mask`	Bit mask of Ability used by the current MapPoint.
Declaration int ability_mask

MapPath

The data structure that handles the return values of a navigation query after calling the GetPath function. The structure contains all control points that define the closest route from the starting point to the destination point specified.

Static Variables

Name Description

point_count The control point location on the Map.

Declaration

unsigned short point_count

Functions

Name	Description
`GetPoint`	Return a specific MapPoint location using an index as key.
Declaration vec3 GetPoint( unsigned short point_index ) `point_index`: Index of the point to return. Return Value The location in world space of the navigation point; else return a zeroed vector in the event the `point_index` is invalid.
`GetFlags`	Return the active flags of a specific MapPoint.
Declaration MapPointFlags GetFlags( unsigned short point_index ) `point_index`: Index of the point to return. Return Value The flags used by the point assuming the the index is valid; if invalid `-1`.
`GetAbilityMask`	Get the ability mask used by a specific point.
Declaration int GetAbilityMask( unsigned short point_index ) `point_index`: Index of the point to return the ability for. Return Value The ability mask used by the control point at `point_index`; else return `-1` if the `point_index` is invalid.
`GetMapPoint`	Return a specific navigation path point.
Declaration MapPoint GetMapPoint( unsigned short point_index ) `index`: Index of the point to return. Return Value A filled MapPoint structure on success; if the `point_index` is out of bounds return a zeroed structure with a negative ability mask.

MapHit

The data structure used to return a hit by a ray against the Map.

Static Variables

Name	Description
`hit`	`True` if a hit occur; else `false`.
Declaration bool hit
`hit_point`	The hit location point.
Declaration vec3 hit_point
`hit_normal`	The normal at the hit point location.
Declaration vec3 hit_normal
`hit_distance`	Distance between the ray starting position and the hit position.
Declaration float hit_distance

MapRay

The structure used to return a hit by a ray against the Map.

Static Variables

Name	Description
`hit`	`True` if a hit occur; else `false`.
Declaration bool hit
`hit_point`	The hit location point.
Declaration vec3 hit_point
`hit_normal`	The normal at the hit point location.
Declaration vec3 hit_normal
`tile_header`	The TileHeader of the Tile where the hit occur.
Declaration TileHeader tile_header
`area_id`	User defined area id (Sector).
Declaration unsigned char area_id
`poly_flags`	Polygon flags containing the mask of Ability that can be used on the active polygon.
Declaration unsigned short poly_flags
`poly_type`	The active polygon type (either ground:`0` or connection:`1`).
Declaration unsigned char poly_type

MapInfo

Structure containing general information about the active Map.

Static Variables

Name	Description
`tile_size`	The tile size used to generate the Map.
Declaration int tile_size
`cell_size`	Original cell size used to generate the Map.
Declaration float cell_size
`cell_height`	The cell height used when the Map was generated.
Declaration float cell_height
`grid_size_x`	Amount of tiles on the X plane.
Declaration int grid_size_x
`grid_size_y`	Amount of tiles on the Y plane.
Declaration int grid_size_y
`tile_max`	The maximum amount of tiles.
Declaration int tile_max
`polygon_max`	Maximum amount of polygons.
Declaration int polygon_max
`raw_usage`	Raw memory usage in bytes.
Declaration int raw_usage
`mem_usage`	Compressed memory usage in bytes.
Declaration int mem_usage