Refactored Bounds API

api/src/main/java/module-info.java

@@ -3,10 +3,11 @@
 @NullMarked
 module net.thenextlvl.portals {
     exports net.thenextlvl.portals.action;
+    exports net.thenextlvl.portals.bounds;
     exports net.thenextlvl.portals.event;
-    exports net.thenextlvl.portals.model;
     exports net.thenextlvl.portals.selection;
     exports net.thenextlvl.portals.shape;
+    exports net.thenextlvl.portals.view;
     exports net.thenextlvl.portals;
 
     requires core.paper;

api/src/main/java/net/thenextlvl/portals/action/ActionTypes.java

@@ -2,7 +2,7 @@
 
 import net.thenextlvl.binder.StaticBinder;
 import net.thenextlvl.portals.PortalLike;
-import net.thenextlvl.portals.model.Bounds;
+import net.thenextlvl.portals.bounds.Bounds;
 import org.bukkit.Location;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;

api/src/main/java/net/thenextlvl/portals/bounds/Bounds.java

@@ -0,0 +1,136 @@
+package net.thenextlvl.portals.bounds;
+
+import io.papermc.paper.math.BlockPosition;
+import net.kyori.adventure.key.Key;
+import net.thenextlvl.binder.StaticBinder;
+import org.bukkit.Location;
+import org.bukkit.World;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.CheckReturnValue;
+import org.jetbrains.annotations.Contract;
+import org.jspecify.annotations.Nullable;
+
+import java.util.Optional;
+import java.util.Random;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Represents a bounding box for teleportation.
+ *
+ * @since 0.2.0
+ */
+@ApiStatus.NonExtendable
+public interface Bounds {
+    /**
+     * Gets the factory for creating Bounds instances.
+     *
+     * @return The bounds factory.
+     * @since 0.2.0
+     */
+    static @CheckReturnValue BoundsFactory factory() {
+        return StaticBinder.getInstance(BoundsFactory.class.getClassLoader()).find(BoundsFactory.class);
+    }
+
+    /**
+     * Gets the world the bounds are in.
+     * <p>
+     * May be empty if the world is not loaded.
+     *
+     * @return The world.
+     * @since 0.2.0
+     */
+    Optional<World> world();
+
+    /**
+     * Gets the world key.
+     *
+     * @return The world key.
+     * @since 0.2.0
+     */
+    @Contract(pure = true)
+    Key worldKey();
+
+    /**
+     * Gets the minimum position of the bounds.
+     *
+     * @return the minimum position of the bounds
+     * @since 0.2.0
+     */
+    @Contract(value = " -> new", pure = true)
+    BlockPosition minPosition();
+
+    /**
+     * Gets the maximum position of the bounds.
+     *
+     * @return the maximum position of the bounds
+     * @since 0.2.0
+     */
+    @Contract(value = " -> new", pure = true)
+    BlockPosition maxPosition();
+
+    /**
+     * Gets the minimum X coordinate of the bounds.
+     *
+     * @return the minimum X coordinate of the bounds
+     * @since 0.2.0
+     */
+    int minX();
+
+    /**
+     * Gets the minimum Y coordinate of the bounds.
+     *
+     * @return the minimum Y coordinate of the bounds
+     * @since 0.2.0
+     */
+    int minY();
+
+    /**
+     * Gets the minimum Z coordinate of the bounds.
+     *
+     * @return the minimum Z coordinate of the bounds
+     * @since 0.2.0
+     */
+    int minZ();
+
+    /**
+     * Gets the maximum X coordinate of the bounds.
+     *
+     * @return the maximum X coordinate of the bounds
+     * @since 0.2.0
+     */
+    int maxX();
+
+    /**
+     * Gets the maximum Y coordinate of the bounds.
+     *
+     * @return the maximum Y coordinate of the bounds
+     * @since 0.2.0
+     */
+    int maxY();
+
+    /**
+     * Gets the maximum Z coordinate of the bounds.
+     *
+     * @return the maximum Z coordinate of the bounds
+     * @since 0.2.0
+     */
+    int maxZ();
+
+    /**
+     * Searches for a safe location within the bounds using a smart algorithm.
+     * <p>
+     * The algorithm works as follows:
+     * <ol>
+     *   <li>Pick a random X and Z coordinate within the bounds</li>
+     *   <li>Pick a random Y coordinate and search up and down for a safe location</li>
+     *   <li>If no safe location is found within height bounds, try a new X coordinate</li>
+     *   <li>If still no safe location is found, try a new Z coordinate</li>
+     *   <li>If still no safe location is found, try both new X and Z coordinates</li>
+     * </ol>
+     *
+     * @param random The random number generator.
+     * @return A CompletableFuture that completes with a safe location, or {@code null} if none is found.
+     * @since 0.2.0
+     */
+    CompletableFuture<@Nullable Location> searchSafeLocation(Random random);
+}

api/src/main/java/net/thenextlvl/portals/bounds/BoundsFactory.java

@@ -0,0 +1,91 @@
+package net.thenextlvl.portals.bounds;
+
+import io.papermc.paper.math.Position;
+import net.kyori.adventure.key.Key;
+import org.bukkit.World;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.Contract;
+
+/**
+ * Factory for creating Bounds instances.
+ *
+ * @since 0.2.0
+ */
+@ApiStatus.NonExtendable
+public interface BoundsFactory {
+    /**
+     * Creates new Bounds for teleportation to happen within.
+     *
+     * @param world The key of the world the teleport will happen in.
+     * @param minX  The minimum X coordinate.
+     * @param minY  The minimum Y coordinate.
+     * @param minZ  The minimum Z coordinate.
+     * @param maxX  The maximum X coordinate.
+     * @param maxY  The maximum Y coordinate.
+     * @param maxZ  The maximum Z coordinate.
+     * @since 0.2.0
+     */
+    @Contract(value = "_, _, _, _, _, _, _ -> new", pure = true)
+    Bounds of(Key world, int minX, int minY, int minZ, int maxX, int maxY, int maxZ);
+
+    /**
+     * Creates new Bounds for teleportation to happen within.
+     *
+     * @param world The world the teleport will happen in.
+     * @param minX  The minimum X coordinate.
+     * @param minY  The minimum Y coordinate.
+     * @param minZ  The minimum Z coordinate.
+     * @param maxX  The maximum X coordinate.
+     * @param maxY  The maximum Y coordinate.
+     * @param maxZ  The maximum Z coordinate.
+     * @since 0.2.0
+     */
+    @Contract(value = "_, _, _, _, _, _, _ -> new", pure = true)
+    Bounds of(World world, int minX, int minY, int minZ, int maxX, int maxY, int maxZ);
+
+    /**
+     * Creates new Bounds for teleportation to happen within.
+     *
+     * @param key The world key.
+     * @param min The minimum position.
+     * @param max The maximum position.
+     * @since 0.2.0
+     */
+    @Contract(value = "_, _, _ -> new", pure = true)
+    Bounds of(Key key, Position min, Position max);
+
+    /**
+     * Creates new Bounds for teleportation to happen within.
+     *
+     * @param world The world.
+     * @param min   The minimum position.
+     * @param max   The maximum position.
+     * @since 0.2.0
+     */
+    @Contract(value = "_, _, _ -> new", pure = true)
+    Bounds of(World world, Position min, Position max);
+
+    /**
+     * Creates new Bounds based on a center position, radius, and height.
+     *
+     * @param world  The key of the world.
+     * @param center The center position.
+     * @param radius The radius.
+     * @param height The height.
+     * @since 0.2.0
+     */
+    @Contract(value = "_, _, _, _ -> new", pure = true)
+    Bounds radius(Key world, Position center, int radius, int height);
+
+    /**
+     * Creates new Bounds based on a center position, radius, and height.
+     *
+     * @param world  The world.
+     * @param center The center position.
+     * @param radius The radius.
+     * @param height The height.
+     * @since 0.2.0
+     */
+    @Contract(value = "_, _, _, _ -> new", pure = true)
+    Bounds radius(World world, Position center, int radius, int height);
+}