VisibilityChecker documentation

Author: emyfops

common/src/main/kotlin/com/lambda/interaction/visibilty/VisibilityChecker.kt

@@ -39,7 +39,20 @@ import net.minecraft.util.math.Vec3d
 import java.util.*
 import kotlin.math.pow
 
+/**
+ * Object for handling visibility checks, rotation calculations, and hit detection.
+ */
 object VisibilityChecker {
+
+    /**
+     * Attempts to rotate the player to look at a specified entity.
+     * The function calculates the best rotation to center the player's view on the bounding box of the given entity.
+     *
+     * @param rotationConfig Specifies the rotation configuration settings.
+     * @param interactionConfig Specifies interaction settings, such as range and resolution.
+     * @param entity The entity to be looked at.
+     * @return A [RotationContext] if a valid rotation was found; otherwise, null.
+     */
     fun SafeContext.lookAtEntity(
         rotationConfig: IRotationConfig,
         interactionConfig: InteractionConfig,
@@ -48,6 +61,16 @@ object VisibilityChecker {
         entityResult?.entity == entity
     }
 
+    /**
+     * Attempts to rotate the player to look at a specific block position.
+     * The function computes the best rotation to focus on a target block's position and side.
+     *
+     * @param blockPos The position of the block to look at.
+     * @param rotationConfig Specifies rotation configuration settings.
+     * @param interactionConfig Specifies interaction settings, such as range and resolution.
+     * @param sides Specifies the set of block sides to consider for targeting.
+     * @return A [RotationContext] if a valid rotation was found; otherwise, null.
+     */
     fun SafeContext.lookAtBlock(
         blockPos: BlockPos,
         rotationConfig: IRotationConfig = TaskFlow.rotation,
@@ -62,6 +85,18 @@ object VisibilityChecker {
         }
     }
 
+    /**
+     * Finds a rotation that intersects with one of the specified bounding boxes, allowing the player to look at entities or blocks.
+     *
+     * @param boxes List of bounding boxes for potential targets.
+     * @param rotationConfig Specifies rotation configuration settings.
+     * @param interact Specifies interaction settings, such as range and resolution.
+     * @param sides Set of block sides to consider for targeting.
+     * @param reach The maximum reach distance for the interaction.
+     * @param eye The player's eye position.
+     * @param verify A lambda to verify if a [HitResult] meets the desired criteria.
+     * @return A [RotationContext] if a valid rotation was found; otherwise, null.
+     */
     fun SafeContext.findRotation(
         boxes: List<Box>,
         rotationConfig: IRotationConfig,
@@ -109,6 +144,16 @@ object VisibilityChecker {
         return null
     }
 
+    /**
+     * Scans the visible surfaces of a given box, identifying points on each surface within a defined resolution.
+     * The surface is subdivided to hits the corners of the pixels
+     *
+     * @param eyes The player's eye position.
+     * @param box The bounding box of the target.
+     * @param sides Set of block sides to consider for visibility.
+     * @param resolution The number of points to sample along each axis of the box.
+     * @param check A lambda to check each visible point for a hit.
+     */
     inline fun scanVisibleSurfaces(
         eyes: Vec3d,
         box: Box,
@@ -134,11 +179,20 @@ object VisibilityChecker {
             }
     }
 
+    /**
+     * Computes the optimum point by averaging the vectors in a set of points.
+     */
     val Set<Vec3d>.optimum: Vec3d?
         get() = reduceOrNull { acc, vec3d ->
             acc.add(vec3d)
         }?.multiply(1.0 / size.toDouble())
 
+    /**
+     * Gets the bounding coordinates of a box's side, specifying min and max values for each axis.
+     *
+     * @param side The side of the box to calculate bounds for.
+     * @return An array of doubles representing the side's bounds.
+     */
     fun Box.bounds(side: Direction) =
         when (side) {
             Direction.DOWN -> doubleArrayOf(minX, minY, minZ, maxX, minY, maxZ)
@@ -149,12 +203,21 @@ object VisibilityChecker {
             Direction.EAST -> doubleArrayOf(maxX, minY, minZ, maxX, maxY, maxZ)
         }
 
+    /**
+     * Determines which surfaces of the box are visible from a specific position, typically the player's eyes.
+     *
+     * @param eyes The position to determine visibility from.
+     * @return A set of directions corresponding to visible sides.
+     */
     fun Box.getVisibleSurfaces(eyes: Vec3d) =
         EnumSet.noneOf(Direction::class.java)
             .checkAxis(eyes.x - center.x, lengthX / 2, Direction.WEST, Direction.EAST)
             .checkAxis(eyes.y - center.y, lengthY / 2, Direction.DOWN, Direction.UP)
             .checkAxis(eyes.z - center.z, lengthZ / 2, Direction.NORTH, Direction.SOUTH)
 
+    /**
+     * Helper function to add visible sides to an EnumSet based on positional differences.
+     */
     private fun EnumSet<Direction>.checkAxis(
         diff: Double,
         limit: Double,