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/Traits/BotModules/HarvesterBotModule.cs

@@ -142,7 +142,7 @@ namespace OpenRA.Mods.Common.Traits
 				harv.Harvester.CanHarvestCell(cell) &&
 				claimLayer.CanClaimCell(actor, cell);
 
-			var path = harv.Mobile.PathFinder.FindUnitPathToTargetCellByPredicate(
+			var path = harv.Mobile.PathFinder.FindPathToTargetCellByPredicate(
 				actor, new[] { actor.Location }, isValidResource, BlockedByActor.Stationary,
 				loc => world.FindActorsInCircle(world.Map.CenterOfCell(loc), Info.HarvesterEnemyAvoidanceRadius)
 					.Where(u => !u.IsDead && actor.Owner.RelationshipWith(u.Owner) == PlayerRelationship.Enemy)

OpenRA.Mods.Common/Traits/Harvester.cs

@@ -193,7 +193,7 @@ namespace OpenRA.Mods.Common.Traits
 				}).ToLookup(r => r.Location);
 
 			// Start a search from each refinery's delivery location:
-			var path = mobile.PathFinder.FindUnitPathToTargetCell(
+			var path = mobile.PathFinder.FindPathToTargetCell(
 				self, refineries.Select(r => r.Key), self.Location, BlockedByActor.None,
 				location =>
 				{

OpenRA.Mods.Common/Traits/Mobile.cs

@@ -825,7 +825,7 @@ namespace OpenRA.Mods.Common.Traits
 			if (CanEnterCell(above))
 				return above;
 
-			var path = PathFinder.FindUnitPathToTargetCellByPredicate(
+			var path = PathFinder.FindPathToTargetCellByPredicate(
 				self, new[] { self.Location }, loc => loc.Layer == 0 && CanEnterCell(loc), BlockedByActor.All);
 
 			if (path.Count > 0)

OpenRA.Mods.Common/Traits/World/HierarchicalPathFinderOverlay.cs

@@ -0,0 +1,137 @@
+#region Copyright & License Information
+/*
+ * Copyright 2007-2022 The OpenRA Developers (see AUTHORS)
+ * This file is part of OpenRA, which is free software. It is made
+ * available to you under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3 of
+ * the License, or (at your option) any later version. For more
+ * information, see COPYING.
+ */
+#endregion
+
+using System.Collections.Generic;
+using System.Linq;
+using OpenRA.Graphics;
+using OpenRA.Mods.Common.Commands;
+using OpenRA.Mods.Common.Graphics;
+using OpenRA.Primitives;
+using OpenRA.Traits;
+
+namespace OpenRA.Mods.Common.Traits
+{
+	[TraitLocation(SystemActors.World)]
+	[Desc("Renders a debug overlay showing the abstract graph of the hierarchical pathfinder. Attach this to the world actor.")]
+	public class HierarchicalPathFinderOverlayInfo : TraitInfo, Requires<PathFinderInfo>
+	{
+		public readonly string Font = "TinyBold";
+		public readonly Color GroundLayerColor = Color.DarkOrange;
+		public readonly Color CustomLayerColor = Color.Blue;
+		public readonly Color GroundToCustomLayerColor = Color.Purple;
+		public readonly Color AbstractNodeColor = Color.Red;
+
+		public override object Create(ActorInitializer init) { return new HierarchicalPathFinderOverlay(this); }
+	}
+
+	public class HierarchicalPathFinderOverlay : IRenderAnnotations, IWorldLoaded, IChatCommand
+	{
+		const string CommandName = "hpf";
+		const string CommandDesc = "toggles the hierarchical pathfinder overlay.";
+
+		readonly HierarchicalPathFinderOverlayInfo info;
+		readonly SpriteFont font;
+
+		public bool Enabled { get; private set; }
+
+		/// <summary>
+		/// The Locomotor selected in the UI which the overlay will display.
+		/// If null, will show the overlays for the currently selected units.
+		/// </summary>
+		public Locomotor Locomotor { get; set; }
+
+		public HierarchicalPathFinderOverlay(HierarchicalPathFinderOverlayInfo info)
+		{
+			this.info = info;
+			font = Game.Renderer.Fonts[info.Font];
+		}
+
+		void IWorldLoaded.WorldLoaded(World w, WorldRenderer wr)
+		{
+			var console = w.WorldActor.TraitOrDefault<ChatCommands>();
+			var help = w.WorldActor.TraitOrDefault<HelpCommand>();
+
+			if (console == null || help == null)
+				return;
+
+			console.RegisterCommand(CommandName, this);
+			help.RegisterHelp(CommandName, CommandDesc);
+		}
+
+		void IChatCommand.InvokeCommand(string name, string arg)
+		{
+			if (name == CommandName)
+				Enabled ^= true;
+		}
+
+		IEnumerable<IRenderable> IRenderAnnotations.RenderAnnotations(Actor self, WorldRenderer wr)
+		{
+			if (!Enabled)
+				yield break;
+
+			var pathFinder = self.Trait<PathFinder>();
+			var visibleRegion = wr.Viewport.AllVisibleCells;
+			var locomotors = Locomotor == null
+				? self.World.Selection.Actors
+					.Where(a => !a.Disposed)
+					.Select(a => a.TraitOrDefault<Mobile>()?.Locomotor)
+					.Where(l => l != null)
+					.Distinct()
+				: new[] { Locomotor };
+			foreach (var locomotor in locomotors)
+			{
+				var abstractGraph = pathFinder.GetOverlayDataForLocomotor(locomotor);
+
+				// Locomotor doesn't allow movement, nothing to display.
+				if (abstractGraph == null)
+					continue;
+
+				foreach (var connectionsFromOneNode in abstractGraph)
+				{
+					var nodeCell = connectionsFromOneNode.Key;
+					var srcUv = (PPos)nodeCell.ToMPos(self.World.Map);
+					foreach (var cost in connectionsFromOneNode.Value)
+					{
+						var destUv = (PPos)cost.Destination.ToMPos(self.World.Map);
+						if (!visibleRegion.Contains(destUv) && !visibleRegion.Contains(srcUv))
+							continue;
+
+						var connection = new WPos[]
+						{
+							self.World.Map.CenterOfSubCell(cost.Destination, SubCell.FullCell),
+							self.World.Map.CenterOfSubCell(nodeCell, SubCell.FullCell),
+						};
+
+						// Connections on the ground layer given in ground color.
+						// Connections on any custom layers given in custom color.
+						// Connections that allow a transition between layers given in transition color.
+						Color lineColor;
+						if (nodeCell.Layer == 0 && cost.Destination.Layer == 0)
+							lineColor = info.GroundLayerColor;
+						else if (nodeCell.Layer == cost.Destination.Layer)
+							lineColor = info.CustomLayerColor;
+						else
+							lineColor = info.GroundToCustomLayerColor;
+						yield return new TargetLineRenderable(connection, lineColor, 1, 2);
+
+						var centerCell = new CPos(
+							(cost.Destination.X + nodeCell.X) / 2,
+							(cost.Destination.Y + nodeCell.Y) / 2);
+						var centerPos = self.World.Map.CenterOfSubCell(centerCell, SubCell.FullCell);
+						yield return new TextAnnotationRenderable(font, centerPos, 0, lineColor, cost.Cost.ToString());
+					}
+				}
+			}
+		}
+
+		bool IRenderAnnotations.SpatiallyPartitionable => false;
+	}
+}

OpenRA.Mods.Common/Traits/World/PathFinder.cs

@@ -12,6 +12,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using OpenRA.Graphics;
 using OpenRA.Mods.Common.Pathfinder;
 using OpenRA.Traits;
 
@@ -23,19 +24,39 @@ namespace OpenRA.Mods.Common.Traits
 	{
 		public override object Create(ActorInitializer init)
 		{
-			return new PathFinder(init.World);
+			return new PathFinder(init.Self);
 		}
 	}
 
-	public class PathFinder : IPathFinder
+	public class PathFinder : IPathFinder, IWorldLoaded
 	{
 		public static readonly List<CPos> NoPath = new List<CPos>(0);
 
-		readonly World world;
+		/// <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>
+		const int DefaultHeuristicWeightPercentage = 125;
 
-		public PathFinder(World world)
+		readonly World world;
+		Dictionary<Locomotor, HierarchicalPathFinder> hierarchicalPathFindersByLocomotor;
+
+		public PathFinder(Actor self)
 		{
-			this.world = world;
+			world = self.World;
+		}
+
+		public IReadOnlyDictionary<CPos, List<GraphConnection>> GetOverlayDataForLocomotor(Locomotor locomotor)
+		{
+			return hierarchicalPathFindersByLocomotor[locomotor].GetOverlayData();
+		}
+
+		public void WorldLoaded(World w, WorldRenderer wr)
+		{
+			// Requires<LocomotorInfo> ensures all Locomotors have been initialized.
+			hierarchicalPathFindersByLocomotor = w.WorldActor.TraitsImplementing<Locomotor>().ToDictionary(
+				locomotor => locomotor,
+				locomotor => new HierarchicalPathFinder(world, locomotor));
 		}
 
 		/// <summary>
@@ -48,7 +69,7 @@ namespace OpenRA.Mods.Common.Traits
 		/// as optimizations are possible for the single source case. Use searches from multiple source cells
 		/// sparingly.
 		/// </remarks>
-		public List<CPos> FindUnitPathToTargetCell(
+		public List<CPos> FindPathToTargetCell(
 			Actor self, IEnumerable<CPos> sources, CPos target, BlockedByActor check,
 			Func<CPos, int> customCost = null,
 			Actor ignoreActor = null,
@@ -58,13 +79,13 @@ namespace OpenRA.Mods.Common.Traits
 			if (sourcesList.Count == 0)
 				return NoPath;
 
-			var locomotor = GetLocomotor(self);
+			var locomotor = GetActorLocomotor(self);
 
 			// If the target cell is inaccessible, bail early.
 			var inaccessible =
 				!world.Map.Contains(target) ||
 				!locomotor.CanMoveFreelyInto(self, target, check, ignoreActor) ||
-				(!(customCost is null) && customCost(target) == PathGraph.PathCostForInvalidPath);
+				(customCost != null && customCost(target) == PathGraph.PathCostForInvalidPath);
 			if (inaccessible)
 				return NoPath;
 
@@ -81,18 +102,14 @@ namespace OpenRA.Mods.Common.Traits
 					return new List<CPos>(2) { target, source };
 				}
 
-				// With one starting point, we can use a bidirectional search.
-				using (var fromTarget = PathSearch.ToTargetCell(
-					world, locomotor, self, new[] { target }, source, check, ignoreActor: ignoreActor))
-				using (var fromSource = PathSearch.ToTargetCell(
-					world, locomotor, self, new[] { source }, target, check, ignoreActor: ignoreActor, inReverse: true))
-					return PathSearch.FindBidiPath(fromTarget, fromSource);
+				// Use a hierarchical path search, which performs a guided bidirectional search.
+				return hierarchicalPathFindersByLocomotor[locomotor].FindPath(
+					self, source, target, check, DefaultHeuristicWeightPercentage, customCost, ignoreActor, laneBias);
 			}
 
-			// With multiple starting points, we can only use a unidirectional search.
-			using (var search = PathSearch.ToTargetCell(
-				world, locomotor, self, sourcesList, target, check, customCost, ignoreActor, laneBias))
-				return search.FindPath();
+			// Use a hierarchical path search, which performs a guided unidirectional search.
+			return hierarchicalPathFindersByLocomotor[locomotor].FindPath(
+				self, sourcesList, target, check, DefaultHeuristicWeightPercentage, customCost, ignoreActor, laneBias);
 		}
 
 		/// <summary>
@@ -101,10 +118,10 @@ namespace OpenRA.Mods.Common.Traits
 		/// The shortest path between a source and a discovered target is returned.
 		/// </summary>
 		/// <remarks>
-		/// Searches with this method are slower than <see cref="FindUnitPathToTargetCell"/> due to the need to search for
+		/// Searches with this method are slower than <see cref="FindPathToTargetCell"/> due to the need to search for
 		/// and discover an acceptable target cell. Use this search sparingly.
 		/// </remarks>
-		public List<CPos> FindUnitPathToTargetCellByPredicate(
+		public List<CPos> FindPathToTargetCellByPredicate(
 			Actor self, IEnumerable<CPos> sources, Func<CPos, bool> targetPredicate, BlockedByActor check,
 			Func<CPos, int> customCost = null,
 			Actor ignoreActor = null,
@@ -112,11 +129,11 @@ namespace OpenRA.Mods.Common.Traits
 		{
 			// With no pre-specified target location, we can only use a unidirectional search.
 			using (var search = PathSearch.ToTargetCellByPredicate(
-				world, GetLocomotor(self), self, sources, targetPredicate, check, customCost, ignoreActor, laneBias))
+				world, GetActorLocomotor(self), self, sources, targetPredicate, check, customCost, ignoreActor, laneBias))
 				return search.FindPath();
 		}
 
-		static Locomotor GetLocomotor(Actor self)
+		static Locomotor GetActorLocomotor(Actor self)
 		{
 			// PERF: This PathFinder trait requires the use of Mobile, so we can be sure that is in use.
 			// We can save some performance by avoiding querying for the Locomotor trait and retrieving it from Mobile.