feat: implemented a way to hook into the pathfinding process

pathetic-api/src/main/java/de/metaphoriker/pathetic/api/pathing/Pathfinder.java

@@ -4,6 +4,7 @@
 import java.util.concurrent.CompletionStage;
 import javax.annotation.Nullable;
 
+import de.metaphoriker.pathetic.api.pathing.hook.PathfinderHook;
 import de.metaphoriker.pathetic.api.pathing.result.PathState;
 import lombok.NonNull;
 import de.metaphoriker.pathetic.api.pathing.filter.PathFilter;
@@ -62,4 +63,11 @@ CompletionStage<PathfinderResult> findPath(
    * will be {@link PathState#ABORTED}.
    */
   void abort();
+
+  /**
+   * Registers a {@link PathfinderHook} that will be called on every step of the pathfinding process.
+   * This can be used to modify the pathfinding process or to collect data.
+   * @param hook The hook to register.
+   */
+  void registerPathfindingHook(PathfinderHook hook);
 }

pathetic-api/src/main/java/de/metaphoriker/pathetic/api/pathing/hook/PathfinderHook.java

@@ -0,0 +1,14 @@
+package de.metaphoriker.pathetic.api.pathing.hook;
+
+/**
+ * Interface for hooks that are called during the pathfinding process.
+ */
+public interface PathfinderHook {
+
+  /**
+   * Called on each step of the pathfinding process.
+   *
+   * @param pathfindingContext the context of the current pathfinding step
+   */
+  void onPathfindingStep(PathfindingContext pathfindingContext);
+}

pathetic-api/src/main/java/de/metaphoriker/pathetic/api/pathing/hook/PathfindingContext.java

@@ -0,0 +1,16 @@
+package de.metaphoriker.pathetic.api.pathing.hook;
+
+import de.metaphoriker.pathetic.api.wrapper.Depth;
+import lombok.Value;
+
+/**
+ * Context for the current step of the pathfinding process.
+ */
+@Value
+public class PathfindingContext {
+
+  /**
+   * The depth of the current pathfinding step.
+   */
+  Depth depth;
+}

pathetic-model/src/main/java/de/metaphoriker/pathetic/model/pathing/pathfinder/Depth.java → pathetic-api/src/main/java/de/metaphoriker/pathetic/api/wrapper/Depth.java

@@ -1,4 +1,4 @@
-package de.metaphoriker.pathetic.model.pathing.pathfinder;
+package de.metaphoriker.pathetic.api.wrapper;
 
 import lombok.EqualsAndHashCode;
 import lombok.Getter;

pathetic-model/src/main/java/de/metaphoriker/pathetic/model/pathing/pathfinder/AStarPathfinder.java

@@ -4,14 +4,14 @@
 import de.metaphoriker.pathetic.api.pathing.filter.PathFilter;
 import de.metaphoriker.pathetic.api.pathing.filter.PathFilterStage;
 import de.metaphoriker.pathetic.api.pathing.filter.PathValidationContext;
+import de.metaphoriker.pathetic.api.wrapper.Depth;
 import de.metaphoriker.pathetic.api.wrapper.PathPosition;
 import de.metaphoriker.pathetic.api.wrapper.PathVector;
 import de.metaphoriker.pathetic.model.pathing.Node;
 import de.metaphoriker.pathetic.model.pathing.Offset;
 import de.metaphoriker.pathetic.util.ExpiringHashMap;
 import de.metaphoriker.pathetic.util.GridRegionData;
 import de.metaphoriker.pathetic.util.Tuple3;
-import de.metaphoriker.pathetic.util.WatchdogUtil;
 import java.util.*;
 import org.jheaps.tree.FibonacciHeap;
 
@@ -41,18 +41,10 @@ protected void tick(
       List<PathFilter> filters,
       List<PathFilterStage> filterStages) {
 
-    tickWatchdogIfNeeded(depth);
-
     evaluateNewNodes(nodeQueue, examinedPositions, currentNode, filters, filterStages);
     depth.increment();
   }
 
-  private void tickWatchdogIfNeeded(Depth depth) {
-    if (depth.getDepth() % 500 == 0) {
-      WatchdogUtil.tickWatchdog();
-    }
-  }
-
   private void evaluateNewNodes(
       FibonacciHeap<Double, Node> nodeQueue,
       Set<PathPosition> examinedPositions,

pathetic-model/src/main/java/de/metaphoriker/pathetic/model/pathing/pathfinder/AbstractPathfinder.java

@@ -1,19 +1,5 @@
 package de.metaphoriker.pathetic.model.pathing.pathfinder;
 
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.HashSet;
-import java.util.LinkedHashSet;
-import java.util.List;
-import java.util.Optional;
-import java.util.Set;
-import java.util.concurrent.CompletableFuture;
-import java.util.concurrent.CompletionStage;
-import java.util.concurrent.ExecutorService;
-import java.util.concurrent.Executors;
-import javax.annotation.Nullable;
-import lombok.NonNull;
-import org.jheaps.tree.FibonacciHeap;
 import de.metaphoriker.pathetic.BStatsHandler;
 import de.metaphoriker.pathetic.Pathetic;
 import de.metaphoriker.pathetic.api.event.EventPublisher;
@@ -23,16 +9,33 @@
 import de.metaphoriker.pathetic.api.pathing.configuration.PathfinderConfiguration;
 import de.metaphoriker.pathetic.api.pathing.filter.PathFilter;
 import de.metaphoriker.pathetic.api.pathing.filter.PathFilterStage;
+import de.metaphoriker.pathetic.api.pathing.hook.PathfinderHook;
+import de.metaphoriker.pathetic.api.pathing.hook.PathfindingContext;
 import de.metaphoriker.pathetic.api.pathing.result.Path;
 import de.metaphoriker.pathetic.api.pathing.result.PathState;
 import de.metaphoriker.pathetic.api.pathing.result.PathfinderResult;
 import de.metaphoriker.pathetic.api.snapshot.SnapshotManager;
+import de.metaphoriker.pathetic.api.wrapper.Depth;
 import de.metaphoriker.pathetic.api.wrapper.PathPosition;
 import de.metaphoriker.pathetic.model.pathing.Node;
 import de.metaphoriker.pathetic.model.pathing.result.PathImpl;
 import de.metaphoriker.pathetic.model.pathing.result.PathfinderResultImpl;
 import de.metaphoriker.pathetic.model.snapshot.FailingSnapshotManager;
 import de.metaphoriker.pathetic.util.ErrorLogger;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import javax.annotation.Nullable;
+import lombok.NonNull;
+import org.jheaps.tree.FibonacciHeap;
 
 /**
  * The AbstractPathfinder class provides a skeletal implementation of the Pathfinder interface and
@@ -59,6 +62,8 @@ abstract class AbstractPathfinder implements Pathfinder {
     Pathetic.addShutdownListener(PATHING_EXECUTOR::shutdown);
   }
 
+  private final Set<PathfinderHook> pathfinderHooks = new HashSet<>();
+
   protected final PathfinderConfiguration pathfinderConfiguration;
   protected final SnapshotManager snapshotManager;
 
@@ -111,9 +116,13 @@ public void abort() {
     this.aborted = true;
   }
 
+  @Override
+  public void registerPathfindingHook(PathfinderHook hook) {
+    pathfinderHooks.add(hook);
+  }
+
   private boolean shouldSkipPathing(PathPosition start, PathPosition target) {
-    return !isSameEnvironment(start, target)
-        || isSameBlock(start, target);
+    return !isSameEnvironment(start, target) || isSameBlock(start, target);
   }
 
   private boolean isSameEnvironment(PathPosition start, PathPosition target) {
@@ -162,6 +171,9 @@ private PathfinderResult executePathing(
       while (!nodeQueue.isEmpty()
           && depth.getDepth() <= pathfinderConfiguration.getMaxIterations()) {
 
+        pathfinderHooks.forEach(
+            hook -> hook.onPathfindingStep(new PathfindingContext(depth)));
+
         if (isAborted()) return abortedPathing(fallbackNode);
 
         Node currentNode = nodeQueue.deleteMin().getValue();

pathetic-model/src/main/java/de/metaphoriker/pathetic/model/pathing/pathfinder/SpigotPathfindingHook.java

@@ -0,0 +1,20 @@
+package de.metaphoriker.pathetic.model.pathing.pathfinder;
+
+import de.metaphoriker.pathetic.api.pathing.hook.PathfinderHook;
+import de.metaphoriker.pathetic.api.pathing.hook.PathfindingContext;
+import de.metaphoriker.pathetic.api.wrapper.Depth;
+import de.metaphoriker.pathetic.util.WatchdogUtil;
+
+public class SpigotPathfindingHook implements PathfinderHook {
+
+  @Override
+  public void onPathfindingStep(PathfindingContext pathfindingContext) {
+    tickWatchdogIfNeeded(pathfindingContext.getDepth());
+  }
+
+  private void tickWatchdogIfNeeded(Depth depth) {
+    if (depth.getDepth() % 500 == 0) {
+      WatchdogUtil.tickWatchdog();
+    }
+  }
+}