Map

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.

See Also

Static Variables


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

Variables


Name

Description

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

Functions


Name Description
Build Build the active Map.
IsBuilt Helper to verify that the active Map has been built.
Update Manually trigger a Map update.
Clear Clear out all internal Map data and restart fresh.
AddZone Add a new Zone to the active Map.
GetZone Retrieve an existing Zone using its name as key.
GetZoneAt Get a specific Zone using its index as key.
GetZoneAtLocation Retrieve a Zone using a specific world space location.
GetZoneByType Retrieve a Zone using its internal type.
GetZoneIndex Retrive the list index of a specific Zone.
RemoveZone Retrieve a Zone using its internal type.
RemoveZoneAt Remove a Zone using its list index as key.
AddTile Add a new Tile at specific world space location.
RemoveTile Remove a Tile from the grid.
GetTileAt Retrieve a Tile using its grid coordinate.
GetTileAtLocation Retrieve a Tile at a world position.
UpdateTile Rebuild a specific Tile.
AddConnection Create a new Connection.
GetConnection Retrieve an existing Connection using its name as key.
GetConnectionAt Retrieve an existing Connection using its index as key.
GetConnectionAtLocation Evaluate if a Connection resides at a specific location in world space.
GetConnectionIndex Return the index of an existing Connection.
RemoveConnection Remove an existing Connection from the Map.
RemoveConnectionAt Remove a Connection using its index as key.
Raycast Launch a ray to look for the intersection on the current Map.
GetInfo Return generic information about the active Map construction.
GetPath Query the active Map for the shortest path an agent should take to reach an arbitrary destination
GetNearestPoint Return the closest point on the Map from the location received in parameter.
GetHit A more flexible and precise variant of the RayCast function.
GetWallHit Look for a wall hit against the active Map within a specific radius.
FindRandomPoints Find a sepcific amount of random around the active Map.
FindRandomPointsAround Find a serie of random point around a specific location based on a custom radius.

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.
min The lower bound of the Tile AABB.
max The upper bound of the Tile AABB.
vertex_count The amount of vertex the Tile contains.
polygon_count Total amount of polygon that are used to create the Tile.
walkable_height The Tile walkable height.
walkable_radius The Tile walkable radius.
walkable_ledge_height The Tile walkable ledge height.
mem_usage Amount of memory (in bytes) the Tile is currently using.

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
point The control point location on the Map.
flags MapPointFlag set for the active MapPoint.
ability_mask Bit mask of Ability used by the current MapPoint.

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.

Functions


Name Description
GetPoint Return a specific MapPoint location using an index as key.
GetFlags Return the active flags of a specific MapPoint.
GetAbilityMask Get the ability mask used by a specific point.
GetMapPoint Return a specific navigation path point.

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.
hit_point The hit location point.
hit_normal The normal at the hit point location.
hit_distance Distance between the ray starting position and the hit position.

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.
hit_point The hit location point.
hit_normal The normal at the hit point location.
tile_header The TileHeader of the Tile where the hit occur.
area_id User defined area id (Sector).
poly_flags Polygon flags containing the mask of Ability that can be used on the active polygon.
poly_type The active polygon type (either ground:0 or connection:1).

MapInfo


Structure containing general information about the active Map.

Static Variables


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




NRG - API 2022.3.383570 - Thu Jul 28 2022
Copyright © 2022 nrgcore.com. All Rights Reserved. Terms of Service - Privacy Policy - EULA