Caveats
Here's an overview of some of the caveats.
Unreachable islands
Consider a scenario on a grid where a goal location is totally enclosed by walls. If the starting location is beyond those walls, A* will have to search the entire grid before knowing for certain that the goal is unreachable. There are several ways to mitigate this.
The easiest method is to provide an upper bound on the maximum amount of nodes A* may expand into. This can be set with the MaxExpand property on a Finder.
Do a simple Eval query from goal to start before attempting to find a full path from start to goal. This only works for undirected graphs.
Use seperate graphs or flags to know beforehand if islands are connected
Standalone builds
Unity does not support open generic types for burst compiled jobs in generic jobs. If you use any of the OptionFinders, this means that the TOption type cannot be left open in the finder class declaration. This unfortuntately means you have to declare a finder class for every specific type you're targeting with an option finder. The code generater enforces this rule for you however.
Note that the jobs will work in the Unity editor, but an exception will be thrown in a standalone build if the job could not be burst compiled.
Straight paths on grid like navmeshes
If your navmesh resembles a grid, it may be possible that the resulting paths do not seem to take the shortest possible straight path.
Because A* can only operate on the triangles itself, there may be many optimal paths to the destination that share the same cost (at the triangle level). If you use SSFA, then it may become apparent that the path that was chosen was not the most optimal after SSFA was performed.
Since v1.4, you can use the NavMeshStraightLineMod to mitigate this.
Known Issues
The type or namespace name 'NativeMultiHashMap<,>' could not be found.
If you're getting a compilation error along the lines of: "The type or namespace name 'NativeMultiHashMap<,>' could not be found."
This package was made with Unity 2020.3.16f1, so that it remains compatible with older Unity versions. The error occurs because Unity renamed these collections. NativeMultiHashMap became NativeParallelMultiHashMap in later versions. This should be resolved automatically, but if it doesn't, you can fix it by running the API updater by launching Unity with the -accept-apiupdate option.
For more information visit: https://docs.unity3d.com/6000.0/Documentation/Manual/APIUpdater.html
Jobs are not burst compiled
In some extremely rare cases, if you get a warning along the lines of: "Compilation was requested for method ..." for a PathFinder job. First check if you made a concrete implementation of the class using the AnyPath code generator.
If so, then there may be a bug in Unity where the Burst compiler sometimes doesn't detect these classes if they are defined alphanumerically before the AnyPath folder itself. I know this sounds very strange, but it currently is the only explanation for this issue. Please try renaming the class that your definitions are in and see if it resolves the warning. A project reload may be required.
You can also try running a build and see if the error "Job was not burst compiled!" turns up. If you do not get this error then everything is OK and AnyPath should run optimal.