A* Pathfinding Project  4.0.1
The A* Pathfinding Project for Unity 3D
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Properties Events Macros Groups Pages
NavmeshCut Class Reference

Navmesh cutting is used for fast recast graph updates. More...

Detailed Description

Navmesh cutting is used for fast recast graph updates.

Navmesh cutting is used to cut holes into an existing navmesh generated by a recast graph. Recast graphs usually only allow either just changing parameters on existing nodes (e.g make a whole triangle unwalkable) which is not very flexible or recalculate a whole tile which is pretty slow. With navmesh cutting you can remove (cut) parts of the navmesh that is blocked by obstacles such as a new building in an RTS game however you cannot add anything new to the navmesh or change the positions of the nodes.


The NavmeshCut component uses a 2D shape to cut the navmesh with. A rectangle and circle shape is built in, but you can also specify a custom mesh to use. The custom mesh should be a flat 2D shape like in the image below. The script will then find the contour of that mesh and use that shape as the cut. Make sure that all normals are smooth and that the mesh contains no UV information. Otherwise Unity might split a vertex and then the script will not find the correct contour. You should not use a very high polygon mesh since that will create a lot of nodes in the navmesh graph and slow down pathfinding because of that. For very high polygon meshes it might even cause more suboptimal paths to be generated if it causes many thin triangles to be added to the navmesh.

Note that the shape is not 3D so if you rotate the cut you will see that the 2D shape will be rotated and then just projected down on the XZ plane.

To use a navmesh cut in your scene you need to have a TileHandlerHelper script somewhere in your scene. You should only have one though. That script will take care of checking all the NavmeshCut components to see if they need to update the navmesh.

In the scene view the NavmeshCut looks like an extruded 2D shape because a navmesh cut also has a height. It will only cut the part of the navmesh which it touches. For performance it only checks the bounding boxes of the triangles in the navmesh, so it may cut triangles whoose bounding boxes it intersects even if the triangle does not intersect the extructed shape. However in most cases this does not make a large difference.

It is also possible to set the navmesh cut to dual mode by setting the isDual field to true. This will prevent it from cutting a hole in the navmesh and it will instead just split the navmesh along the border but keep both the interior and the exterior. This can be useful if you for example want to change the penalty of some region which does not neatly line up with the navmesh triangles. It is often combined with the GraphUpdateScene component (however note that the GraphUpdateScene component will not automatically reapply the penalty if the graph is updated again).

By default the navmesh cut does not take rotation or scaling into account. If you want to do that, you can set the useRotationAndScale field to true. This is a bit slower, but it is not a very large difference.

A* Pro Feature:
This is an A* Pathfinding Project Pro feature only. This function/class/variable might not exist in the Free version of the A* Pathfinding Project or the functionality might be limited
The Pro version can be bought here
See Also
http://www.arongranberg.com/2013/08/navmesh-cutting/

Public Types

enum  MeshType { Rectangle, Circle, CustomMesh }
 

Public Member Functions

void ForceUpdate ()
 Forces this navmesh cut to update the navmesh.
 
Rect GetBounds (Pathfinding.Util.GraphTransform transform)
 Bounds in XZ space after transforming using the *inverse* transform of the transform parameter.
 
void GetContour (List< List< Vector3 > > buffer)
 World space contour of the navmesh cut.
 
void NotifyUpdated ()
 Internal method to notify the NavmeshCut that it has just been used to update the navmesh.
 
void OnDrawGizmos ()
 
void OnDrawGizmosSelected ()
 
bool RequiresUpdate ()
 Returns true if this object has moved so much that it requires an update.
 
virtual void UsedForCut ()
 Called whenever this navmesh cut is used to update the navmesh.
 

Public Attributes

Vector3 center
 
float circleRadius = 1
 Radius of the circle.
 
int circleResolution = 6
 Number of vertices on the circle.
 
bool cutsAddedGeom = true
 Cuts geometry added by a NavmeshAdd component.
 
float height = 1
 The cut will be extruded to this height.
 
bool isDual
 Only makes a split in the navmesh, but does not remove the geometry to make a hole.
 
Mesh mesh
 Custom mesh to use.
 
float meshScale = 1
 Scale of the custom mesh, if used.
 
Vector2 rectangleSize = new Vector2(1, 1)
 Size of the rectangle.
 
MeshType type
 Shape of the cut.
 
float updateDistance = 0.4f
 Distance between positions to require an update of the navmesh.
 
float updateRotationDistance = 10
 How many degrees rotation that is required for an update to the navmesh.
 
bool useRotationAndScale
 Includes rotation and scale in calculations.
 

Static Public Attributes

static readonly Color GizmoColor = new Color(37.0f/255, 184.0f/255, 239.0f/255)
 
static System.Action< NavmeshCutOnDisableCallback
 Called every time a NavmeshCut component is disabled.
 
static System.Action< NavmeshCutOnEnableCallback
 Called every time a NavmeshCut component is enabled.
 

Protected Member Functions

override void Awake ()
 
