Accessing graph data

How to access graphs and nodes.

All data in the graphs can be accessed. There are for example many cases where the API expects a GraphNode as a parameter so you need to be able to find those. And there can be other cases where you need to extensively modify the graph data to suit your game. For example you might have your own custom made tilemap generator and you need to pass that data to the grid graph.

Finding Nodes close to Positions

Here's how you get nodes

// Find the closest node to this GameObject's position
GraphNode node = AstarPath.active.GetNearest (transform.position).node;
if (node.Walkable) {
    // Yay, the node is walkable, we can place a tower here or something
}

Note

Also check out the page on updating graphs during runtime: Graph Updates during Runtime.

There are also cases where you want to get only certain nodes, such as "What is the closest *Walkable* node to this position?". This can be accomplished using the Pathfinding.NNConstraint. For this case the Default NNConstraint (it is called default, because it is used for path calls if nothing else is specified)

GraphNode node = AstarPath.active.GetNearest (transform.positon, NNConstraint.Default).node;

The search range of these constraints is not unlimited, but quite large. The maximum distance can be set in A* Inspector -> Settings -> Max Nearest Node Distance or AstarPath.maxNearestNodeDistance.

Closest Point on Nodes

You may have noticed above that to get the node from the GetNearest call we had to access the node field. The GetNearest method returns an NNInfo struct which contains two fields. The first one is the node field which contains the best node (or null if no node could be found). The second one is the position field which contains the closest point on that node to the query point. On grid graphs, the nodes are thought of as squares so the position field will then contain the closest point inside that square to the query point. On navmesh based graphs (RecastGraph and NavMeshGraph) the position field will contain the closest point on the closest triangle. Point nodes do not have a surface so the position will just be set to the node's position.

Accessing graphs

All graphs are stored in the Pathfinding.AstarData class. It contains an array with all the graphs and there are a bunch of methods for finding graphs in it. The quickest way however is to use the shortcuts that are provided. For each type of built in graph there is a field which points to the first graph of that type.

GridGraph gridGraph = AstarPath.active.astarData.gridGraph;
PointGraph pointGraph = AstarPath.active.astarData.pointGraph;
RecastGraph recastGraph = AstarPath.active.astarData.recastGraph;
NavMeshGraph navmeshGraph = AstarPath.active.astarData.navmesh;
LayerGridGraph layerGridGraph = AstarPath.active.astarData.layerGridGraph;

NavGraph[] allGraphs = AstarPath.active.astarData.graphs;

Getting nodes in a graph.

The different graphs types store their nodes in different ways. The grid graph for example stores all nodes in a huge array which can be indexed to easily get a node at a specific cell index. The recast graph stores all nodes in arrays in separate tiles.

The generic very high-level way to get all nodes in a graph is by using the GetNodes method which exists on all types of graphs. It takes a callback which will be invoked for each node. The callback should return true if the graph should continue to call it with the rest of the nodes in the graph and false if it should stop. The reason it is a callback instead of an iterator is because after profiling I found this to be significantly faster and for large graphs that does make a difference.

var gg = AstarPath.active.astarData.gridGraph;
gg.GetNodes (node => {
    // Here is a node
    return true;
});

Warning

Do not update the data in the nodes. This can interfere with pathfinding that might be running at the same time (especially if using multithreading). To safely update node data you need to do that inside a safe callback. You can request a safe callback using AstarPath.RegisterSafeUpdate.

See Also

Graph Updates during Runtime

GridGraph

Grid graph nodes are stored in a large array. It is indexed by the coordinates of the node so they can be accessed easily.

var gg = AstarPath.active.astarData.gridGraph;
int x = 5;
int z = 8;
GridNode node = gg.nodes[z*gg.width + x];

There are some cases where you want to change the size of a grid graph during runtime. Then you can modify either the unclampedSize field. Which is the size of the grid in world units. Or you can modify the width and depth fields. But then you need to call the UpdateSizeFromWidthDepth method afterwards. After you have changed the width or depth of the graph you need to recalculate it using AstarPath.Scan.

var gg = AstarPath.active.astarData.gridGraph;
gg.width = 80;
gg.depth = 60;
gg.UpdateSizeFromWidthDepth();

// Recalculate the graph
AstarPath.active.Scan ();

It is also possible to move the grid graph without recalculating it using the RelocateNodes method. The same method is also available for other graphs, but then you have to calculate the necessarily matrix yourself.

Layered Grid Graph

The layered grid graph works almost like the grid graph. However the nodes are not ordered in exactly the same way. Since layered grid graphs can contain several layers. An additional layer coordinate is needed.

var gg = AstarPath.active.astarData.layerGridGraph;
int x = 5;
int z = 8;
int y = 2; // Layer
LevelGridNode node = gg.nodes[y*gg.width*gg.depth + z*gg.width + x];

Recast Graphs

Recast graphs divide the nodes into a number of tiles. The individual tiles are stored in an array in the same way as the grid graph stores its nodes. Inside each tile, the nodes are stored in an array without any inherent order. However all nodes are also added to a axis aligned bounding box tree AABB Tree in order to be able to query for the closest node to a point in an efficient manner.

var graph = AstarPath.active.astarData.recastGraph;
int tileX = 5;
int tileZ = 8;
RecastGraph.NavmeshTile tile = graph.tiles[tileZ*graph.tileXCount + tileX];
for (int i = 0; i < tile.nodes.Length; i++) {
    // ...
}

PointGraph

Point graphs simply store the nodes in an array without any inherent order.

Point graph nodes also contain a field for the GameObject they were created from (if any) which can be useful for all kinds of purposes.

var node = AstarPath.active.GetNearest (transform.position).node;
var pointNode = node as PointNode;
if (pointNode != null) {
    Debug.Log ("That node was created from the GameObject named " + pointNode.gameObject.name);
} else {
    Debug.Log ("That node is not a PointNode");
}