Added better kdoc and standard entity search

Author: emyfops

common/src/main/kotlin/com/lambda/util/world/EntityUtils.kt

@@ -8,32 +8,34 @@ import net.minecraft.util.math.Vec3d
 import kotlin.math.ceil
 
 
-/**
- * Utility class for working with entities in a Minecraft environment.
- */
 object EntityUtils {
-
-    /**
-     * Gets the closest entity of type [T] within a specified range.
-     *
-     * @param pos The position to search from.
-     * @param range The maximum distance to search for entities.
-     * @param predicate Optional predicate to filter entities.
-     * @return The closest entity of type [T] within the specified range, or null if none is found.
-     */
-    inline fun <reified T : Entity> SafeContext.getClosestEntity(
-        pos: Vec3d,
-        range: Double,
-        noinline predicate: (T) -> Boolean = { true },
-    ): T? = getFastEntities(pos, range, predicate).firstOrNull { it.pos.squaredDistanceTo(pos) <= range * range }
-
     /**
      * Gets all entities of type [T] within a specified distance from a position.
      *
+     * This function retrieves entities of type [T] within a specified distance from a given position. It efficiently
+     * queries nearby chunks based on the distance and returns a list of matching entities, excluding the player entity.
+     *
+     *
+     * Getting all Zombie entities within a certain distance:
+     * ```
+     * val nearbyZombies = getFastEntities<ZombieEntity>(playerPos, 20.0)
+     * ```
+     *
+     * Getting all hostile entities within a certain distance:
+     * ```
+     * val hostileEntities = getFastEntities<HostileEntity>(playerPos, 30.0)
+     * ```
+     * This fetches all hostile entities (e.g., Monsters) within a 30-block radius from the player's position.
+     *
+     * Please note that this implementation is optimized for performance at small distances. For larger distances, it is
+     * recommended to use the [getEntities] function instead.
+     * With the time complexity, we can determine that after 64 blocks, the performance of this function will degrade.
+     *
      * @param pos The position to search from.
      * @param distance The maximum distance to search for entities.
-     * @param predicate Optional predicate to filter entities.
-     * @return A list of entities of type [T] within the specified distance from the position.
+     * @param predicate Optional predicate to filter entities. It allows custom filtering based on entity properties.
+     * @return A list of entities of type [T] within the specified distance from the position, excluding the player.
+     *
      */
     inline fun <reified T : Entity> SafeContext.getFastEntities(
         pos: Vec3d,
@@ -61,4 +63,23 @@ object EntityUtils {
 
         return entities
     }
+
+    /**
+     * Gets all entities of type [T] within a specified distance from a position.
+     *
+     * This function retrieves entities of type [T] within a specified distance from a given position. Unlike
+     * [getFastEntities], it traverses all entities in the world to find matches, while also excluding the player entity.
+     *
+     * @param predicate Optional predicate to filter entities.
+     * @return A list of entities of type [T] within the specified distance from the position without the player.
+     */
+    inline fun <reified T : Entity> SafeContext.getEntities(noinline predicate: (T) -> Boolean = { true }): List<T> {
+        val entities = ArrayList<T>()
+
+        world.entities.filterIsInstanceTo(entities) { entity ->
+            entity != player && predicate(entity)
+        }
+
+        return entities
+    }
 }