Expose reachRange argument in findPath for PathFinder (#13026)

Author: Doc94

paper-api/src/main/java/com/destroystokyo/paper/entity/Pathfinder.java

@@ -5,6 +5,7 @@
 import org.bukkit.entity.LivingEntity;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Mob;
+import org.checkerframework.checker.index.qual.NonNegative;
 import org.jspecify.annotations.NullMarked;
 import org.jspecify.annotations.Nullable;
 
@@ -43,7 +44,20 @@ public interface Pathfinder {
      * @param loc Location to navigate to
      * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
      */
-    @Nullable PathResult findPath(Location loc);
+    default @Nullable PathResult findPath(Location loc) {
+        return this.findPath(loc, 0);
+    }
+
+    /**
+     * Calculates a destination for the Entity to navigate to, but does not set it
+     * as the current target. Useful for calculating what would happen before setting it.
+     *
+     * @param loc Location to navigate to
+     * @param reachRange The <a href="https://cp-algorithms.com/geometry/manhattan-distance.html">Manhattan-distance</a> threshold
+     *                   from the target position at which the path is considered reached, where {@code 0} requires the exact target position
+     * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
+     */
+    @Nullable PathResult findPath(final Location loc, final @NonNegative int reachRange);
 
     /**
      * Calculates a destination for the Entity to navigate to reach the target entity,
@@ -76,7 +90,26 @@ default PathResult findPath(LivingEntity target) {
      * @param target the Entity to navigate to
      * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
      */
-    @Nullable PathResult findPath(Entity target);
+    default @Nullable PathResult findPath(Entity target) {
+        return this.findPath(target, 0);
+    }
+
+    /**
+     * Calculates a destination for the Entity to navigate to to reach the target entity,
+     * but does not set it as the current target.
+     * Useful for calculating what would happen before setting it.
+     * <p>
+     * The behavior of this PathResult is subject to the games pathfinding rules, and may
+     * result in the pathfinding automatically updating to follow the target Entity.
+     * <p>
+     * However, this behavior is not guaranteed, and is subject to the games behavior.
+     *
+     * @param target the Entity to navigate to
+     * @param reachRange The <a href="https://cp-algorithms.com/geometry/manhattan-distance.html">Manhattan-distance</a> threshold
+     *                   from the target position at which the path is considered reached, where {@code 0} requires the exact target position
+     * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
+     */
+    @Nullable PathResult findPath(final Entity target, final @NonNegative int reachRange);
 
     /**
      * Calculates a destination for the Entity to navigate to, and sets it with default speed

paper-server/src/main/java/com/destroystokyo/paper/entity/PaperPathfinder.java

@@ -49,17 +49,19 @@ public PathResult getCurrentPath() {
 
     @Nullable
     @Override
-    public PathResult findPath(Location loc) {
+    public PathResult findPath(final Location loc, final int reachRange) {
         Preconditions.checkArgument(loc != null, "Location can not be null");
-        Path path = this.entity.getNavigation().createPath(loc.getX(), loc.getY(), loc.getZ(), 0);
+        Preconditions.checkArgument(reachRange >= 0, "Reach range can not be negative");
+        Path path = this.entity.getNavigation().createPath(loc.getX(), loc.getY(), loc.getZ(), reachRange);
         return path != null ? new PaperPathResult(path) : null;
     }
 
     @Nullable
     @Override
-    public PathResult findPath(Entity target) {
+    public PathResult findPath(final Entity target, final int reachRange) {
         Preconditions.checkArgument(target != null, "Target can not be null");
-        Path path = this.entity.getNavigation().createPath(((CraftEntity) target).getHandle(), 0);
+        Preconditions.checkArgument(reachRange >= 0, "Reach range can not be negative");
+        Path path = this.entity.getNavigation().createPath(((CraftEntity) target).getHandle(), reachRange);
         return path != null ? new PaperPathResult(path) : null;
     }