From 875f01c358279e334d38c2e304f31a7c4b6aee44 Mon Sep 17 00:00:00 2001 From: Brady Date: Mon, 8 Oct 2018 23:29:16 -0500 Subject: [PATCH] More comprehensive IPath javadocs --- .../baritone/api/pathing/path/CutoffPath.java | 2 +- .../java/baritone/api/pathing/path/IPath.java | 54 +++++++++++++++---- .../pathing/calc/AbstractNodeCostSearch.java | 2 +- src/main/java/baritone/pathing/calc/Path.java | 2 +- 4 files changed, 47 insertions(+), 13 deletions(-) diff --git a/src/api/java/baritone/api/pathing/path/CutoffPath.java b/src/api/java/baritone/api/pathing/path/CutoffPath.java index a702b7fd..1fcbdadc 100644 --- a/src/api/java/baritone/api/pathing/path/CutoffPath.java +++ b/src/api/java/baritone/api/pathing/path/CutoffPath.java @@ -34,7 +34,7 @@ public class CutoffPath implements IPath { private final Goal goal; - public CutoffPath(IPath prev, int lastPositionToInclude) { + CutoffPath(IPath prev, int lastPositionToInclude) { path = prev.positions().subList(0, lastPositionToInclude + 1); movements = prev.movements().subList(0, lastPositionToInclude + 1); numNodes = prev.getNumNodesConsidered(); diff --git a/src/api/java/baritone/api/pathing/path/IPath.java b/src/api/java/baritone/api/pathing/path/IPath.java index 2d4b08e3..275f0f97 100644 --- a/src/api/java/baritone/api/pathing/path/IPath.java +++ b/src/api/java/baritone/api/pathing/path/IPath.java @@ -18,6 +18,7 @@ package baritone.api.pathing.path; import baritone.api.BaritoneAPI; +import baritone.api.Settings; import baritone.api.pathing.goals.Goal; import baritone.api.pathing.movement.IMovement; import baritone.api.utils.BetterBlockPos; @@ -28,7 +29,7 @@ import net.minecraft.world.chunk.EmptyChunk; import java.util.List; /** - * @author leijurv + * @author leijurv, Brady */ public interface IPath { @@ -37,12 +38,16 @@ public interface IPath { * movements.get(i).getSrc() should equal positions.get(i) * movements.get(i).getDest() should equal positions.get(i+1) * movements.size() should equal positions.size()-1 + * + * @return All of the movements to carry out */ List movements(); /** * All positions along the way. * Should begin with the same as getSrc and end with the same as getDest + * + * @return All of the positions along this path */ List positions(); @@ -50,10 +55,10 @@ public interface IPath { * This path is actually going to be executed in the world. Do whatever additional processing is required. * (as opposed to Path objects that are just constructed every frame for rendering) */ - default void postprocess() {} + default void postProcess() {} /** - * Number of positions in this path + * Returns the number of positions in this path. Equivalent to {@code positions().size()}. * * @return Number of positions in this path */ @@ -62,27 +67,45 @@ public interface IPath { } /** - * What goal was this path calculated towards? - * - * @return + * @return The goal that this path was calculated towards */ Goal getGoal(); /** - * Where does this path start + * Returns the number of nodes that were considered during calculation before + * this path was found. + * + * @return The number of nodes that were considered before finding this path + */ + int getNumNodesConsidered(); + + /** + * Returns the start position of this path. This is the first element in the + * {@link List} that is returned by {@link IPath#positions()}. + * + * @return The start position of this path */ default BetterBlockPos getSrc() { return positions().get(0); } /** - * Where does this path end + * Returns the end position of this path. This is the last element in the + * {@link List} that is returned by {@link IPath#positions()}. + * + * @return The end position of this path. */ default BetterBlockPos getDest() { List pos = positions(); return pos.get(pos.size() - 1); } + /** + * Returns the estimated number of ticks to complete the path from the given node index. + * + * @param pathPosition The index of the node we're calculating from + * @return The estimated number of ticks remaining frm the given position + */ default double ticksRemainingFrom(int pathPosition) { double sum = 0; //this is fast because we aren't requesting recalculation, it's just cached @@ -92,8 +115,11 @@ public interface IPath { return sum; } - int getNumNodesConsidered(); - + /** + * Cuts off this path at the loaded chunk border, and returns the {@link CutoffResult}. + * + * @return The result of this cut-off operation + */ default CutoffResult cutoffAtLoadedChunks() { for (int i = 0; i < positions().size(); i++) { BlockPos pos = positions().get(i); @@ -104,6 +130,14 @@ public interface IPath { return CutoffResult.preservePath(this); } + /** + * Cuts off this path using the min length and cutoff factor settings, and returns the {@link CutoffResult}. + * + * @see Settings#pathCutoffMinimumLength + * @see Settings#pathCutoffFactor + * + * @return The result of this cut-off operation + */ default CutoffResult staticCutoff(Goal destination) { if (length() < BaritoneAPI.getSettings().pathCutoffMinimumLength.get()) { return CutoffResult.preservePath(this); diff --git a/src/main/java/baritone/pathing/calc/AbstractNodeCostSearch.java b/src/main/java/baritone/pathing/calc/AbstractNodeCostSearch.java index adac5e28..3c033a93 100644 --- a/src/main/java/baritone/pathing/calc/AbstractNodeCostSearch.java +++ b/src/main/java/baritone/pathing/calc/AbstractNodeCostSearch.java @@ -89,7 +89,7 @@ public abstract class AbstractNodeCostSearch implements IPathFinder { this.cancelRequested = false; try { Optional path = calculate0(timeout); - path.ifPresent(IPath::postprocess); + path.ifPresent(IPath::postProcess); isFinished = true; return path; } finally { diff --git a/src/main/java/baritone/pathing/calc/Path.java b/src/main/java/baritone/pathing/calc/Path.java index ddd51dc2..4983de54 100644 --- a/src/main/java/baritone/pathing/calc/Path.java +++ b/src/main/java/baritone/pathing/calc/Path.java @@ -150,7 +150,7 @@ class Path implements IPath { } @Override - public void postprocess() { + public void postProcess() { if (verified) { throw new IllegalStateException(); }