Pathfinder.java

package com.destroystokyo.paper.entity;

import org.bukkit.Location;
import org.bukkit.entity.LivingEntity;
import org.bukkit.entity.Mob;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.List;

/**
 * Handles pathfinding operations for an Entity
 */
public interface Pathfinder {
    /**
     *
     * @return The entity that is controlled by this pathfinder
     */
    Mob getEntity();

    /**
     * If the entity is currently trying to navigate to a destination, this will return true
     * @return true if the entity is navigating to a destination
     */
    boolean hasDestination();

    /**
     * @return The location the entity is trying to navigate to, or null if there is no destination
     */
    @Nullable PathResult getCurrentDestination();

    /**
     * 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
     * @return The closest Location the Entity can get to for this navigation, or null if no path could be calculated
     */
    @Nullable PathResult calculateDestination(Location loc);

    /**
     * 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.
     *
     * 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.
     *
     * However, this behavior is not guaranteed, and is subject to the games behavior.
     *
     * @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 calculateDestination(LivingEntity target);

    /**
     * Calculates a destination for the Entity to navigate to, and sets it with default speed
     * as the current target.
     * @param loc Location to navigate to
     * @return If the pathfinding was successfully started
     */
    default boolean setDestination(@Nonnull Location loc) {
        return setDestination(loc, 1);
    }

    /**
     * Calculates a destination for the Entity to navigate to, with desired speed
     * as the current target.
     * @param loc Location to navigate to
     * @param speed Speed multiplier to navigate at, where 1 is 'normal'
     * @return If the pathfinding was successfully started
     */
    default boolean setDestination(@Nonnull Location loc, double speed) {
        return setDestination(calculateDestination(loc), speed);
    }

    /**
     * Calculates a destination for the Entity to navigate to to reach the target entity,
     * and sets it with default speed.
     *
     * 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.
     *
     * However, this behavior is not guaranteed, and is subject to the games behavior.
     *
     * @param target the Entity to navigate to
     * @return If the pathfinding was successfully started
     */
    default boolean setDestination(@Nonnull LivingEntity target) {
        return setDestination(target, 1);
    }

    /**
     * Calculates a destination for the Entity to navigate to to reach the target entity,
     * and sets it with specified speed.
     *
     * 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.
     *
     * However, this behavior is not guaranteed, and is subject to the games behavior.
     *
     * @param target the Entity to navigate to
     * @param speed Speed multiplier to navigate at, where 1 is 'normal'
     * @return If the pathfinding was successfully started
     */
    default boolean setDestination(@Nonnull LivingEntity target, double speed) {
        return setDestination(calculateDestination(target), speed);
    }

    /**
     * Takes the result of a previous pathfinding calculation and sets it
     * as the active pathfinding with default speed.
     *
     * @param path The Path to start following
     * @return If the pathfinding was successfully started
     */
    default boolean setDestination(@Nonnull PathResult path) {
        return setDestination(path, 1);
    }

    /**
     * Takes the result of a previous pathfinding calculation and sets it
     * as the active pathfinding,
     *
     * @param path The Path to start following
     * @param speed Speed multiplier to navigate at, where 1 is 'normal'
     * @return If the pathfinding was successfully started
     */
    boolean setDestination(@Nonnull PathResult path, double speed);

    /**
     * Represents the result of a pathfinding calculation
     */
    interface PathResult {

        /**
         * If this path is targetting an entity, which entity is being followed
         * @return The Entity being followed
         */
        @Nullable LivingEntity getTarget();

        /**
         * @return The closest point the path can get to the target location
         */
        @Nullable Location getLocation();

        /**
         * All currently calculated points to follow along the path to reach the destination location
         *
         * Will return points the entity has already moved past, see {@link #getCurrentPointIndex()}
         * @return List of points
         */
        List<Location> getPoints();

        /**
         * @return Returns the index of the current point along the points returned in {@link #getPoints()}, or null
         * if we are done with this pathfinding.
         */
        @Nullable Integer getCurrentPointIndex();

        /**
         * @return The next location in the path points, or null if there is no next point
         */
        @Nullable Location getNextPointLocation();

    }
}