Pathfinding interface

Contents

• Searching for paths using a Seeker
• Other types of paths
• Calling AstarPath directly
• Getting graph data
  • Finding Nodes

Searching for paths using a Seeker

The pathfinding can be called in a number of ways. The by far easiest method is to have Seeker component attached to the GameObject you want to call pathfinding from and then call Seeker::StartPath.
Note a Seeker will only take one pathfinding call at a time, if you send one before the previous one has been completed, it the previous one will be canceled
The Seeker will also automatically handle modifiers.

using Pathfinding;

public void Start () {
    //Get the seeker component attached to this GameObject
    Seeker seeker = GetComponent<Seeker>();
    
    //Start a new path request from the current position to a position 10 units forward.
    //When the path has been calculated, it will be returned to the function OnPathComplete unless it was canceled by another path request
    seeker.StartPath (transform.position, transform.position+transform.forward*10, OnPathComplete);
}

public void OnPathComplete (Path p) {
    //We got our path back
    if (p.error) {
        //Nooo, a valid path couldn't be found
    } else {
        //Yey, now we can get a Vector3 representation of the path
        //from p.vectorPath
    }
}

You can also create your own path objects instead of using the Seekers functions.
This will enable you to change settings on the path object before calculating it.

//Create a new path object, the last parameter is a callback function
//but it will be used internally by the seeker, so we will set it to null here
Path p = new Path (transform.position, transform.position+transform.forward*10, null);

// By default, a search for the closest walkable nodes to the start and end nodes will be carried out
//but for example in a turn based game, you might not want it to search for the closest walkable node, but return an error if the target point
//was at an unwalkable node. Setting the NNConstraint to None will disable the nearest walkable node search
p.nnConstraint = NNConstraint.None;

//Start the path by sending it to the Seeker
seeker.StartPath (p, OnPathComplete);

It might seem tedious to specify the callback function every time, well, you don't have to.
There is a field on the Seeker which can be set to a function which will be called every time a path is returned. For those of you interested in performance, this is also a tiny bit faster and does not allocate a new delegate on the heap.

//Set the path callback, this should be done once
seeker.pathCallback += OnPathComplete;
 
//Now we can skip the callback function parameter
seeker.StartPath (transform.position, transform.position+transform.forward*10);

Note

This callback is permanent, while the component you are calling from might not be, so it's good practise to un-register from the callback when the component is destroyed

public void OnDisable () {
    seeker.pathCallback -= OnPathComplete;
}

A nice thing is that the callback is not limited to one function, you can have several scripts which all get a callback, or just callbacks to more than one function in the script (if you of some reason need that).
That's why I have been using + and - when registering and un-registering the callback.

Other types of paths

There are other types of paths than the standard one, for example the MultiTargetPath (Pro feature).
These can be started easily as well, especially the MultiTargetPath since the Seeker has a special function for it

//Start a multi target path, where endPoints is a Vector3[] array. The last parameter specifies if path to all end points should be searched for
//or only to the closest one
seeker.StartMultiTargetPath (transform.position,endPoints,true);

The path will be returned as a Path instance, but it can be casted to for example MultiTargetPath to get all the data. The full example of MultiTargetPaths can be found here: Multi Target Paths

Note

The MultiTargetPath is an A* Pathfinding Project Pro Feature, so you will get an error if you try the above code using the Free version of the project.

The generic way to start a type of path is simply

Path p = MyPathType.Construct (...);    //For example MultiTargetPath
seeker.StartPath (p, OnPathComplete);

This is instead of a real consructor. It is used so that path pooling can be done more easily.

Calling AstarPath directly

There are of-course cases where you want even more control of each path. Then you can call AstarPath directly. The main function you then use is AstarPath::StartPath
Note that these paths will not be post-processed

//There must be an AstarPath instance in the scene
if (AstarPath.active == null) return;

//As there is not Seeker to keep track of the callbacks, you now need to specify the callback every time again
Path p = ABPath.Construct (transform.position, transform.position+transform.forward*10, OnPathComplete);
 
//Start the path, but call AstarPath directly
//AstarPath.active is the current AstarPath instance
AstarPath.StartPath (p);

Getting graph data

Finding Nodes

Sometimes you want to get access to the graph data. If you, for example are making a TD game, you probably don't want to place a tower on an unwalkable node.
Here's how you get nodes

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

Note

Also check out the page on updating graphs during runtime: Updating Graphs 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's default, because it is used for path calls if nothing else is said)

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

The search range of these constraints is not unlimited, but quite large, for grid graphs it will search a large square, but for Point Graphs, it will actually search the whole graph since they are usually small.

Version

The code on this page was written without any testing, but I hope I haven't made any mistakes.
It was written for version 3.0.7
Updated for version 3.2.5 to use new syntax.