- Protected Member Functions inherited from VersionedMonoBehaviour
virtual int OnUpgradeSerializedData (int version)
 Handle serialization backwards compatibility.
 

Protected Attributes

Transform tr
 cached transform component
 

Package Functions

float GetY (Pathfinding.Util.GraphTransform transform)
 Y coordinate of the center of the bounding box in graph space.
 

Private Member Functions

void CalculateMeshContour ()
 
void OnDisable ()
 
void OnEnable ()
 
void TransformBuffer (List< Vector3 > buffer, bool reverse)
 

Private Attributes

Vector3[][] contours
 
Mesh lastMesh
 
Vector3 lastPosition
 
Quaternion lastRotation
 

Static Private Attributes

static readonly Dictionary
< Int2, int > 
edges = new Dictionary<Int2, int>()
 Cached variable, to avoid allocations.
 
static readonly Dictionary
< int, int > 
pointers = new Dictionary<int, int>()
 Cached variable, to avoid allocations.
 

Member Enumeration Documentation

enum MeshType
Enumerator:
Rectangle 
Circle 
CustomMesh 

Member Function Documentation

override void Awake ( )
protectedvirtual

Reimplemented from VersionedMonoBehaviour.

void CalculateMeshContour ( )
private
void ForceUpdate ( )

Forces this navmesh cut to update the navmesh.

Note
Dynamic updating requires a Tile Handler Helper somewhere in the scene. This update is not instant, it is done the next time the TileHandlerHelper checks this instance for if it needs updating.
See Also
TileHandlerHelper.ForceUpdate()
Rect GetBounds ( Pathfinding.Util.GraphTransform  transform)

Bounds in XZ space after transforming using the *inverse* transform of the transform parameter.

The transformation will typically transform the vertices to graph space and this is used to figure out which tiles the cut intersects.

void GetContour ( List< List< Vector3 > >  buffer)

World space contour of the navmesh cut.

Fills the specified buffer with all contours. The cut may contain several contours which is why the buffer is a list of lists.

float GetY ( Pathfinding.Util.GraphTransform  transform)
package

Y coordinate of the center of the bounding box in graph space.

void NotifyUpdated ( )

Internal method to notify the NavmeshCut that it has just been used to update the navmesh.

void OnDisable ( )
private
void OnDrawGizmos ( )
void OnDrawGizmosSelected ( )
void OnEnable ( )
private
bool RequiresUpdate ( )

Returns true if this object has moved so much that it requires an update.

When an update to the navmesh has been done, call NotifyUpdated to be able to get relavant output from this method again.

void TransformBuffer ( List< Vector3 >  buffer,
bool  reverse 
)
private
virtual void UsedForCut ( )
virtual

Called whenever this navmesh cut is used to update the navmesh.

Called once for each tile the navmesh cut is in. You can override this method to execute custom actions whenever this happens.

Member Data Documentation

Vector3 center
float circleRadius = 1

Radius of the circle.

int circleResolution = 6

Number of vertices on the circle.

Vector3 [][] contours
private
bool cutsAddedGeom = true

Cuts geometry added by a NavmeshAdd component.

You rarely need to change this

readonly Dictionary<Int2, int> edges = new Dictionary<Int2, int>()
staticprivate

Cached variable, to avoid allocations.

readonly Color GizmoColor = new Color(37.0f/255, 184.0f/255, 239.0f/255)
static
float height = 1

The cut will be extruded to this height.

bool isDual

Only makes a split in the navmesh, but does not remove the geometry to make a hole.

This is slower than a normal cut

Mesh lastMesh
private
Vector3 lastPosition
private
Quaternion lastRotation
private
Mesh mesh

Custom mesh to use.

The contour(s) of the mesh will be extracted. If you get the "max perturbations" error when cutting with this, check the normals on the mesh. They should all point in the same direction. Try flipping them if that does not help.

This mesh should only be a 2D surface, not a volume.

float meshScale = 1

Scale of the custom mesh, if used.

System.Action<NavmeshCut> OnDisableCallback
static

Called every time a NavmeshCut component is disabled.

System.Action<NavmeshCut> OnEnableCallback
static

Called every time a NavmeshCut component is enabled.

readonly Dictionary<int, int> pointers = new Dictionary<int, int>()
staticprivate

Cached variable, to avoid allocations.

Vector2 rectangleSize = new Vector2(1, 1)

Size of the rectangle.

Transform tr
protected

cached transform component

MeshType type

Shape of the cut.

float updateDistance = 0.4f

Distance between positions to require an update of the navmesh.

A smaller distance gives better accuracy, but requires more updates when moving the object over time, so it is often slower.

Note
Dynamic updating requires a TileHandlerHelper somewhere in the scene.
float updateRotationDistance = 10

How many degrees rotation that is required for an update to the navmesh.

Should be between 0 and 180.

Note
Dynamic updating requires a Tile Handler Helper somewhere in the scene.
bool useRotationAndScale

Includes rotation and scale in calculations.

This is slower since a lot more matrix multiplications are needed but gives more flexibility.


The documentation for this class was generated from the following file: