first step to pave pathetic the path to universality WiP

README.md

@@ -3,8 +3,8 @@
 
 <h1>Pathetic - A Pathfinding library for Minecraft</h1>
 
-<p>A high-performance, backwards-compatible, and asynchronous easy-to-use pathfinding library written in Java.
-<br> Pathetic leverages the <b>A* algorithm</b> with customizable heuristics for real-time pathfinding in <b>Spigot/Paper </b>environments.</p>
+<p>A high-performance, backwards-compatible, and asynchronous easy-to-use pathfinding library written in Java for 3D environments.
+<br> Pathetic leverages the <b>A* algorithm</b> with customizable heuristics for real-time pathfinding.</p>
 
 <h2>Key Features</h2>
 
@@ -23,7 +23,7 @@
 
 <h2>Installation</h2>
 
-To integrate pathetic into your project, follow the following steps:
+To integrate pathetic into your bukkit project, follow the following steps:
 <br>
 *(We advise you to relocate pathetic)*
 
@@ -40,7 +40,7 @@ To integrate pathetic into your project, follow the following steps:
 
 <dependency>
     <groupId>com.github.Metaphoriker.pathetic</groupId>
-    <artifactId>pathetic-mapping</artifactId>
+    <artifactId>pathetic-bukkit</artifactId>
     <version>VERSION</version>
 </dependency>
 ```
@@ -55,13 +55,47 @@ allprojects {
 }
 
 dependencies {
-    implementation 'com.github.Metaphoriker.pathetic:pathetic-mapping:VERSION'
+    implementation 'com.github.Metaphoriker.pathetic:pathetic-bukkit:VERSION'
+}
+```
+
+<h3>Manual Pathetic</h3>
+If you want to leverage pathetic for your own implementation, you can use the following dependency:
+
+<h4>Maven</h4>
+
+```xml
+<repositories>
+    <repository>
+        <id>jitpack.io</id>
+        <url>https://jitpack.io</url>
+    </repository>
+</repositories>
+
+<dependency>
+    <groupId>de.metaphoriker</groupId>
+    <artifactId>pathetic-engine</artifactId>
+    <version>VERSION</version>
+</dependency>
+```
+
+<h4>Gradle</h4>
+
+```groovy
+allprojects {
+    repositories {
+        maven { url 'https://jitpack.io' }
+    }
+}
+
+dependencies {
+    implementation 'de.metaphoriker:pathetic-engine:VERSION'
 }
 ```
 
 <h2>Example Usage</h2>
 
-<p>See the <a href="https://github.com/Metaphoriker/pathetic/tree/trunk/pathetic-example">pathetic-example</a> module for a detailed example usage.</p>
+<p>See the <a href="https://github.com/Metaphoriker/pathetic/tree/trunk/pathetic-example">pathetic-example</a> module for a detailed bukkit example.</p>
 
 <h2>Documentation</h2>
 

pathetic-api/pom.xml

@@ -14,13 +14,11 @@
     <version>3.3.1</version>
 
     <dependencies>
-        <dependency>
-            <groupId>org.spigotmc</groupId>
-            <artifactId>spigot-api</artifactId>
-        </dependency>
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
+            <version>1.18.36</version>
+            <scope>provided</scope>
         </dependency>
     </dependencies>
 </project>

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

@@ -2,8 +2,8 @@
 
 import java.util.List;
 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;
@@ -27,7 +27,7 @@ public interface Pathfinder {
   CompletionStage<PathfinderResult> findPath(
       @NonNull PathPosition start,
       @NonNull PathPosition target,
-      @Nullable List<@NonNull PathFilter> filters);
+      List<@NonNull PathFilter> filters);
 
   /**
    * Tries to find a Path between the two {@link PathPosition}'s provided with the given
@@ -52,8 +52,8 @@ CompletionStage<PathfinderResult> findPath(
   CompletionStage<PathfinderResult> findPath(
       @NonNull PathPosition start,
       @NonNull PathPosition target,
-      @Nullable List<PathFilter> sharedFilters,
-      @Nullable List<@NonNull PathFilterStage> filterStages);
+      List<@NonNull PathFilter> sharedFilters,
+      List<@NonNull PathFilterStage> filterStages);
 
   /**
    * Aborts the running pathfinding process.
@@ -62,4 +62,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/PathfinderFactory.java

@@ -0,0 +1,30 @@
+package de.metaphoriker.pathetic.api.pathing;
+
+import de.metaphoriker.pathetic.api.pathing.configuration.PathfinderConfiguration;
+
+/**
+ * A factory class for creating {@link Pathfinder} instances.
+ *
+ * @param <I> The type of {@link PathfinderInitializer} used to initialize the pathfinder.
+ */
+public abstract class PathfinderFactory<I extends PathfinderInitializer> {
+
+  protected final I initializer;
+
+  /**
+   * Creates a new {@link PathfinderFactory} with the given initializer.
+   *
+   * @param initializer The initializer to use for initializing the pathfinder.
+   */
+  public PathfinderFactory(I initializer) {
+    this.initializer = initializer;
+  }
+
+  /**
+   * Creates a new {@link Pathfinder} instance with the given configuration.
+   *
+   * @param configuration The configuration for the pathfinder.
+   * @return A new {@link Pathfinder} instance.
+   */
+  public abstract Pathfinder createPathfinder(PathfinderConfiguration configuration);
+}

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

