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

Basic point graph. More...

Detailed Description

Basic point graph.

The List graph is the most basic graph structure, it consists of a number of interconnected points in space, waypoints or nodes.
The list graph takes a Transform object as "root", this Transform will be searched for child objects, every child object will be treated as a node. It will then check if any connections between the nodes can be made, first it will check if the distance between the nodes isn't too large ( maxDistance ) and then it will check if the axis aligned distance isn't too high. The axis aligned distance, named limits, is useful because usually an AI cannot climb very high, but linking nodes far away from each other, but on the same Y level should still be possible. limits and maxDistance won't affect anything if the values are 0 (zero) though.
Lastly it will check if there are any obstructions between the nodes using raycasting which can optionally be thick.
One thing to think about when using raycasting is to either place the nodes a small distance above the ground in your scene or to make sure that the ground is not in the raycast mask to avoid the raycast from hitting the ground.

Note
Does not support linecast because of obvious reasons.

Public Member Functions

void AddChildren (ref int c, Transform tr)
 Recursively adds childrens of a transform as nodes.
 
PointNode AddNode (Int3 position)
 Add a node to the graph at the specified position.
 
AddNode< T > (T nd, Int3 position)
 Add a node with the specified type to the graph at the specified position.
 
void AddToLookup (PointNode node)
 
GraphUpdateThreading CanUpdateAsync (GraphUpdateObject o)
 
override void DeserializeExtraInfo (GraphSerializationContext ctx)
 Deserializes graph type specific node data.
 
override NNInfo GetNearest (Vector3 position, NNConstraint constraint, GraphNode hint)
 Returns the nearest node to a position using the specified NNConstraint.
 
override NNInfo GetNearestForce (Vector3 position, NNConstraint constraint)
 Returns the nearest node to a position using the specified constraint.
 
override void GetNodes (GraphNodeDelegateCancelable del)
 Calls a delegate with all nodes in the graph.
 
virtual bool IsValidConnection (GraphNode a, GraphNode b, out float dist)
 Returns if the connection between a and b is valid.
 
override void PostDeserialization ()
 Called after all deserialization has been done for all graphs.
 
void RebuildNodeLookup ()
 Rebuilds the lookup structure for nodes.
 
override void RelocateNodes (Matrix4x4 oldMatrix, Matrix4x4 newMatrix)
 Relocates the nodes in this graph.
 
override void ScanInternal (OnScanStatus statusCallback)
 Scans the graph, called from AstarPath.ScanInternal Override this function to implement custom scanning logic The statusCallback may be optionally called to show progress info in the editor
 
override void SerializeExtraInfo (GraphSerializationContext ctx)
 Serializes graph type specific node data.
 
void UpdateArea (GraphUpdateObject guo)
 Updates an area in the list graph.
 
void UpdateAreaInit (GraphUpdateObject o)
 
- Public Member Functions inherited from NavGraph
virtual void Awake ()
 This will be called on the same time as Awake on the gameObject which the AstarPath script is attached to.
 
virtual int CountNodes ()
 Count nodes in the graph.
 
NNInfo GetNearest (Vector3 position)
 Returns the nearest node to a position using the default NNConstraint.
 
NNInfo GetNearest (Vector3 position, NNConstraint constraint)
 Returns the nearest node to a position using the specified NNConstraint.
 
virtual Color NodeColor (GraphNode node, PathHandler data)
 
virtual void OnDestroy ()
 Function for cleaning up references.
 
virtual void OnDrawGizmos (bool drawNodes)
 Draw gizmos for the graph.
 
void Scan ()
 
void ScanGraph ()
 Consider using AstarPath.Scan () instead since this function might screw things up if there is more than one graph.
 
void ScanInternal ()
 Internal method for scanning graphs.
 
void SetMatrix (Matrix4x4 m)
 Use to set both matrix and inverseMatrix at the same time.
 
- Public Member Functions inherited from IUpdatableGraph
GraphUpdateThreading CanUpdateAsync (GraphUpdateObject o)
 
void UpdateArea (GraphUpdateObject o)
 Updates an area using the specified GraphUpdateObject.
 
void UpdateAreaInit (GraphUpdateObject o)
 

Static Public Member Functions

static int CountChildren (Transform tr)
 Recursively counds children of a transform.
 
- Static Public Member Functions inherited from NavGraph
static bool InSearchTree (GraphNode node, Path path)
 Returns if the node is in the search tree of the path.
 

Public Attributes

bool autoLinkNodes = true
 
Vector3 limits
 Max distance along the axis for a connection to be valid.
 
LayerMask mask
 Layer mask to use for raycast.
 
float maxDistance = 0
 Max distance for a connection to be valid.
 
int nodeCount
 Number of nodes in this graph.
 
PointNode[] nodes
 All nodes in this graph.
 
bool optimizeFor2D = false
 Optimizes for when the graph is mostly spread out in the XZ plane.
 
bool optimizeForSparseGraph = false
 Optimizes the graph for sparse graphs.
 
bool raycast = true
 Use raycasts to check connections.
 
bool recursive = true
 Recursively search for childnodes to the root.
 
Transform root
 Childs of this transform are treated as nodes.
 
string searchTag
 If no root is set, all nodes with the tag is used as nodes.
 
bool thickRaycast = false
 Use thick raycast.
 
float thickRaycastRadius = 1
 Thick raycast radius.
 
bool use2DPhysics = false
 Use the 2D Physics API.
 
- Public Attributes inherited from NavGraph
byte[] _sguid
 Used to store the guid value.
 
AstarPath active
 Reference to the AstarPath object in the scene.
 
bool drawGizmos = true
 
uint graphIndex
 Index of the graph, used for identification purposes.
 
bool infoScreenOpen
 Used in the editor to check if the info screen is open.
 
uint initialPenalty = 0
 Default penalty to apply to all nodes.
 
Matrix4x4 inverseMatrix = Matrix4x4.identity
 Inverse of matrix.
 
Matrix4x4 matrix = Matrix4x4.identity
 A matrix for translating/rotating/scaling the graph.
 
string name
 Name of the graph.
 
bool open
 Is the graph open in the editor.
 

Private Member Functions

Int3 WorldToLookupSpace (Int3 p)
 

Private Attributes

Int3 lookupCellSize
 
Int3 maxLookup
 
Int3 minLookup
 
Dictionary< Int3, PointNodenodeLookup
 

Static Private Attributes

static readonly Int3[] ThreeDNeighbours
 

Additional Inherited Members

- Properties inherited from NavGraph
Guid guid [get, set]
 Used as an ID of the graph, considered to be unique.
 

Member Function Documentation

void AddChildren ( ref int  c,
Transform  tr 
)

Recursively adds childrens of a transform as nodes.

PointNode AddNode ( Int3  position)

Add a node to the graph at the specified position.

Note
Vector3 can be casted to Int3 using (Int3)myVector.
This needs to be called when it is safe to update nodes, which is
T AddNode< T > ( nd,
Int3  position 
)

Add a node with the specified type to the graph at the specified position.

Note
Vector3 can be casted to Int3 using (Int3)myVector.
Parameters
ndThis must be a node created using T(AstarPath.active) right before the call to this method. The node parameter is only there because there is no new(AstarPath) constraint on generic type parameters.
Note
This needs to be called when it is safe to update nodes, which is
Type Constraints
T :PointNode 
void AddToLookup ( PointNode  node)
GraphUpdateThreading CanUpdateAsync ( GraphUpdateObject  o)
static int CountChildren ( Transform  tr)
static

Recursively counds children of a transform.

override void DeserializeExtraInfo ( GraphSerializationContext  ctx)
virtual

Deserializes graph type specific node data.

See Also
SerializeExtraInfo

Reimplemented from NavGraph.

override NNInfo GetNearest ( Vector3  position,
NNConstraint  constraint,
GraphNode  hint 
)
virtual

Returns the nearest node to a position using the specified NNConstraint.

Parameters
positionThe position to try to find a close node to
hintCan be passed to enable some graph generators to find the nearest node faster.
constraintCan for example tell the function to try to return a walkable node. If you do not get a good node back, consider calling GetNearestForce.

Reimplemented from NavGraph.

override NNInfo GetNearestForce ( Vector3  position,
NNConstraint  constraint 
)
virtual

Returns the nearest node to a position using the specified constraint.

Parameters
positionA Vector3
constraintA NNConstraint
Returns
A NNInfo. This function will only return an empty NNInfo if there are no nodes which comply with the specified constraint.

Reimplemented from NavGraph.

override void GetNodes ( GraphNodeDelegateCancelable  del)
virtual

Calls a delegate with all nodes in the graph.

This is the primary way of "looping" through all nodes in a graph.

This function should not change anything in the graph structure.

myGraph.GetNodes ((node) => {
Debug.Log ("I found a node at position " + (Vector3)node.Position);
return true;
});

Implements NavGraph.

virtual bool IsValidConnection ( GraphNode  a,
GraphNode  b,
out float  dist 
)
virtual

Returns if the connection between a and b is valid.

Checks for obstructions using raycasts (if enabled) and checks for height differences.
As a bonus, it outputs the distance between the nodes too if the connection is valid

override void PostDeserialization ( )
virtual

Called after all deserialization has been done for all graphs.

Can be used to set up more graph data which is not serialized

Reimplemented from NavGraph.

void RebuildNodeLookup ( )

Rebuilds the lookup structure for nodes.

This is used when optimizeForSparseGraph is enabled.

You should call this method every time you move a node in the graph manually and you are using optimizeForSparseGraph, otherwise pathfinding might not work correctly.

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
override void RelocateNodes ( Matrix4x4  oldMatrix,
Matrix4x4  newMatrix 
)
virtual

