namespace Mine.NET
{
    /**
     * The Travel Agent handles the creation and the research of Nether and End
     * portals when Entities try to use one.
     * <p>
     * It is used in {@link org.bukkit.event.entity.EntityPortalEvent} and in
     * {@link org.bukkit.event.player.PlayerPortalEvent} to help developers
     * reproduce and/or modify Vanilla behaviour.
     */
    public interface TravelAgent
    {

        /**
         * Set the Block radius to search in for available portals.
         *
         * @param radius the radius in which to search for a portal from the
         *     location
         * @return this travel agent
         */
        TravelAgent setSearchRadius(int radius);

        /**
         * Gets the search radius value for finding an available portal.
         *
         * @return the currently set search radius
         */
        int getSearchRadius();

        /**
         * Sets the maximum radius from the given location to create a portal.
         *
         * @param radius the radius in which to create a portal from the location
         * @return this travel agent
         */
        TravelAgent setCreationRadius(int radius);

        /**
         * Gets the maximum radius from the given location to create a portal.
         *
         * @return the currently set creation radius
         */
        int getCreationRadius();

        /**
         * Returns whether the TravelAgent will attempt to create a destination
         * portal or not.
         *
         * @return whether the TravelAgent should create a destination portal or
         *     not
         */
        bool getCanCreatePortal();

        /**
         * Sets whether the TravelAgent should attempt to create a destination
         * portal or not.
         *
         * @param create Sets whether the TravelAgent should create a destination
         *     portal or not
         */
        void setCanCreatePortal(bool create);

        /**
         * Attempt to find a portal near the given location, if a portal is not
         * found it will attempt to create one.
         *
         * @param location the location where the search for a portal should begin
         * @return the location of a portal which has been found or returns the
         *     location passed to the method if unsuccessful
         * @see #createPortal(Location)
         */
        Location findOrCreate(Location location);

        /**
         * Attempt to find a portal near the given location.
         *
         * @param location the desired location of the portal
         * @return the location of the nearest portal to the location
         */
        Location findPortal(Location location);

        /**
         * Attempt to create a portal near the given location.
         * <p>
         * In the case of a Nether portal teleportation, this will attempt to
         * create a Nether portal.
         * <p>
         * In the case of an Ender portal teleportation, this will (re-)create the
         * obsidian platform and clean blocks above it.
         *
         * @param location the desired location of the portal
         * @return true if a portal was successfully created
         */
        bool createPortal(Location location);
    }
}