@@ -0,0 +1,17 @@
+package de.metaphoriker.pathetic.api.pathing;
+
+import de.metaphoriker.pathetic.api.pathing.configuration.PathfinderConfiguration;
+
+/**
+ * An interface for initializing {@link Pathfinder} instances.
+ */
+public interface PathfinderInitializer {
+
+  /**
+   * Initializes the given {@link Pathfinder} with the given {@link PathfinderConfiguration}.
+   *
+   * @param pathfinder The pathfinder to initialize.
+   * @param configuration The configuration for the pathfinder.
+   */
+  void initialize(Pathfinder pathfinder, PathfinderConfiguration configuration);
+}

pathetic-api/src/main/java/de/metaphoriker/pathetic/api/pathing/configuration/PathfinderConfiguration.java

@@ -1,10 +1,5 @@
 package de.metaphoriker.pathetic.api.pathing.configuration;
 
-import de.metaphoriker.pathetic.api.annotation.Experimental;
-import de.metaphoriker.pathetic.api.pathing.Pathfinder;
-import de.metaphoriker.pathetic.api.pathing.filter.PathFilterStage;
-import de.metaphoriker.pathetic.api.wrapper.PathPosition;
-import java.util.List;
 import lombok.AccessLevel;
 import lombok.Builder;
 import lombok.Getter;
@@ -30,7 +25,7 @@
    *
    * @default 5000
    */
   @Builder.Default int maxIterations = 5000;
 
   /**
    * The maximum permissible length of a calculated path (in blocks). Use this to constrain long
@@ -45,43 +40,19 @@
    */
   boolean async;
 
-  /**
-   * If set to true, the pathfinding process will terminate immediately if either the start or
-   * target or both are unreachable.
-   *
-   * <p>NOTE: This prevents fallback strategies.
-   * @deprecated Will be removed in future releases
-   */
-  @Deprecated
-  boolean allowingFailFast;
-
   /**
    * If pathfinding fails, this parameter determines whether the algorithm should fall back to the
    * last successfully calculated path. This can help maintain progress, but might use an outdated
    * path.
    */
-  boolean allowingFallback;
+  @Builder.Default boolean allowingFallback = true;
 
   /**
    * Controls whether chunks should be loaded or generated as needed during the pathfinding process.
    * This is essential for exploring uncharted areas, but may impact performance.
    */
   boolean loadingChunks;
 
-  /**
-   * Determines whether the pathfinding algorithm should see PathFilterStages as prioritization,
-   * instead of filtering. This means that the pathfinding algorithm will prioritize paths that pass
-   * the filters over paths that do not.
-   *
-   * <p>Setting this to true will no longer take the {@link PathFilterStage}s into the validation
-   * process. Shared filters must still be passed.
-   *
-   * <p>{@link Pathfinder#findPath(PathPosition, PathPosition, List, List)}
-   *
-   * @experimental This feature is experimental and may be subject to change.
-   */
-  @Experimental @Builder.Default boolean prioritizing = false;
-
   /**
    * The set of weights used to calculate heuristics within the A* algorithm. These influence the
    * pathfinding priority for distance, elevation changes, smoothness, and diagonal movement.
@@ -90,16 +61,6 @@
    */
   @Builder.Default HeuristicWeights heuristicWeights = HeuristicWeights.NATURAL_PATH_WEIGHTS;
 
-  /**
-   * Determines whether the pathfinding algorithm should collect statistics about the pathfinding
-   * process. This can be useful for debugging and performance tuning.
-   *
-   * <p>Help us improve the API by providing feedback with the collected statistics!
-   *
-   * @default true
-   */
-  @Builder.Default boolean bStats = true;
-
   /**
    * @return A new {@link PathfinderConfiguration} with default parameters but async.
    */
@@ -129,7 +90,6 @@
         .maxIterations(pathfinderConfiguration.maxIterations)
         .maxLength(pathfinderConfiguration.maxLength)
         .async(pathfinderConfiguration.async)
-        .allowingFailFast(pathfinderConfiguration.allowingFailFast)
         .allowingFallback(pathfinderConfiguration.allowingFallback)
         .loadingChunks(pathfinderConfiguration.loadingChunks)
         .heuristicWeights(pathfinderConfiguration.heuristicWeights)