Relocates the nodes in this graph.

Assumes the nodes are already transformed using the "oldMatrix", then transforms them such that it will look like they have only been transformed using the "newMatrix". The "oldMatrix" is not required by all implementations of this function though (e.g the NavMesh generator).

The matrix the graph is transformed with is typically stored in the matrix field, so the typical usage for this method is

var myNewMatrix = Matrix4x4.TRS (...);
myGraph.RelocateNodes (myGraph.matrix, myNewMatrix);

So for example if you want to move all your nodes in e.g a point graph 10 units along the X axis from the initial position

var graph = AstarPath.astarData.pointGraph;
var m = Matrix4x4.TRS (new Vector3(10,0,0), Quaternion.identity, Vector3.one);
graph.RelocateNodes (graph.matrix, m);
Note
For grid graphs it is recommended to use the helper method RelocateNodes which takes parameters for center and nodeSize (and additional parameters) instead since it is both easier to use and is less likely to mess up pathfinding.
Warning
This method is lossy, so calling it many times may cause node positions to loose precision. For example if you set the scale to 0 in one call, and then to 1 in the next call, it will not be able to recover the correct positions since when the scale was 0, all nodes were scaled/moved to the same point. The same thing happens for other - less extreme - values as well, but to a lesser degree.
Version
Prior to version 3.6.1 the oldMatrix and newMatrix parameters were reversed by mistake.

Reimplemented from NavGraph.

override void ScanInternal ( OnScanStatus  statusCallback)
virtual

Scans the graph, called from AstarPath.ScanInternal Override this function to implement custom scanning logic The statusCallback may be optionally called to show progress info in the editor

Implements NavGraph.

override void SerializeExtraInfo ( GraphSerializationContext  ctx)
virtual

Serializes graph type specific node data.

This function can be overriden to serialize extra node information (or graph information for that matter) which cannot be serialized using the standard serialization. Serialize the data in any way you want and return a byte array. When loading, the exact same byte array will be passed to the DeserializeExtraInfo function.
These functions will only be called if node serialization is enabled.

Reimplemented from NavGraph.

void UpdateArea ( GraphUpdateObject  guo)

Updates an area in the list graph.

Recalculates possibly affected connections, i.e all connectionlines passing trough the bounds of the guo will be recalculated

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
void UpdateAreaInit ( GraphUpdateObject  o)
Int3 WorldToLookupSpace ( Int3  p)
private

Member Data Documentation

bool autoLinkNodes = true
Vector3 limits

Max distance along the axis for a connection to be valid.

0 = infinity

Int3 lookupCellSize
private
LayerMask mask

Layer mask to use for raycast.

float maxDistance = 0

Max distance for a connection to be valid.

The value 0 (zero) will be read as infinity and thus all nodes not restricted by other constraints will be added as connections.

A negative value will disable any neighbours to be added. It will completely stop the connection processing to be done, so it can save you processing power if you don't these connections.

Int3 maxLookup
private
Int3 minLookup
private
int nodeCount

Number of nodes in this graph.

Warning
Do not edit directly
Dictionary<Int3, PointNode> nodeLookup
private
PointNode [] nodes

All nodes in this graph.

Note that only the first nodeCount will be non-null.

You can also use the GetNodes method to get all nodes.

bool optimizeFor2D = false

Optimizes for when the graph is mostly spread out in the XZ plane.

Requires optimizeForSparseGraph.

When your graph is mostly spread out in the XZ plane instead of equally in all directions, you can tick this toggle to speed up some calculations. If you do not have a graph which is spread out mostly on the XZ plane, enabling this option will most likely degrade the performance of the graph instead of improve it.

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
bool optimizeForSparseGraph = false

Optimizes the graph for sparse graphs.

This can reduce calculation times for both scanning and for normal path requests by huge amounts.

You should enable this when your maxDistance and/or limits variables are set relatively low compared to the world size. It reduces the number of node-node checks that need to be done during scan, and can also optimize getting the nearest node from the graph (such as when querying for a path).

Try enabling and disabling this option, check the scan times logged when you scan the graph to see if your graph is suited for this optimization or if it makes it slower.

The gain of using this optimization increases with larger graphs, the default scan algorithm is brute force and requires O(n^2) checks, this optimization along with a graph suited for it, requires only O(n) checks during scan.

Note
When you have this enabled, you will not be able to move nodes around using scripting unless you recalculate the lookup structure at the same time.
See Also
RebuildNodeLookup
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
bool raycast = true

Use raycasts to check connections.

bool recursive = true

Recursively search for childnodes to the root.

Transform root

Childs of this transform are treated as nodes.

string searchTag

If no root is set, all nodes with the tag is used as nodes.

bool thickRaycast = false

Use thick raycast.

float thickRaycastRadius = 1

Thick raycast radius.

readonly Int3 [] ThreeDNeighbours
staticprivate
bool use2DPhysics = false

Use the 2D Physics API.


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