Merge pull request #103 from patheloper/trunk

[3.2] SnapshotManager#getHighestBlockAt, PathValidationContext now holds the absolute start and target and bStats can now be deactivated

pathetic-api/pom.xml

@@ -7,11 +7,11 @@
     <parent>
         <artifactId>pathetic-main</artifactId>
         <groupId>org.patheloper</groupId>
-        <version>3.1.1</version>
+        <version>3.2</version>
     </parent>
 
     <artifactId>pathetic-api</artifactId>
-    <version>3.1.1</version>
+    <version>3.2</version>
 
     <dependencies>
         <dependency>

pathetic-api/src/main/java/org/patheloper/api/event/package-info.java

@@ -11,32 +11,33 @@
  *
  * <p>For example:
  *
- * <pre>
+ * <pre>{@code
  * // Define a new event
- * public class CustomEvent extends PathingEvent {
- *     private final String message;
+ *  public class CustomEvent extends PathingEvent {
+ *    private final String message;
  *
- *     public CustomEvent(String message) {
- *         this.message = message;
- *     }
+ *    public CustomEvent(String message) {
+ *      this.message = message;
+ *    }
  *
- *     public String getMessage() {
- *         return message;
- *     }
- * }
+ *    public String getMessage() {
+ *      return message;
+ *    }
+ *  }
  *
- * // Define a listener for the new event
- * public class CustomEventListener {
+ *  // Define a listener for the new event
+ *  public class CustomEventListener {
  *
- *     @Subscribe
- *     public void onCustomEvent(CustomEvent event) {
- *         System.out.println("Received custom event with message: " + event.getMessage());
- *     }
- * }
+ *   {@literal @}Subscribe
+ *   public void onCustomEvent(CustomEvent event) {
+ *     System.out.println("Received custom event with message: " + event.getMessage());
+ *    }
+ *  }
  *
  * // Register the listener and raise the event
  * EventPublisher.registerListener(new CustomEventListener());
  * EventPublisher.raiseEvent(new CustomEvent("Hello, world!"));
- * </pre>
+ *
+ * }</pre>
  */
 package org.patheloper.api.event;

pathetic-api/src/main/java/org/patheloper/api/pathing/configuration/PathfinderConfiguration.java

@@ -78,14 +78,15 @@ public class PathfinderConfiguration {
    * 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 org.patheloper.api.pathing.filter.PathFilterStage}s into the validation
