Add a hierarchical path finder to improve pathfinding performance.

Replaces the existing bi-directional search between points used by the pathfinder with a guided hierarchical search. The old search was a standard A* search with a heuristic of advancing in straight line towards the target. This heuristic performs well if a mostly direct path to the target exists, it performs poorly it the path has to navigate around blockages in the terrain. The hierarchical path finder maintains a simplified, abstract graph. When a path search is performed it uses this abstract graph to inform the heuristic. Instead of moving blindly towards the target, it will instead steer around major obstacles, almost as if it had been provided a map which ensures it can move in roughly the right direction. This allows it to explore less of the area overall, improving performance.

When a path needs to steer around terrain on the map, the hierarchical path finder is able to greatly improve on the previous performance. When a path is able to proceed in a straight line, no performance benefit will be seen. If the path needs to steer around actors on the map instead of terrain (e.g. trees, buildings, units) then the same poor pathfinding performance as before will be observed.

OpenRA.Mods.Common/Pathfinder/PathSearch.cs

@@ -20,12 +20,6 @@ namespace OpenRA.Mods.Common.Pathfinder
 {
 	public sealed class PathSearch : IDisposable
 	{
-		/// <summary>
-		/// When searching for paths, use a default weight of 125% to reduce
-		/// computation effort - even if this means paths may be sub-optimal.
-		/// </summary>
-		public const int DefaultHeuristicWeightPercentage = 125;
-
 		// PERF: Maintain a pool of layers used for paths searches for each world. These searches are performed often
 		// so we wish to avoid the high cost of initializing a new search space every time by reusing the old ones.
 		static readonly ConditionalWeakTable<World, CellInfoLayerPool> LayerPoolTable = new ConditionalWeakTable<World, CellInfoLayerPool>();
@@ -37,13 +31,14 @@ namespace OpenRA.Mods.Common.Pathfinder
 		}
 
 		public static PathSearch ToTargetCellByPredicate(
-			World world, Locomotor locomotor, Actor self, IEnumerable<CPos> froms, Func<CPos, bool> targetPredicate, BlockedByActor check,
+			World world, Locomotor locomotor, Actor self,
+			IEnumerable<CPos> froms, Func<CPos, bool> targetPredicate, BlockedByActor check,
 			Func<CPos, int> customCost = null,
 			Actor ignoreActor = null,
 			bool laneBias = true)
 		{
 			var graph = new MapPathGraph(LayerPoolForWorld(world), locomotor, self, world, check, customCost, ignoreActor, laneBias, false);
-			var search = new PathSearch(graph, loc => 0, DefaultHeuristicWeightPercentage, targetPredicate);
+			var search = new PathSearch(graph, loc => 0, 0, targetPredicate);
 
 			foreach (var sl in froms)
 				if (world.Map.Contains(sl))
@@ -53,15 +48,20 @@ namespace OpenRA.Mods.Common.Pathfinder
 		}
 
 		public static PathSearch ToTargetCell(
-			World world, Locomotor locomotor, Actor self, IEnumerable<CPos> froms, CPos target, BlockedByActor check,
+			World world, Locomotor locomotor, Actor self,
+			IEnumerable<CPos> froms, CPos target, BlockedByActor check, int heuristicWeightPercentage,
 			Func<CPos, int> customCost = null,
 			Actor ignoreActor = null,
 			bool laneBias = true,
 			bool inReverse = false,
 			Func<CPos, int> heuristic = null,
-			int heuristicWeightPercentage = DefaultHeuristicWeightPercentage)
+			Grid? grid = null)
 		{
-			var graph = new MapPathGraph(LayerPoolForWorld(world), locomotor, self, world, check, customCost, ignoreActor, laneBias, inReverse);
+			IPathGraph graph;
+			if (grid != null)
+				graph = new GridPathGraph(locomotor, self, world, check, customCost, ignoreActor, laneBias, inReverse, grid.Value);
+			else
+				graph = new MapPathGraph(LayerPoolForWorld(world), locomotor, self, world, check, customCost, ignoreActor, laneBias, inReverse);
 
 			heuristic = heuristic ?? DefaultCostEstimator(locomotor, target);
 			var search = new PathSearch(graph, heuristic, heuristicWeightPercentage, loc => loc == target);
@@ -73,6 +73,18 @@ namespace OpenRA.Mods.Common.Pathfinder
 			return search;
 		}
 
+		public static PathSearch ToTargetCellOverGraph(
+			Func<CPos, List<GraphConnection>> edges, Locomotor locomotor, CPos from, CPos target,
+			int estimatedSearchSize = 0)
+		{
+			var graph = new SparsePathGraph(edges, estimatedSearchSize);
+			var search = new PathSearch(graph, DefaultCostEstimator(locomotor, target), 100, loc => loc == target);
+
+			search.AddInitialCell(from);
+
+			return search;
+		}
+
 		/// <summary>
 		/// Default: Diagonal distance heuristic. More information:
 		/// http://theory.stanford.edu/~amitp/GameProgramming/Heuristics.html
@@ -113,9 +125,9 @@ namespace OpenRA.Mods.Common.Pathfinder
 		}
 
 		public IPathGraph Graph { get; }
+		public Func<CPos, bool> TargetPredicate { get; set; }
 		readonly Func<CPos, int> heuristic;
 		readonly int heuristicWeightPercentage;
-		readonly Func<CPos, bool> targetPredicate;
 		readonly IPriorityQueue<GraphConnection> openQueue;
 
 		/// <summary>
@@ -137,7 +149,7 @@ namespace OpenRA.Mods.Common.Pathfinder
 			Graph = graph;
 			this.heuristic = heuristic;
 			this.heuristicWeightPercentage = heuristicWeightPercentage;
-			this.targetPredicate = targetPredicate;
+			TargetPredicate = targetPredicate;
 			openQueue = new PriorityQueue<GraphConnection>(GraphConnection.ConnectionCostComparer);
 		}
 
@@ -215,6 +227,30 @@ namespace OpenRA.Mods.Common.Pathfinder
 			return currentMinNode;
 		}
 
+		/// <summary>
+		/// Expands the path search until a path is found, and returns whether a path is found successfully.
+		/// </summary>
+		public bool ExpandToTarget()
+		{
+			while (CanExpand())
+				if (TargetPredicate(Expand()))
+					return true;
+
+			return false;
+		}
+
+		/// <summary>
+		/// Expands the path search over the whole search space.
+		/// Returns the cells that were visited during the search.
+		/// </summary>
+		public List<CPos> ExpandAll()
+		{
+			var consideredCells = new List<CPos>();
+			while (CanExpand())
+				consideredCells.Add(Expand());
+			return consideredCells;
+		}
+
 		/// <summary>
 		/// Expands the path search until a path is found, and returns that path.
 		/// Returned path is *reversed* and given target to source.
@@ -224,7 +260,7 @@ namespace OpenRA.Mods.Common.Pathfinder
 			while (CanExpand())
 			{
 				var p = Expand();
-				if (targetPredicate(p))
+				if (TargetPredicate(p))
 					return MakePath(Graph, p);
 			}