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.

See also

Graph Updates during Runtime.

For info on how to search for nodes close to a point, take a look at Using nodes

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 convenience 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.data.gridGraph;
        PointGraph pointGraph = AstarPath.active.data.pointGraph;
        NavMeshGraph navmeshGraph = AstarPath.active.data.navmesh;
        RecastGraph recastGraph = AstarPath.active.data.recastGraph;
        LayerGridGraph layerGridGraph = AstarPath.active.data.layerGridGraph;

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

        // You can set the name of a graph in the graph inspector
        var graph = AstarPath.active.data.FindGraph(g => g.name == "My Custom Graph Name");

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 reason it uses a callback instead of an iterator is because callbacks are significantly faster than iterators and for large graphs that does make a difference.

        var gg = AstarPath.active.data.gridGraph;

        gg.GetNodes(node => {
            // Here is a node
            Debug.Log("I found a node at position " + (Vector3)node.position);
        });

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.AddWorkItem.

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. There are also convenience methods for accessing the nodes:

        var gg = AstarPath.active.data.gridGraph;
        int x = 5;
        int z = 8;
        GridNodeBase node = gg.GetNode(x, z);

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 use the SetDimensions method. After you have changed the width or depth of the graph you need to recalculate it using AstarPath.Scan.

        var gg = AstarPath.active.data.gridGraph;
        var width = 80;
        var depth = 60;
        var nodeSize = 1.0f;

        gg.SetDimensions(width, depth, nodeSize);

        // 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 necessary matrix yourself.

Layered Grid Graph

The layered grid graph works almost like the grid graph. However since layered grid graphs can contain several layers. An additional layer coordinate is needed.

        var gg = AstarPath.active.data.layerGridGraph;
        int x = 5;
        int z = 8;
        int layer = 0;
        GridNodeBase node = gg.GetNode(x, z, layer);

NavmeshGraph/RecastGraph

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. Navmesh graphs work exactly the same as recast graphs however they always use a single tile.

        var graph = AstarPath.active.data.recastGraph;
        int tileX = 5;
        int tileZ = 8;
        NavmeshTile tile = graph.GetTile(tileX, tileZ);

        for (int i = 0; i < tile.nodes.Length; i++) {
            // ...
        }
        // or you can access the nodes like this:
        tile.GetNodes(node => {
            // ...
        });

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");
        }

You can also add nodes to a point graph during runtime:

        AstarPath.active.AddWorkItem(new AstarWorkItem(ctx => {
            var graph = AstarPath.active.data.pointGraph;
            // Add 2 nodes and connect them
            var node1 = graph.AddNode((Int3)transform.position);
            var node2 = graph.AddNode((Int3)(transform.position + Vector3.right));
            var cost = (uint)(node2.position - node1.position).costMagnitude;
            node1.AddConnection(node2, cost);
            node2.AddConnection(node1, cost);
            // Required because we have changed connectivity of the graph
            ctx.QueueFloodFill();
        }));

See also

Graph Updates during Runtime which among other things explains more about the QueueFloodFill call.