-   * process. Shared filters must still be passed.
+   * <p>Setting this to true will no longer take the {@link
+   * org.patheloper.api.pathing.filter.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;
+  @Experimental @Builder.Default boolean prioritizing = false;
 
   /**
    * The set of weights used to calculate heuristics within the A* algorithm. These influence the
@@ -95,6 +96,16 @@ public class PathfinderConfiguration {
    */
   @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.
    */

pathetic-api/src/main/java/org/patheloper/api/pathing/filter/PathValidationContext.java

@@ -4,11 +4,45 @@
 import org.patheloper.api.snapshot.SnapshotManager;
 import org.patheloper.api.wrapper.PathPosition;
 
-/** A parameter object for the {@link PathFilter#filter} method. */
+/**
+ * PathValidationContext is a data container used during the pathfinding process to provide relevant
+ * contextual information needed for evaluating path validity.
+ *
+ * <p>This context is passed to {@link PathFilter#filter} methods during the pathfinding process and
+ * allows filters to validate or invalidate nodes based on the provided context.
+ */
 @Value
 public class PathValidationContext {
 
+  /**
+   * The current position being evaluated in the pathfinding process. This represents the position
+   * that is being validated by the filter to determine if it can be part of a valid path.
+   */
   PathPosition position;
+
+  /**
+   * The parent position of the current position. This is the previous node from which the current
+   * position was reached. It is used to trace the path and ensure logical continuity between nodes.
+   */
   PathPosition parent;
+
+  /**
+   * The absolute start position of the pathfinding process. This represents the original starting
+   * point of the path and remains constant throughout the algorithm, providing a stable reference.
+   */
+  PathPosition absoluteStart;
+
+  /**
+   * The absolute target position of the pathfinding process. This is the final goal or destination
+   * that the pathfinding algorithm is trying to reach. Like the start, it remains constant and
+   * provides a clear end-point for the path.
+   */
+  PathPosition absoluteTarget;
+
+  /**
+   * The snapshot manager provides access to world data, such as block information, in the context
+   * of the pathfinding process. It is used to retrieve block data from the world at different
+   * positions during path validation.
+   */
   SnapshotManager snapshotManager;
 }

pathetic-api/src/main/java/org/patheloper/api/snapshot/SnapshotManager.java

@@ -18,4 +18,14 @@ public interface SnapshotManager {
    * @return {@link PathBlock} the block.
    */
   PathBlock getBlock(PathPosition position);
+
+  /**
+   * Gets the highest block at the given position
+   *
+   * @api.Note If the pathfinder is not permitted to load chunks, this method will return null if
+   *     the chunk is not loaded.
+   * @param position the position to get as block-form
+   * @return {@link PathBlock} the block.
+   */
+  PathBlock getHighestBlockAt(PathPosition position);
 }

pathetic-example/pom.xml

@@ -7,11 +7,11 @@
     <parent>
         <artifactId>pathetic-main</artifactId>
         <groupId>org.patheloper</groupId>
-        <version>3.1.1</version>
+        <version>3.2</version>
     </parent>
 
     <artifactId>pathetic-example</artifactId>
-    <version>3.1.1</version>
+    <version>3.2</version>
     <packaging>jar</packaging>
 
     <name>PatheticTest</name>
@@ -73,7 +73,7 @@
         <dependency>
             <groupId>org.patheloper</groupId>
             <artifactId>pathetic-mapping</artifactId>
-            <version>3.1.1</version>
+            <version>3.2</version>
         </dependency>
     </dependencies>
 </project>

pathetic-mapping/pom.xml

@@ -5,12 +5,12 @@
     <parent>
         <artifactId>pathetic-main</artifactId>
         <groupId>org.patheloper</groupId>
-        <version>3.1.1</version>
+        <version>3.2</version>
     </parent>
     <modelVersion>4.0.0</modelVersion>
 
     <artifactId>pathetic-mapping</artifactId>
-    <version>3.1.1</version>
+    <version>3.2</version>
 
     <build>
         <plugins>
@@ -34,7 +34,7 @@
         <dependency>
             <groupId>org.patheloper</groupId>
             <artifactId>pathetic-model</artifactId>
-            <version>3.1.1</version>
+            <version>3.2</version>
             <scope>compile</scope>
         </dependency>
         <dependency>

pathetic-model/pom.xml

@@ -6,11 +6,11 @@
     <parent>
         <artifactId>pathetic-main</artifactId>
         <groupId>org.patheloper</groupId>
-        <version>3.1.1</version>
+        <version>3.2</version>
     </parent>
 
     <artifactId>pathetic-model</artifactId>
-    <version>3.1.1</version>
+    <version>3.2</version>
 
     <build>
         <resources>
@@ -100,13 +100,13 @@
         <dependency>
             <groupId>org.patheloper</groupId>
             <artifactId>pathetic-api</artifactId>
-            <version>3.1.1</version>
+            <version>3.2</version>
             <scope>compile</scope>
         </dependency>
         <dependency>
             <groupId>org.patheloper</groupId>
             <artifactId>pathetic-nms</artifactId>
-            <version>3.1.1</version>
+            <version>3.2</version>
             <scope>compile</scope>
         </dependency>
         <dependency>

pathetic-model/src/main/java/org/patheloper/BStatsHandler.java

@@ -9,10 +9,14 @@
 @UtilityClass
 public class BStatsHandler {
 
+  private Metrics metrics;
+
   private int paths;
 
-  public void init(JavaPlugin javaPlugin) {
-    Metrics metrics = new Metrics(javaPlugin, 20529);
+  private void init(JavaPlugin javaPlugin) {
+    if (metrics != null) return;
+
+    metrics = new Metrics(javaPlugin, 20529);
     metrics.addCustomChart(
         new SingleLineChart(
             "total_paths",
@@ -24,7 +28,15 @@ public void init(JavaPlugin javaPlugin) {
     metrics.addCustomChart(new SimplePie("pathetic-model_version", Pathetic::getModelVersion));
   }
 
+  private void makeSureBStatsIsInitialized() {
+    if (!Pathetic.isInitialized())
+      throw new IllegalStateException("Pathetic has not been initialized yet");
+
+    init(Pathetic.getPluginInstance());
+  }
+
   public synchronized void increasePathCount() {
+    makeSureBStatsIsInitialized();
     paths++;
   }
 }

pathetic-model/src/main/java/org/patheloper/Pathetic.java

@@ -35,8 +35,6 @@ public static void initialize(JavaPlugin javaPlugin) {
     instance = javaPlugin;
     Bukkit.getPluginManager().registerEvents(new ChunkInvalidateListener(), javaPlugin);
 
-    BStatsHandler.init(javaPlugin);
-
     loadModelVersion();
 
     if (BukkitVersionUtil.getVersion().isUnder(16, 0)

pathetic-model/src/main/java/org/patheloper/model/pathing/pathfinder/AStarPathfinder.java

@@ -89,6 +89,8 @@ private double calculatePriorityAdjustment(Node node, List<PathFilterStage> filt
               new PathValidationContext(
                   node.getPosition(),
                   node.getParent() != null ? node.getParent().getPosition() : null,
+                  node.getStart(),
+                  node.getTarget(),
                   snapshotManager));
 
       if (filterResult) {
@@ -248,6 +250,8 @@ private boolean doAllFiltersPass(List<PathFilter> filters, Node node) {
           new PathValidationContext(
               node.getPosition(),
               node.getParent() != null ? node.getParent().getPosition() : null,
+              node.getStart(),
+              node.getTarget(),
               snapshotManager);
 
       if (!filter.filter(context)) {
@@ -265,6 +269,8 @@ private boolean doAnyFilterStagePass(List<PathFilterStage> filterStages, Node no
           new PathValidationContext(
               node.getPosition(),
               node.getParent() != null ? node.getParent().getPosition() : null,
+              node.getStart(),
+              node.getTarget(),
               snapshotManager))) {
         return true;
       }

pathetic-model/src/main/java/org/patheloper/model/pathing/pathfinder/AbstractPathfinder.java

@@ -157,7 +157,7 @@ private CompletionStage<PathfinderResult> initiatePathing(
       PathPosition target,
       List<PathFilter> filters,
       List<PathFilterStage> filterStages) {
-    BStatsHandler.increasePathCount();
+    pushToBStatsIfActivated();
     return pathfinderConfiguration.isAsync()
         ? CompletableFuture.supplyAsync(
                 () -> executePathingAndCleanupFilters(start, target, filters, filterStages),
@@ -167,6 +167,12 @@ private CompletionStage<PathfinderResult> initiatePathing(
         : initiateSyncPathing(start, target, filters, filterStages);
   }
 
+  private void pushToBStatsIfActivated() {
+    if (pathfinderConfiguration.isBStats()) {
+      BStatsHandler.increasePathCount();
+    }
+  }
+
   private PathfinderResult executePathing(
       PathPosition start,
       PathPosition target,