Click here to Skip to main content
15,867,453 members
Articles / Game Development

EpPathFinding.cs- A Fast Path Finding Algorithm (Jump Point Search) in C# (grid-based)

Rate me:
Please Sign up or sign in to vote.
4.82/5 (46 votes)
1 Jul 2015MIT5 min read 107.4K   4.7K   99   19
A jump point search algorithm for grid based games in C#
 

Image 1

Table of Contents

  1. Introduction 
  2. Unity Integration Guide
  3. Basic Usage
  4. Advanced Usage
  5. Conclusion
  6. 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):

C#
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):

C#
searchGrid.SetWalkableAt(10, 20, true);
 
// OR
 
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):

C#
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):

C#
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):

C#
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:

C#
List<GridPos> resultPathList = JumpPointFinder.FindPath(jpParam); 

JumpPointParam class can be used as much as you want with different start/end positions unlike PathFinding.js:

C#
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.)

C#
JumpPointParam jpParam = new JumpPointParam(searchGrid, true); 

If iAllowEndNodeUnWalkable is false the FindPath will return the empty path if the end node is unwalkable:

C#
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.) 

C#
JumpPointParam jpParam = new JumpPointParam(searchGrid,true,true);   

Image 2

To make it unable to walk diagonally when one of the side is unwalkable and rather go around the corner:

C#
JumpPointParam jpParam = new JumpPointParam(searchGrid,true,false);   

 

Image 3

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:

C#
JumpPointParam jpParam = new JumpPointParam(searchGrid, true, true, true); 

Image 4 

To make it unable to walk diagonally across two diagonal unwalkable corners:

C#
JumpPointParam jpParam = new JumpPointParam(searchGrid, true, true, false);   

Image 5

Heuristic Functions  

The predefined heuristics are Heuristic.EUCLIDEAN (default), Heuristic.MANHATTAN, and Heuristic.CHEBYSHEV.

To use the MANHATTAN heuristic function: 

C#
JumpPointParam jpParam = new JumpPointParam(searchGrid,true,true,true, Heuristic.MANHATTAN); 

You can always change the heuristics later with SetHeuristic function:

C#
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.)

C#
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:

C#
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 SetWalkableAtReset, 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.

C#
NodePool nodePool = new NodePool();
BaseGrid seachGrid = new DynamicGridWPool(nodePool);   

Rest of the functionality like SetWalkableAtReset, 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.

C#
NodePool nodePool = new NodePool();
...
BaseGrid seachGrid = new PartialGridWPool(nodePool, new GridRect(1,3,15,30));   

Rest of the functionality like SetWalkableAtReset, 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.) 

C#
// To use recursive function
JumpPointParam jpParam = new JumpPointParam(...);
jpParam.UseRecursive = true 

To change back to loop function

C#
// 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 

License

This article, along with any associated source code and files, is licensed under The MIT License


Written By
Software Developer
United States United States
Woong Gyu La had been working as a software developer for over 8 years.
His personal interests are improving his personal projects,

EpLibrary (Visual C++ Utility Library)
https://github.com/juhgiyo/EpLibrary[^]

EpOraLibrary (Oracle OCI Wrapper Library for Visual C++)
https://github.com/juhgiyo/EpOraLibrary[^]

EpServerEngine (Visual C++ WinSock Server/Client Engine)
https://github.com/juhgiyo/EpServerEngine[^]

And other projects can be found at
https://github.com/juhgiyo?tab=repositories[^]

Finally, my other articles can be found at
http://www.codeproject.com/Articles/juhgiyo#articles[^]

You can contact me at juhgiyo@gmail.com[^]

Comments and Discussions

 
QuestionNo diagonal path Pin
Member 1451579125-Dec-19 2:16
Member 1451579125-Dec-19 2:16 
PraiseClean and ready to upgrade for the needs of your project Pin
Tkangal8-Mar-17 5:35
Tkangal8-Mar-17 5:35 
QuestionResult path Pin
reverso1322-Sep-16 0:57
reverso1322-Sep-16 0:57 
AnswerRe: Result path Pin
Chris La22-Sep-16 2:13
professionalChris La22-Sep-16 2:13 
Questionuploading map Pin
Member 1093836210-Dec-14 20:16
Member 1093836210-Dec-14 20:16 
QuestionFull path list Pin
Member 1067978827-Mar-14 10:03
Member 1067978827-Mar-14 10:03 
AnswerRe: Full path list Pin
Chris La29-Mar-14 6:05
professionalChris La29-Mar-14 6:05 
GeneralMy vote of 5 Pin
Athari10-Sep-13 21:53
Athari10-Sep-13 21:53 
QuestionGPL License --> nobody will use? [Edit: now MIT, yay!] Pin
JaredThirsk19-Aug-13 19:39
JaredThirsk19-Aug-13 19:39 
AnswerRe: GPL License --> nobody will use? Pin
Chris La20-Aug-13 4:52
professionalChris La20-Aug-13 4:52 
GeneralRe: GPL License --> nobody will use? Pin
JaredThirsk20-Aug-13 11:04
JaredThirsk20-Aug-13 11:04 
GeneralRe: GPL License --> nobody will use? Pin
David Jeske25-Oct-14 23:25
David Jeske25-Oct-14 23:25 
GeneralMy vote of 4 Pin
sam.hill8-Aug-13 6:40
sam.hill8-Aug-13 6:40 
GeneralRe: My vote of 4 Pin
Chris La8-Aug-13 12:54
professionalChris La8-Aug-13 12:54 
GeneralRe: My vote of 4 Pin
sam.hill8-Aug-13 19:34
sam.hill8-Aug-13 19:34 
GeneralRe: My vote of 4 Pin
Ted Goulden15-Aug-13 10:08
Ted Goulden15-Aug-13 10:08 
GeneralRe: My vote of 4 Pin
Chris La15-Aug-13 11:22
professionalChris La15-Aug-13 11:22 
GeneralRe: My vote of 4 Pin
Ted Goulden17-Aug-13 12:14
Ted Goulden17-Aug-13 12:14 
GeneralRe: My vote of 4 Pin
Chris La17-Aug-13 14:19
professionalChris La17-Aug-13 14:19 
Thanks a lot for the screenshot, you sent me.

Yes, it was bug due to my stupid mistake.

I will update the code as soon as possible.

Thanks.

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.