Table of Contents
- Introduction
- Unity Integration Guide
- Basic Usage
- Advanced Usage
- Conclusion
- Reference
Introduction
I was working on my grid-based game in C#, and I needed a fast path-find algorithm for my game AI. While I was searching for a good algorithm (since I was not satisfied with A* or Dijkstra), I've found a great article (jump point search) by D. Harabor and a JavaScript implementation by Xueqiao Xu. And I came up with an idea, "Why not for C#?" So here it is! EpPathFinding.cs!
EpPathFinding.cs works very similar to PathFinding.js.
(If you are interested in more detail of the jump point search algorithm and the original JavaScript implementation, please see D. Harabor's article and Xueqiao Xu's implementation.)
Unity Integration Guide
Add EpPathFinding.cs\PathFinder folder to your Unity Project's Assets folder. Then within the script file, you want to use the EpPathFinding.cs, just add using EpPathFinding.cs; namespace at the top of the file, and use it as the guide below.
(If you have a problem when compiling, please refer to Unity Forum)
Basic Usage
The usage and the demo have been made very similar to PathFinding.js for ease of usage.
You first need to build a grid-map. (For example: width 64 and height 32):
BaseGrid searchGrid = new StaticGrid(64, 32);
By default, every node in the grid will NOT allow to be walked through. To set whether a node at a given coordinate is walkable or not, use the SetWalkableAt function.
For example, in order to set the node at (10 , 20) to be walkable, where 10 is the x coordinate (from left to right), and 20 is the y coordinate (from top to bottom):
searchGrid.SetWalkableAt(10, 20, true);
searchGrid.SetWalkableAt(new GridPos(10,20),true);
You may also use in a 2-d array while instantiating the Static<code>Grid class. It will initiate all the nodes in the grid with the walkability indicated by the array. (true for walkable otherwise not walkable):
bool [][] movableMatrix = new bool [width][];
for(int widthTrav=0; widthTrav< 64; widthTrav++)
{
movableMatrix[widthTrav]=new bool[height];
for(int heightTrav=0; heightTrav < 32; heightTrav++)
{
movableMatrix[widthTrav][heightTrav]=true;
}
}
BaseGrid searchGrid = new StaticGrid(64,32, movableMatrix);
In order to search the route from (10,10) to (20,10), you need to create JumpPointParam class with grid and start/end positions. (Note: Both the start point and end point must be walkable):
GridPos startPos=new GridPos(10,10);
GridPos endPos = new GridPos(20,10);
JumpPointParam jpParam = new JumpPointParam(searchGrid,startPos,endPos );
You can also set/change the start and end positions later. (However the start and end positions must be set before the actual search):
JumpPoinParam jpParam = new JumpPointParam(searchGrid);
jpParam.Reset(new GridPos(10,10), new GridPos(20,10));
To find a path, simply run FindPath function with JumpPointParam object created above:
List<GridPos> resultPathList = JumpPointFinder.FindPath(jpParam);
JumpPointParam class can be used as much as you want with different start/end positions unlike PathFinding.js:
jpParam.Reset(new GridPos(15,15), new GridPos(20,15));
resultPathList = JumpPointFinder.FindPath(jpParam);
Advanced Usage
Find the path even the end node is unwalkable
When instantiating the JumpPointParam, you may pass in additional parameter to make the search able to find path even the end node is unwalkable grid:
(Note that it automatically sets to true as a default when the parameter is not specified.)
JumpPointParam jpParam = new JumpPointParam(searchGrid, true);
If iAllowEndNodeUnWalkable is false the FindPath will return the empty path if the end node is unwalkable:
JumpPointParam jpParam = new JumpPointParam(searchGrid, false);
Cross Corners
When instantiating the JumpPointParam, you may pass in additional parameters to make the search able to walk diagonally when one of the side is unwalkable grid:
(Note that it automatically sets to true as a default when the parameter is not specified.)
JumpPointParam jpParam = new JumpPointParam(searchGrid,true,true);
To make it unable to walk diagonally when one of the side is unwalkable and rather go around the corner:
JumpPointParam jpParam = new JumpPointParam(searchGrid,true,false);
Cross Adjacent Point
When instantiating the JumpPointParam, you may pass in additional parameter to indicate specific strategies to use
(Note that this option will be ignored if the CrossCorner option is false.)
In order to make search able to walk diagonally across corner of two diagonal unwalkable nodes:
JumpPointParam jpParam = new JumpPointParam(searchGrid, true, true, true);
To make it unable to walk diagonally across two diagonal unwalkable corners:
JumpPointParam jpParam = new JumpPointParam(searchGrid, true, true, false);
Heuristic Functions
The predefined heuristics are Heuristic.EUCLIDEAN (default), Heuristic.MANHATTAN, and Heuristic.CHEBYSHEV.
To use the MANHATTAN heuristic function:
JumpPointParam jpParam = new JumpPointParam(searchGrid,true,true,true, Heuristic.MANHATTAN);
You can always change the heuristics later with SetHeuristic function:
jpParam.SetHeuristic(Heuristic.MANHATTAN);
Dynamic Grid
For my grid-based game, I had much less walkable grid nodes than un-walkable grid nodes. So above StaticGrid was wasting too much memory to hold un-walkable grid nodes. To avoid the memory waste, I have created DynamicGrid, which allocates the memory for only walkable grid nodes.
(Please note that there is trade off of memory and performance. This degrades the performance to improve memory usage.)
BaseGrid seachGrid = new DynamicGrid();
You may also use a List of walkable GridPos, while instantiating the Dynamic<code>Grid class. It will initiate only the nodes in the grid where the walkability is true:
List<GridPos> walkableGridPosList= new List<GridPos>();
for(int widthTrav=0; widthTrav< 64; widthTrav++)
{
movableMatrix[widthTrav]=new bool[height];
for(int heightTrav=0; heightTrav < 32; heightTrav++)
{
walkableGridPosList.Add(new GridPos(widthTrav, heightTrav));
}
}
BaseGrid searchGrid = new DynamicGrid(walkableGridPosList);
Rest of the functionality like SetWalkableAt, Reset, etc. are same as StaticGrid.
Dynamic Grid With Pool
In many cases, you might want to reuse the same grid for next search. And this can be extremely useful when used with PartialGridWPool, since you don't have to allocate the grid again.
NodePool nodePool = new NodePool();
BaseGrid seachGrid = new DynamicGridWPool(nodePool);
Rest of the functionality like SetWalkableAt, Reset, etc. are same as DynamicGrid.
Partial Grid With Pool
As mentioned above, if you want to search only partial of the grid for performance reason, you can use PartialGridWPool with/without DynamicGridWPool. Just give the GridRect which shows the portion of the grid you want to search within.
NodePool nodePool = new NodePool();
...
BaseGrid seachGrid = new PartialGridWPool(nodePool, new GridRect(1,3,15,30));
Rest of the functionality like SetWalkableAt, Reset, etc. are same as DynamicGridWPool.
UseRecursive
You may use recursive function or loop function to find the path. This can be simply done by setting UseRecursive flag in JumpPointParam:
(Note that the default is false, which uses loop function.)
JumpPointParam jpParam = new JumpPointParam(...);
jpParam.UseRecursive = true;
To change back to loop function
jpParam.UseRecursive = false;
Extendability
You can also create a sub-class of BaseGrid to create your own way of Grid class to best support your situation.
Conclusion
Most of functionality and work of EpPathFinding.cs project was originally from D. Harabor's article and PathFinding.js, so all the hard work and contribution should go to D. Harabor and Xueqiao Xu. The reason I am presenting this is in a hope of being helpful to someone who might need this algorithm in C#.
Reference
History
- 07.01.2015: - Advanced usage updated again.
- 02.18.2014: - Advanced usage updated
- 08.21.2013: - Re-distributed under MIT License
- 08.20.2013: - Article updated with "DynamicGrid"
- 08.19.2013: - Source updated with a bug fix. (Thanks to Jacek Gajek)
- 08.18.2013: - Source updated with a bug fix. (Thanks to Ted Goulden and sam.hill)
- 08.07.2013: - Source updated
- 08.06.2013: - Submitted the article
